# Миграция в V1

Это руководство объясняет, как мигрировать с V0 на V1 для затронутых микросервисов.

# Изменения в услугах

# Запрос на удаленные предметы

Получите конечные точки, которые позволяют возвращать удаленные элементы, теперь имеются следующие запросы:

  • show_active - логический флаг (по умолчанию true), чтобы вернуть несущественные (то есть активные) элементы в корпусе ответа
  • show_deleted - логический флаг (по умолчанию false), чтобы вернуть удаленные элементы в корпусе ответа.

По умолчанию активные элементы будут возвращены только.

Чтобы вернуть только удаленные элементы, запросите со значением show_deleted true и show_active Значение false.

Чтобы вернуть как активные, так и удаленные элементы, запросите со значением show_deleted 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"
  }

# Параметр службы

Пожалуйста, используйте эти заметки о миграции, чтобы помочь переключиться с V0 parameter-service-api на 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 true, вы получите ошибку, если публикуете свойство 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"
          }
        ]
      ]
    }
    

# Записи

Запись представляет значение для параметра. Записи могут быть пересмотрены. В настоящее время параметры ограничены максимум до одной записи. В будущих версиях параметры будут иметь возможность иметь несколько записей. Пожалуйста, посмотрите документация (opens new window) Чтобы получить больше информации.

Есть четыре новых маршрута, связанных с записями:

# GET /entries

  • Эта конечная точка возвращает все записи, это запрашивается массивом parameter_id '.

# PUT /entries

  • Эта конечная точка заменяет POST /parameters/:parameter_id/revision и позволяет создавать или обновлять одну или несколько записей.
  • Эта конечная точка принимает массив entries. Требуемые поля: entry_id, parameter_id, source_id, values. В настоящее время values имеет максимальную длину одной. Дополнительные дополнения - 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 Convinting V1 Convention
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 в entries Post Body:
  • Если вы добавляете новую запись вбез ответаПараметр, это можно оставить пустым и автоматически заполнить новым 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

  • Добавлена страница. Пожалуйста, посмотрите Начальная секция Чтобы получить больше информации.

  • Ключ 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

  • Ответ unit_types для метода POST был обновлен так же, как 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

  • Добавлена страница. Пожалуйста, посмотрите Начальная секция Чтобы получить больше информации.

# Параметр метаданные услуга

Пожалуйста, используйте эти заметки о миграции, чтобы помочь переключиться с V0 parameter-metadata-service-api на V1. Этот документ должен подробно описать все изменения в версиях.

# Устаревшие конечные точки

Обратите внимание, что все конечные точки в V0 API устарели, поэтому пользователи должны перейти на следующую доступную версию

# Изменения в конечных точках

Пожалуйста, смотрите ниже изменения в каждой конечной точке. Это структурировано аналогично Документация API (opens new window) для простоты использования.

Примечание: не все конечные точки имели изменения.

# Allow Custom

  • allow_custom является новым ключом в корпусе ответа для всех объектов tag_type возвращаемых конечных точек. Это свойство означает, принимает ли A 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). Если это правда, это пропускает все глобальные теги (с 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 в качестве требуемого запроса
  • Эта конечная точка требует привилегий администратора.

# Контекст окружающей среды

Пожалуйста, используйте эти заметки о миграции, чтобы помочь переключиться с V0 Environmental-Context-Service-api на V1. Этот документ должен подробно описать все изменения в версиях.

# Устаревшие конечные точки

Обратите внимание, что все конечные точки в V0 этого API устарели, поэтому пользователи должны перейти на следующую доступную версию

Last Updated: 13.09.2023, 15:19:15