# V1 への移行

このガイドでは、影響を受けるマイクロサービスのために、V0 から V1 に移動する方法について説明します。

# サービス全体の変更

# 削除されたアイテムのクエリ

削除されたアイテムを返すことを可能にするエンドポイントを取得すると、次のクエリが利用可能になりました。

  • show_active-応答ボディの非削除(アクティブ)アイテムを返すためのブールフラグ(デフォルトtrue
  • show_deleted-応答ボディの削除されたアイテムを返すブールフラグ(デフォルトfalse)。

デフォルトでは、アクティブアイテムは返品のみに返されます。

削除されたアイテムのみを返すには、show_deletedtrueおよびshow_activefalseでリクエストします。

アクティブアイテムと削除されたアイテムの両方を返すには、show_deletedtrueでリクエストします。

注:一部のエンドポイントには、show_deletedクエリのみが含まれていますが、動作は同じです。

# ページネーション

ページネーションは、サービス全体のいくつかのルートに追加されました。 これは非常に大きな応答で合理的に管理できます。

ページネーションは、任意のページングされたエンドポイントに新しいクエリを追加します。

+ ?page_limit=int
+ ?before=base64
+ ?after=base64

以前に存在しなかった場合、ordersort_byの新しいクエリも、普及したエンドポイントに存在します。

+ ?sort_by=name
+ ?order=desc

これらのクエリの詳細については、ドキュメントをご覧ください。

パジネートされたエンドポイントの応答本体も、新しいキーで更新されています。

+ paging: {
+     cursors: {
+       before: "MjUxYjYzNzAtNDk1MC1lNzExLTgxMDQtMDA1MDU2YjU3NDU5",
+       after: "OGExMTcxNzAtNDk1MC1lNzExLTgxMDQtMDA1MDU2YjU3NDU5"
+     },
+     previous: "http://ddb.arup.com/api/projects?before=MjUxYjYzNzAtNDk1MC1lNzExLTgxMDQtMDA1MDU2YjU3NDU5",
+     next: "http://ddb.arup.com/api/projects?after=MjUxYjYzNzAtNDk1MC1lNzExLTgxMDQtMDA1MDU2YjU3NDU5"
+   },
+   summary: {
+     estimate_count: 44
+  }

# エラーメッセージ

クライアントエラー応答には、sourceキーが含まれなくなりました。

  {
    details: "id \"632f6133-c5c4-4232-bdb6-c1a227a48b8e\" could not be found",
    msg: "Route Not Found",
-   source: "body"
  }

# パラメーターサービス

これらの移行ノートを使用して、parameter-service-apiの V0 から V1 に切り替えるのに役立ちます。 このセクションでは、バージョン全体のすべての変更を詳しく説明する必要があります。

# 非推奨エンドポイント

次のエンドポイントは V1 から削除されました。

# **GET /parameters/:parameter_id/revision**

新しいエンドポイントに置き換えられましたGET /entries/:entry_id/revisions(以下を参照)

# **POST /parameters/:parameter_id/revision**

新しいエンドポイントPUT /entriesに置き換えられました(以下を参照)

# **PATCH /parameters/:parameter_id/revision**

新しいエンドポイントに置き換えられましたPATCH /revisions(以下を参照)

# エンドポイント全体で変更されます

各エンドポイントの変更については、以下をご覧ください。 これは、と同様の方法で構成されています API ドキュメント (opens new window) 使いやすさ。

注:すべてのエンドポイントに変更があったわけではありません。

# 資産

# GET /assets

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。

  • 応答本体には、asset_type_idキーにasset_sub_typeプロパティが含まれるようになりました。

    asset_sub_type: {
          id: "a7154e9a-9dd4-4983-a900-c172a3366544",
          name: "Domestic Hot Water",
    +     asset_type_id: "577cfd8d-8da0-4d78-b4a4-c81ab728d4bf",
          parent_asset_sub_type_id: "f2ac4d11-6854-4763-b26e-2b2c664390cb"
        }
    
  • show_deleted_assetsクエリが置き換えられました。 参照してください 上のセクション 詳細については

    - GET /assets?show_deleted_assets=true
    + GET /assets?show_deleted=true
    

# POST /assets

  • このエンドポイントは、リクエスト本体のasset_type_idまたはasset_sub_type_idの 1 つを受け入れるようになりました。

  • asset_sub_type_idを提供している場合、nameフィールドはオプションであり、asset_sub_type名と一致するように空白が自動的に入力されます。

  • asset_type_idプロパティのasset_sub_typeを持つ資産に対してのみtrueを提供する場合、有効なサブタイプ名の 1 つと一致しないnameプロパティを投稿する場合、エラーが表示されます。

  • 応答本体には、asset_type_idキーにasset_sub_typeプロパティが含まれるようになりました。

    asset_sub_type: {
          id: "a7154e9a-9dd4-4983-a900-c172a3366544",
          name: "Domestic Hot Water",
    +     asset_type_id: "577cfd8d-8da0-4d78-b4a4-c81ab728d4bf",
          parent_asset_sub_type_id: "f2ac4d11-6854-4763-b26e-2b2c664390cb"
        }
    

# GET /assets/{asset_id}

  • 応答本体には、asset_type_idキーにasset_sub_typeプロパティが含まれるようになりました。

    asset_sub_type: {
          id: "a7154e9a-9dd4-4983-a900-c172a3366544",
          name: "Domestic Hot Water",
    +     asset_type_id: "577cfd8d-8da0-4d78-b4a4-c81ab728d4bf",
          parent_asset_sub_type_id: "f2ac4d11-6854-4763-b26e-2b2c664390cb"
        }
    
  • show_deleted_assetsクエリが置き換えられました。 を参照してください 上のセクション 詳細については

    - GET /assets?show_deleted_assets=true
    + GET /assets?show_deleted=true
    

# GET /assets/{asset_ids}/hierarchy

  • 応答本体の各hierarchyオブジェクトには、asset_type_idキーが含まれるようになりました。

    {
      hierarchies: [
        [
          {
            id: "a3d5c386-9451-495e-9d3c-8ed152b1300f",
            name: "Wellington Place",
    +       asset_type_id: "a3d5c386-9451-495e-9d3c-8ed152b1300f"
          }
        ]
      ]
    }
    

# エントリ

エントリは、パラメーターの値を表します。 エントリは改訂できます。 現在、パラメーターは最大 1 つのエントリに制限されています。 将来のバージョンでは、パラメーターには複数のエントリを持つ能力があります。 を参照してください ドキュメンテーション (opens new window) 詳細については。

エントリに関連する 4 つの新しいルートがあります。

# GET /entries

  • このエンドポイントはすべてのエントリを返します。これは、parameter_idの配列でクエリです。

# PUT /entries

  • このエンドポイントはPOST /parameters/:parameter_id/revisionに置き換えられ、1 つ以上のエントリを作成または更新できます。
  • このエンドポイントは、entriesの配列を受け入れます。 必要なフィールドはentry_idparameter_idsource_idvaluesです。 現在、valuesの最大長は 1 つです。 オプションの追加はcommentおよびlocation_in_sourceです。

# GET /entries/:entry_id/revisions

  • このエンドポイントはGET /parameters/:parameter_id/revisionを置き換え、指定されたentry_idのすべての改訂を返します。

# PATCH /revisions

  • このエンドポイントは、PATCH /parameters/:parameter_id/revisionsエンドポイントを置き換え、ユーザーが複数の異なるエントリに関連する複数のリビジョンのstatusを一度に更新できるようにします。
  • ユーザーは、のみ更新する必要があります最新エントリの改訂
  • ユーザーは、リビジョンのrevision_idを更新する必要があります
  • ユーザーがリビジョンstatusを QA 状態に更新している場合rejected A commentプロパティが必要です。

# パラメーターセット

注:パラメーターセットは、テスト用にアルファリリース中です。 これらのルートを生産に使用することはお勧めしません。

パラメーターセットの命名規則は、V0 から V1 に変更されています。 変更は次のとおりです。

V0 命名規則 V1 命名規則
parameter_set_type parameter_set_category
parameter_set parameter_set_type
parameter_set_instance parameter_set

これにより、次の方法でルートが更新されました。

V0 ルート V1 ルート
GET /parameter_set_types GET /parameter_set_categories
GET /parameter_sets GET /parameter_set_types
POST /parameter_sets POST /parameter_set_types
DELETE /parameter_sets/:parameter_set_id DELETE /parameter_set_types/:parameter_set_type_id
POST /parameter_sets/:parameter_set_id/items POST /parameter_set_types/:parameter_set_type_id/items
DELETE //parameter_sets/:parameter_set_id/items/:item_type_id DELETE /parameter_set_types/:parameter_set_type_id/items/:item_type_id
GET /parameter_sets/:parameter_set_id/instances GET /parameter_sets
GET /parameter_sets/:parameter_set_id/instances/:instance_id GET /parameter_sets/:parameter_set_id
GET /parameter_sets/:parameter_set_id/instances/:instance_id/parameters GET /parameter_sets/:parameter_set_id/parameters

応答ボディのキーは、関連する方法で更新されています。 たとえば、GET /parameter_set_categories(以前はGET /parameter_set_typesとして知られていた)へのリクエストは、次の回答を返します。

{
- parameter_set_types: [ ... ]
+ parameter_set_categories: [ ... ]
}

すべてのエンドポイントは、同様の方法で動作する必要があります(以下に詳述されているエンドポイントを除く)。

# GET /parameter_sets

このエンドポイントは、V0 エンドポイントGET /parameter_sets/:parameter_set_id/instancesを置き換えます。 関連するparameter_set_type_idによってパラメーターセットをフィルタリングするには、エンドポイントのクエリを介して渡されます。

+ GET /parameter_sets?parameter_set_type_id=uuid

これにより、指定されたparameter_setsのすべてのparameter_set_type_idを返します。

# GET /parameter_sets/:parameter_set_id/parameters

このエンドポイントには、V0 バージョン(GET /parameter_sets/:parameter_set_id/instances/:instance_id/parameters)と比較して応答が減少しています。

{
- parameter_set_instance_parameters: [
+  parameter_set_parameters: [
    {
      ...parameter,
      parameter_type: {
        id,
        name,
        data_type,
        global_parameter,
-       unit_type_id,
-       created_at,
-       deleted_at,
-       updated_at
      },
      parents: [
        {
          id,
          asset_sub_type,
          children,
          name,
          parent,
          asset_type: {
            id,
            name,
            parent_id,
-           asset_sub_type,
-           asset_type_group,
-           created_at,
-           deleted_at,
          },
-         project_id,
-         deleted_at,
        }
      ]
    }
  ],
  ... rest
}

# パラメーター

# GET /parameters

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。

  • show_deleted_parametersクエリが置き換えられました。 を参照してください 上のセクション 詳細については

    - GET /parameters?show_deleted_parameters=true
    + GET /assets?show_deleted=true
    
  • offsetクエリが削除されました:

    - GET /parameters?offset=
    
  • 応答本体のrevisionキーは、selected_entryに変更されました。

    {
      parameters: [
        {
          ... parameter,
    -    revision: { ... }
    +     selected_entry: { ... }
        },
        ...
      ]
    }
    
  • selected_entry.sourceキーには、応答が減少しています

    source: {
              id: "286a550e-00bc-4b1e-8e20-71f96b43e9c6",
              created_at: "2022-07-18T16:00:53.182Z",
    -         updated_at: "2022-07-18T16:00:53.182Z",
    -         deleted_at: null,
    -         time: null,
              date_day: "15",
              date_month: "1",
              date_year: "2021",
              reference: "Assumption",
    -         reference_id: "90803033-268a-ea11-8129-005056b50c57",
    -         reference_table: "project",
    -         reference_url: "dev.ddb.arup.com/api/project",
    -         scope: "90803033-268a-ea11-8129-005056b50c57",
              title: "Assumption",
              url: "TBA",
              source_type: {
                id: "6a1292c7-a245-41cf-8872-46feb9a7fd11",
                name: "Assumption",
    -           visible: true,
    -           deleted_at: null
              }
            }
    
  • selected_entry.created_byキーには、応答が減少しています

    created_by: {
    -         staff_id: 12345,
              staff_name: "Arup Employee Name",
              email: "[email protected]",
    -         company_centre_arup_unit: "01-462 NOR Digital Services",
    -         location_name: "Edinburgh Office",
    -         grade_level: 3,
    -         my_people_page_url: "https://arup-my.sharepoint.com/PersonImmersive.aspx?accountname=i:0%83.f%7cmembership%[email protected]"
    },
    
  • selected_entryキーには、updated_atcommentまたはlocation_in_sourceプロパティがありません。

# POST /parameters

  • リクエスト本文のrevisionキーは、配列を受け入れるentriesに置き換えられています。
  • entry_idボディにオプションのentriesキーがあります:
  • 新しいエントリを追加している場合未回答パラメーター、これは空のままにすることができ、新しい UUID が自動的に入力されます。
  • あなたが改訂したい場合答えたパラメーターでは、既存のentry_idを提供して修正する必要があります。

これは現在、entriesプロパティのみの 1 つの項目に限定されています。

  • ポストレスポンスボディのrevisionキーは、selected_entryに変更されました

    - revision: { ... }
    + selected_entry: { ... }
    

# GET /parameters/{parameter_id}

  • show_deleted_parametersクエリが置き換えられました。 を参照してください 上のセクション 詳細については

    - GET /parameters/:parameter_id?show_deleted_parameters=true
    + GET /parameters/:parameter_id?show_deleted=true
    
  • 応答本体のrevisionキーはselected_entryに変更されました

    - revision: { ... }
    + selected_entry: { ... }
    
  • selected_entry.sourceキーには、応答が減少しています

    source: {
              id: "286a550e-00bc-4b1e-8e20-71f96b43e9c6",
              created_at: "2022-07-18T16:00:53.182Z",
    -         updated_at: "2022-07-18T16:00:53.182Z",
    -         deleted_at: null,
    -         time: null,
              date_day: "15",
              date_month: "1",
              date_year: "2021",
              reference: "Assumption",
    -         reference_id: "90803033-268a-ea11-8129-005056b50c57",
    -         reference_table: "project",
    -         reference_url: "dev.ddb.arup.com/api/project",
    -         scope: "90803033-268a-ea11-8129-005056b50c57",
              title: "Assumption",
              url: "TBA",
              source_type: {
                id: "6a1292c7-a245-41cf-8872-46feb9a7fd11",
                name: "Assumption",
    -           visible: true,
    -           deleted_at: null
              }
            }
    
  • selected_entry.created_byキーには、応答が減少しています

    created_by: {
    -         staff_id: 12345,
              staff_name: "Arup Employee Name",
              email: "[email protected]",
    -         company_centre_arup_unit: "01-462 NOR Digital Services",
    -         location_name: "Edinburgh Office",
    -         grade_level: 3,
    -         my_people_page_url: "https://arup-my.sharepoint.com/PersonImmersive.aspx?accountname=i:0%83.f%7cmembership%[email protected]"
    },
    
  • selected_entryキーには、updated_atcommentまたはlocation_in_sourceプロパティがありません。

#

ツリー階層を返すためのいくつかの新しいエンドポイントがあります。 を参照してください ドキュメンテーション (opens new window) これらのエンドポイントの詳細については。

# GET /asset_tree

  • asset_idで資産ツリーを返す新しいエンドポイント。

# GET /asset_type_tree

  • asset_type_idでアセットタイプツリーを返す新しいエンドポイント。

# 種類

# GET /asset_type_groups

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。

# GET /asset_types

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。

# GET /asset_types/{asset_type_id}/asset_sub_types

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。

# GET /parameter_types

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。

  • 応答本体のnameプロパティのdefault_unitキーは、symbolに変更されました。

    default_unit: {
          id: "b39e5bcf-cda6-49ed-8c0c-174d8daf8bc1",
    -     name: "°C",
    +     symbol: "°C",
          unit_type_id: "5391cd71-08f0-44f8-9dd2-6379a511dd29",
          unit_system_id: "50115948-140f-48fc-b5f2-c56e96869734"
          }
    

# GET /item_types

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。
  • offsetクエリが削除されました。

# GET /unit_types

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。

  • unit_typeオブジェクトには、その特定のタイプで利用可能なユニットシステムとユニットが含まれる新しいunit_systemsキーがあります

    unit_types: [
    {
    id: "e8c3da00-5c20-45f1-a24c-0d657bcae032",
    name: "Geotechnics analysis material type",
    created_at: "2022-06-24T12:26:00.263Z",
    updated_at: "2022-06-24T12:26:00.263Z",
    deleted_at: null,
    + unit_systems: [
    +  {
    +    id: "5508a780-9f9f-4e6d-bc9c-a84607a5ba87",
    +    name: "Drop-down list",
    +    short_name: "Drop-down",
    +    units: [
    +      {
    +        id: "892c32c1-808a-440a-8290-e05fdf5457ba",
    +        symbol: "Mohr-coulomb, linear-elastic"
    +      }
    +    ]
    +  }
    + ]
    }
    ]
    

# POST /unit_types

  • POST メソッドのunit_types応答本体は、GET /unit_typesと同じ方法で更新されています - 詳細については、このセクションを参照してください。

# GET /unit_types/:unit_type_id

  • unit_typeオブジェクト応答本体には、created_atupdated_atdeleted_atキーが含まれています。
unit_type: {
 id: "38f045f3-ce7a-4a38-9fe7-f9d72d07a129",
 name: "Area",
+ created_at: "2021-12-22T13:07:17.214Z",
+ updated_at: "2021-12-22T13:07:17.214Z",
+ deleted_at: null,
 unit_systems: [ ... ]
 }

# ユニット

# GET /units

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。

  • 応答本体のnameキーは、symbolに変更されました。

    {
      id: "a3d5c386-9451-495e-9d3c-8ed152b1300f",
      created_at: "2019-05-10T13:45:08.000Z",
      deleted_at: "2020-06-18T11:25:21.000Z",
    - name: "m",
    + symbol: "m",
      updated_at: "2020-06-12T13:39:41.000Z",
      unit_type_id: "7a857f03-a222-405c-bc03-90d6dcaa8e0e",
      unit_system_id: "50115948-140f-48fc-b5f2-c56e96869734"
    }
    

# POST /units

  • リクエスト本体は、nameフィールドを受け入れなくなりました。 これはsymbolになります:

    {
      id: "cdbcb4d1-b6c1-436c-8126-737c29c9b2f4",
    - name: "°F",
    + symbol: "°F",
      unit_type_id: "b68caf97-e537-4ce4-b3bd-7131f0e72e93",
      unit_system_id: "50115948-140f-48fc-b5f2-c56e96869734"
      }
    

# GET /unit_systems

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。

# パラメーターメタデータサービス

これらの移行ノートを使用して、parameter-metadata-service-apiの V0 から V1 に切り替えるのに役立ちます。 このドキュメントは、バージョン全体のすべての変更を詳述する必要があります。

# 非推奨エンドポイント

API の V0 のすべてのエンドポイントは非推奨であるため、ユーザーは次の利用可能なバージョンにアップグレードする必要があることに注意してください

# エンドポイント全体で変更されます

各エンドポイントの変更については、以下をご覧ください。 これは、と同様の方法で構成されています API ドキュメント (opens new window) 使いやすさ。

注:すべてのエンドポイントに変更があったわけではありません。

# Allow Custom

  • allow_customは、すべてのtag_typeオブジェクトが返されたエンドポイントの応答本体の新しいキーです。 このプロパティは、tag_typeがカスタムタグを受け入れるか、trueまたはfalseのブール値を使用しないかどうかを意味します。

    tag_type: {
            id: "1e08965a-f116-4a6d-8bba-74290edc8c0a",
            created_at: "2019-05-10T13:45:08.000Z",
            deleted_at: "2019-05-10T13:45:08.000Z",
            name: "Calculation",
            updated_at: "2019-05-10T13:45:08.000Z",
    +       allow_custom: false
          }
    

# 鬼ごっこ

# GET /tags

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。
  • 削除されたタグを取得するために追加された新しいクエリ。 参照してください 上のセクション 詳細については。
  • item_limitクエリは、ページネーションの一部としてpage_limitクエリに置き換えられました。
  • tag_scopeで利用可能な新しいクエリがあります。これは 1 つ以上のproject_id 'であり、指定されたtag_scopeですべてのタグを返します。 スコープなしのすべてのタグ、つまりグローバルタグの空の(null)クエリ文字列フィルター。
  • omit_global(bool)で利用可能な新しいクエリがあります。 真実の場合、これは結果からすべてのグローバルタグ(tag_scope = nullを持つもの)を省略します。 このクエリのデフォルト値はfalseです。
  • tag_typeの応答本体のtagオブジェクトには、allow_customの新しいキーが含まれるようになりました。 参照してください このセクション 詳細については。

# POST /tags

  • これは、ユーザーが新しいタグを追加できる新しいエンドポイントです。
  • すべてのユーザーは、プロジェクトにスコープされたカスタムタグを投稿できます(つまり、プロパティtag_typeおよびallow_custom: trueを備えたtag_scope: your-project-uuidを備えたタグ)。 グローバルタグを投稿するには、管理者特権が必要です。

# GET /tags/:tag_id

  • 応答本体のtag_typeオブジェクトには、allow_customの新しいキーが含まれるようになりました。 参照してください このセクション 詳細については。

# PATCH /tags/:tag_id

  • これは、タグnameプロパティを更新できる新しいエンドポイントです。
  • このエンドポイントには、管理者特権が必要です。

# DELETE /tags/:tag_id

  • これは、tag_idでタグを削除できる新しいエンドポイントです。
  • このエンドポイントには、管理者特権が必要です。

# タグリンク

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。
  • 削除されたタグリンクを取得するための新しいクエリが追加されました。 参照してください 上のセクション 詳細については。
  • これは、ユーザーがリソース間で既存のタグリンクを取得するための新しいエンドポイントです。
  • これは、タグと参照の間でリンクreference_tableおよび/またはreference_urlを更新するための新しいエンドポイントです。
  • これは、ユーザーが新規を配置したり、既存のtag_linkを更新できる新しいエンドポイントです。

# タグタイプ

# GET /tag_types

  • ページネーションが追加されました。 を参照してください 開始セクション 詳細については。
  • 削除されたタグタイプを取得するための新しいクエリが追加されました。 参照してください 上のセクション 詳細については。
  • 応答本体のtag_typeオブジェクトには、allow_customの新しいキーが含まれるようになりました。 参照してください このセクション 詳細については。

# POST /tag_types

  • これは、新しいtag_typeを追加できる新しいエンドポイントです。
  • このエンドポイントには、管理者特権が必要です。

# GET /tag_types/:tag_type_id

  • 応答本体のtag_typeオブジェクトには、allow_customの新しいキーが含まれるようになりました。 参照してください このセクション 詳細については。

# PATCH /tag_types/{tag_type_id}

  • これは、ユーザーが単一のtag_typeを更新できる新しいエンドポイントです。

*注:このエンドポイントには、管理者特権が必要です。 *

# DELETE /tag_types/{tag_type_id}
  • 必要なクエリとしてtag_type_idを使用して単一のタグタイプを削除する新しいエンドポイント
  • このエンドポイントには、管理者特権が必要です。

# 環境コンテキストサービス

これらの移行ノートを使用して、Environmental-Context-Service-apiの V0 から V1 に切り替えるのに役立ちます。 このドキュメントは、バージョン全体のすべての変更を詳述する必要があります。

# 非推奨エンドポイント

この API の V0 のすべてのエンドポイントは非推奨であるため、ユーザーは次の利用可能なバージョンにアップグレードする必要があることに注意してください

Last Updated: 2023/9/13 15:19:15