# 迁移到 V1

本指南为受影响的微服务说明了如何从 V0 到 V1 迁移。

# 跨服务的变化

# 查询已删除的项目

获取允许删除项目返回的终点，现在有以下查询：

show_active- 布尔旗（默认true）返回响应主体中的非删除（即活动）项目
show_deleted- 一个布尔标志（默认false）将返回响应主体中的已删除项目。

默认情况下，仅返回活动项目。

要仅返回已删除的项目，请请求show_deleted值true和_show_active value false。

要返回活动和删除的项目，请请求show_deleted value true。

注意：某些端点仅包含show_deleted查询，但行为是相同的。

# 分页

分页已添加到整个服务的多个路线中。这是如此大的回应可以合理地管理。

分页为任何分页端点添加了新查询：

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

在以前不存在的地方，order和sort_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的asset_sub_type_id之一：
如果您提供name，则asset_sub_type字段是可选的，如果剩余空白将自动填充以匹配asset_type_id名称。
如果仅提供asset_sub_type的资产 button*blaceholder *true的属性，则如果使用name属性不匹配有效的子类型名称的asset_type_id属性，则会收到错误。
现在，响应主体在asset_sub_type键中包含GET /assets/{asset_id}属性：


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"

}

# `asset_type_id`

现在，响应主体在asset_sub_type键中包含show_deleted_assets属性：


 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_ids}/hierarchy查询已更换。请看上面的部分了解更多信息

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

# `hierarchy`

每个asset_type_id响应主体中的对象现在包括GET /entries键：

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

# 条目

条目表示参数的值。可以修改条目。当前，参数仅限于最多一个条目。在将来的版本中，参数将具有多个条目的能力。请看文档 (opens new window) 了解更多信息。

有四个与条目有关的新路线：

# `parameter_id`

此端点返回所有条目，这是可以通过PUT /entries'的数组来查询的。

# `POST /parameters/:parameter_id/revision`

此端点替换entries，可让您创建或更新一个或多个条目。
该端点接受entry_id的数组。所需字段为parameter_id，source_id，values，_values。当前，comment的最大长度为 1。可选添加是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以更新
如果用户将修订版rejected更新为 QA 状态comment

# 参数集

注意：参数集在 Alpha 释放中进行测试。不建议在生产中使用这些路线。

参数集的命名约定已从 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_at，comment或location_in_source属性。

# `POST /parameters`

请求主体中的revision键已被entries替换，该键接受一个数组。
entry_id post 主体有一个可选entries键：
如果您将新条目添加到未得到答复参数，可以将其留为空，并会使用新的 UUID 自动填充。
如果您想修改回答参数，您必须提供现有的entry_id进行修改。

目前仅限于entries属性中的一个项目。

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_at，comment或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`

分页添加了。请看开始部分了解更多信息。
响应正文中 default_unit 属性上的 name 键已重命名为 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`

unit_types邮政方法的响应主体的更新方式与GET /unit_types- 有关详细信息，请参阅此部分。

# `GET /unit_types/:unit_type_id`

unit_type对象响应主体现在包括created_at，updated_at和_deleted_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有一个新的查询，这可以是一个或多个project_id的一个或多个，并将用给定的tag_scope返回所有标签。一个空的（null）查询字符串过滤器的所有标签，没有范围，即全局标签。
omit_global（bool）有一个新的查询。如果为 true，这将省略结果的所有全局标签（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删除标签。
此终点需要管理特权。

# 标签链接

# `GET /tags/:tag_id/links`

分页添加了。请看开始部分了解更多信息。
添加了用于检索已删除标签链接的新查询。请参见上面的部分了解更多信息。

# `GET /tags/:tag_id/links/:reference_id`

这是用户在资源之间获得现有标签链接的新端点。

# `PATCH /tags/{tag_id}/links/{reference_id}`

这是一个新的端点，可以在标签和参考之间更新链接reference_table和/或reference_url。

# `PUT /tag_links`

这是一个新的端点，允许用户放置新的和/或更新现有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 中的所有端点都被弃用，因此用户必须升级到下一个可用版本

← 版本迁移到 V2 →

# 迁移到 V1

# 跨服务的变化

# 查询已删除的项目

# 分页

# 错误消息

# 参数服务

# 弃用的端点

# GET /parameters/:parameter_id/revision

# POST /parameters/:parameter_id/revision

# PATCH /parameters/:parameter_id/revision

# 跨端点变化

# 资产

# GET /assets

# POST /assets

# asset_type_id

# hierarchy

# 条目

# parameter_id

# POST /parameters/:parameter_id/revision

# GET /parameters/:parameter_id/revision

# PATCH /parameters/:parameter_id/revisions

# 参数集

# GET /parameter_sets

# GET /parameter_sets/:parameter_set_id/parameters

# 参数

# GET /parameters

# POST /parameters

# GET /parameters/{parameter_id}

# 树

# GET /asset_tree

# GET /asset_type_tree

# 类型

# GET /asset_type_groups

# GET /asset_types

# GET /asset_types/{asset_type_id}/asset_sub_types

# GET /parameter_types

# GET /item_types

# GET /unit_types

# POST /unit_types

# GET /unit_types/:unit_type_id

# 单位

# GET /units

# POST /units

# GET /unit_systems

# 参数元数据服务

# 弃用的端点

# 跨端点变化

# Allow Custom

# 标签

# GET /tags

# POST /tags

# GET /tags/:tag_id

# PATCH /tags/:tag_id

# DELETE /tags/:tag_id

# 标签链接

# GET /tags/:tag_id/links

# GET /tags/:tag_id/links/:reference_id

# PATCH /tags/{tag_id}/links/{reference_id}

# PUT /tag_links

# 标签类型

# GET /tag_types

# POST /tag_types

# GET /tag_types/:tag_type_id

# PATCH /tag_types/{tag_type_id}

# DELETE /tag_types/{tag_type_id}

# 环境环境服务

# 弃用的端点

# `GET /parameters/:parameter_id/revision`

# `POST /parameters/:parameter_id/revision`

# `PATCH /parameters/:parameter_id/revision`

# `GET /assets`

# `POST /assets`

# `asset_type_id`

# `hierarchy`

# `parameter_id`

# `POST /parameters/:parameter_id/revision`

# `GET /parameters/:parameter_id/revision`

# `PATCH /parameters/:parameter_id/revisions`

# `GET /parameter_sets`

# `GET /parameter_sets/:parameter_set_id/parameters`

# `GET /parameters`

# `POST /parameters`

# `GET /parameters/{parameter_id}`

# `GET /asset_tree`

# `GET /asset_type_tree`

# `GET /asset_type_groups`

# `GET /asset_types`

# `GET /asset_types/{asset_type_id}/asset_sub_types`

# `GET /parameter_types`

# `GET /item_types`

# `GET /unit_types`

# `POST /unit_types`

# `GET /unit_types/:unit_type_id`

# `GET /units`

# `POST /units`

# `GET /unit_systems`

# `Allow Custom`

# `GET /tags`

# `POST /tags`

# `GET /tags/:tag_id`

# `PATCH /tags/:tag_id`

# `DELETE /tags/:tag_id`

# `GET /tags/:tag_id/links`

# `GET /tags/:tag_id/links/:reference_id`

# `PATCH /tags/{tag_id}/links/{reference_id}`

# `PUT /tag_links`

# `GET /tag_types`

# `POST /tag_types`

# `GET /tag_types/:tag_type_id`

# `PATCH /tag_types/{tag_type_id}`

# `DELETE /tag_types/{tag_type_id}`