# Migración a V1

Esta guía explica cómo migrar de V0 a V1, para los microservicios afectados.

# Cambios en todos los servicios

# Consulta para artículos eliminados

Obtenga puntos finales que permitan la devolución de los elementos eliminados ahora tiene las siguientes consultas disponibles:

  • show_active - Una bandera booleana (predeterminada true) para devolver ítems no eliminados (es decir, activos) en el cuerpo de respuesta
  • show_deleted - Una bandera booleana (predeterminada false) para devolver elementos eliminados en el cuerpo de respuesta.

Por defecto, los elementos activos solo se devolverán.

Para devolver solo los elementos eliminados, solicite el valor show_deleted true y show_active Valor false.

Para devolver los elementos activos y eliminados, solicite el valor show_deleted true.

Nota: Algunos puntos finales contienen solo la consulta show_deleted, pero el comportamiento es el mismo.

# Paginación

La paginación se ha agregado a varias rutas en todos los servicios. Esto es tan grande que las respuestas se pueden gestionar razonablemente.

La paginación agrega nuevas consultas a cualquier punto final paginado:

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

Cuando no esté presente antes, las nuevas consultas de order y sort_by también estarán presentes en puntos finales paginados:

+ ?sort_by=name
+ ?order=desc

Consulte la documentación para obtener más información sobre estas consultas.

Los cuerpos de respuesta para los puntos finales paginados también se han actualizado con nuevas claves:

+ 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
+  }

# Error de mensajes

Las respuestas de error del cliente ya no incluyen la clave source:

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

# Servicio de parámetros

Utilice estas notas de migración para ayudar a cambiar de V0 del parameter-service-api a V1. Esta sección debe detallar todos los cambios en las versiones.

# Puntos finales desapercibidos

Los siguientes puntos finales se han eliminado de V1:

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

reemplazado por nuevo punto final GET /entries/:entry_id/revisions (ver más abajo)

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

reemplazado por nuevo punto final PUT /entries (ver más abajo)

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

reemplazado por nuevo punto final PATCH /revisions (ver más abajo)

# Cambios a través de puntos finales

Consulte a continuación los cambios en cada punto final. Esto está estructurado de manera similar al Documentación de API (opens new window) para facilitar el uso.

Nota: No todos los puntos finales han tenido cambios.

# Activos

# GET /assets

  • Paginación agregada. Por favor vea el sección inicial para más información.

  • El cuerpo de respuesta ahora incluye la propiedad asset_type_id en la clave 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"
        }
    
  • La consulta show_deleted_assets ha sido reemplazada. Por favor mira Sección de arriba para más información

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

# POST /assets

  • Este punto final ahora acepta uno de asset_type_id o asset_sub_type_id en el cuerpo de solicitud:

  • Si está proporcionando asset_sub_type_id, el campo name es opcional y si se deja en blanco se llenará automáticamente para que coincida con el nombre asset_sub_type.

  • Si proporciona un asset_type_id solo para un activo que tenga una propiedad asset_sub_type de true, recibirá un error si se publica con una propiedad name que no coincida con uno de los nombres de subpipos válidos.

  • El cuerpo de respuesta ahora incluye la propiedad asset_type_id en la clave 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}

  • El cuerpo de respuesta ahora incluye la propiedad asset_type_id en la clave 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"
        }
    
  • La consulta show_deleted_assets ha sido reemplazada. Por favor vea el Sección de arriba para más información

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

# GET /assets/{asset_ids}/hierarchy

  • Cada objeto hierarchy en el cuerpo de respuesta ahora incluye una clave asset_type_id:

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

# Entradas

Una entrada representa un valor para un parámetro. Se pueden revisar las entradas. Actualmente, los parámetros están restringidos al máximo de una entrada. En versiones futuras, los parámetros tendrán la capacidad de tener múltiples entradas. Por favor vea el documentación (opens new window) para más información.

Hay cuatro nuevas rutas relacionadas con las entradas:

# GET /entries

  • Este punto final devuelve todas las entradas, esto se puede consultar mediante una matriz de parameter_id.

# PUT /entries

  • Este punto final reemplaza POST /parameters/:parameter_id/revision y le permite crear o actualizar una o más entradas.
  • Este punto final acepta una matriz de entries. Los campos requeridos son entry_id, parameter_id, source_id, values. Actualmente, values tiene una longitud máxima de uno. Las adiciones opcionales son comment y location_in_source.

# GET /entries/:entry_id/revisions

  • Este punto final reemplaza GET /parameters/:parameter_id/revision y devuelve todas las revisiones para un entry_id especificado.

# PATCH /revisions

  • Este punto final reemplaza el punto final PATCH /parameters/:parameter_id/revisions y permite a los usuarios actualizar el status de múltiples revisiones relacionadas con múltiples entradas diferentes a la vez.
  • Los usuarios solo deben actualizar elel últimoRevisión de una entrada
  • Los usuarios deben especificar el revision_id de la revisión para actualizar
  • Si los usuarios están actualizando la revisión status a QA State rejected Se requiere una propiedad comment.

# Conjuntos de parámetros

Nota: Los conjuntos de parámetros están en liberación alfa para las pruebas. No se recomienda usar estas rutas en la producción.

Las convenciones de nombres para conjuntos de parámetros se han alterado de V0 a V1. Los cambios son los siguientes:

Convención de nombres V0 Convención de nombres V1
parameter_set_type parameter_set_category
parameter_set parameter_set_type
parameter_set_instance parameter_set

Esto ha resultado en la actualización de las rutas de la siguiente manera:

ruta V0 ruta 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

Las claves en los cuerpos de respuesta se han actualizado de la manera relevante. Por ejemplo, una solicitud a GET /parameter_set_categories (anteriormente conocida como GET /parameter_set_types) devolverá una respuesta con:

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

Todos los puntos finales deben comportarse de manera similar (excluyendo puntos finales detallados a continuación).

# GET /parameter_sets

Este punto final reemplaza el punto final V0 GET /parameter_sets/:parameter_set_id/instances. Para filtrar los conjuntos de parámetros por el parameter_set_type_id relevante, esto se pasa a través de una consulta en el punto final:

+ GET /parameter_sets?parameter_set_type_id=uuid

Esto devolverá todos parameter_sets del parameter_set_type_id especificado.

# GET /parameter_sets/:parameter_set_id/parameters

Este punto final contiene una respuesta reducida en comparación con la versión 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
}

# Parámetros

# GET /parameters

  • Paginación agregada. Por favor vea el sección inicial para más información.

  • La consulta show_deleted_parameters ha sido reemplazada. Por favor vea el Sección de arriba para más información

    - GET /parameters?show_deleted_parameters=true
    + GET /assets?show_deleted=true
    
  • Se ha eliminado la consulta offset:

    - GET /parameters?offset=
    
  • La clave revision en el cuerpo de respuesta ha sido renombrado a selected_entry:

    {
      parameters: [
        {
          ... parameter,
    -    revision: { ... }
    +     selected_entry: { ... }
        },
        ...
      ]
    }
    
  • La tecla selected_entry.source contiene una respuesta reducida

    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
              }
            }
    
  • La tecla selected_entry.created_by contiene una respuesta reducida

    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]"
    },
    
  • La clave selected_entry no tiene una propiedad updated_at, comment o location_in_source.

# POST /parameters

  • La clave revision en el cuerpo de solicitud ha sido reemplazada por entries, que acepta una matriz.
  • Hay una tecla entry_id opcional en el cuerpo post entries:
  • Si está agregando una nueva entrada a unsin respuestaParámetro, esto se puede dejar vacío y se llenará automáticamente con un nuevo UUID.
  • Si desea revisar uncontestadaParámetro, debe proporcionar el entry_id existente para revisar.

Esto se limita actualmente a un elemento en la propiedad entries solamente.

  • La clave revision en el cuerpo de respuesta posterior ahora se renombra a selected_entry

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

# GET /parameters/{parameter_id}

  • La consulta show_deleted_parameters ha sido reemplazada. Por favor vea el Sección de arriba para más información

    - GET /parameters/:parameter_id?show_deleted_parameters=true
    + GET /parameters/:parameter_id?show_deleted=true
    
  • La clave revision en el cuerpo de respuesta ha sido renombrado a selected_entry

    - revision: { ... }
    + selected_entry: { ... }
    
  • La tecla selected_entry.source contiene una respuesta reducida

    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
              }
            }
    
  • La tecla selected_entry.created_by contiene una respuesta reducida

    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]"
    },
    
  • La clave selected_entry no tiene una propiedad updated_at, comment o location_in_source.

# Árbol

Hay varios puntos finales nuevos para devolver las jerarquías de árboles. Por favor vea el documentación (opens new window) Para obtener más información sobre estos puntos finales.

# GET /asset_tree

  • Nuevo punto final que devuelve un árbol de activos por asset_id.

# GET /asset_type_tree

  • Nuevo punto final que devuelve un árbol de tipo de activo por asset_type_id.

# Tipos

# GET /asset_type_groups

# GET /asset_types

# GET /asset_types/{asset_type_id}/asset_sub_types

# GET /parameter_types

  • Paginación agregada. Por favor vea el sección inicial para más información.

  • La clave name en la propiedad default_unit en el cuerpo de respuesta ha sido renombrado a 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

  • Paginación agregada. Por favor vea el sección inicial para más información.
  • Se ha eliminado la consulta offset.

# GET /unit_types

  • Paginación agregada. Por favor vea el sección inicial para más información.

  • Cada objeto unit_type tiene una nueva tecla unit_systems, que contiene los sistemas y unidades de la unidad que están disponibles para ese tipo particular

    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

  • El cuerpo de respuesta unit_types para el método de publicación se ha actualizado de la misma manera que el GET /unit_types; consulte esta sección para más detalles.

# GET /unit_types/:unit_type_id

  • El cuerpo de respuesta del objeto unit_type ahora incluye las teclas created_at, updated_at y 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: [ ... ]
 }

# Unidades

# GET /units

  • Paginación agregada. Por favor vea el sección inicial para más información.

  • La clave name en el cuerpo de respuesta ha sido renombrado a 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

  • El cuerpo de solicitud ya no acepta un campo name. Esto debería ser 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

# Servicio de metadatos de parámetros

Utilice estas notas de migración para ayudar a cambiar de V0 del parameter-metadata-service-api a V1. Este documento debe detallar todos los cambios en las versiones.

# Puntos finales desapercibidos

Tenga en cuenta que todos los puntos finales en V0 de la API están en desuso para que los usuarios deben actualizar a la próxima versión disponible

# Cambios a través de puntos finales

Consulte a continuación los cambios en cada punto final. Esto está estructurado de manera similar al Documentación de API (opens new window) para facilitar el uso.

Nota: No todos los puntos finales han tenido cambios.

# Allow Custom

  • allow_custom es una nueva clave en el cuerpo de respuesta para todos los objetos tag_type devueltos de puntos finales. Esta propiedad significa si un tag_type acepta etiquetas personalizadas o no usa un valor booleano de true o 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
          }
    

# Etiqueta

# GET /tags

  • Paginación agregada. Por favor vea el sección inicial para más información.
  • Nuevas consultas agregadas para recuperar etiquetas eliminadas. Por favor mira Sección de arriba para más información.
  • La consulta item_limit ha sido reemplazada por la consulta page_limit como parte de la paginación.
  • Hay una nueva consulta disponible para tag_scope, esta puede ser una o más project_id 'y devolverá todas las etiquetas con el tag_scope dado. Una cadena de consulta vacía (null) se filtra para todas las etiquetas sin alcance, es decir, etiquetas globales.
  • Hay una nueva consulta disponible para omit_global (bool). Si es cierto, esto omite todas las etiquetas globales (aquellas con tag_scope = null) del resultado. El valor predeterminado para esta consulta es false.
  • El objeto tag_type en el cuerpo de respuesta para un tag ahora incluye una nueva clave de allow_custom. Por favor mira esta sección para más información.

# POST /tags

  • Este es un nuevo punto final que permite a los usuarios agregar una nueva etiqueta.
  • Cualquier usuario puede publicar una etiqueta personalizada que se alcance a un proyecto (es decir, una etiqueta que tiene tag_type con propiedad allow_custom: true y tag_scope: your-project-uuid). Publicar etiquetas globales requiere privilegios de administración.

# GET /tags/:tag_id

  • El objeto tag_type en el cuerpo de respuesta ahora incluye una nueva clave de allow_custom. Por favor mira esta sección para más información.

# PATCH /tags/:tag_id

  • Este es un nuevo punto final que le permite actualizar una propiedad de etiqueta name.
  • Este punto final requiere privilegios de administración.

# DELETE /tags/:tag_id

  • Este es un nuevo punto final que le permite eliminar una etiqueta en tag_id.
  • Este punto final requiere privilegios de administración.

# Enlaces de etiqueta

  • Paginación agregada. Por favor vea el sección inicial para más información.
  • Nuevas consultas agregadas para recuperar enlaces de etiqueta eliminados. Por favor mira Sección de arriba para más información.
  • Este es un nuevo punto final para que los usuarios obtengan un enlace de etiqueta existente entre los recursos.
  • Este es un nuevo punto final para actualizar un enlace reference_table y/o reference_url entre una etiqueta y referencia.
  • Este es un nuevo punto final que permite a los usuarios colocar y/o actualizar el tag_link existente.

# Tipo de etiqueta

# GET /tag_types

  • Paginación agregada. Por favor vea el sección inicial para más información.
  • Nuevas consultas agregadas para recuperar los tipos de etiquetas eliminadas. Por favor mira Sección de arriba para más información.
  • Los objetos tag_type en el cuerpo de respuesta ahora incluyen una nueva clave de allow_custom. Por favor mira esta sección para más información.

# POST /tag_types

  • Este es un nuevo punto final que le permite agregar un nuevo tag_type.
  • Este punto final requiere privilegios de administración.

# GET /tag_types/:tag_type_id

  • El objeto tag_type en el cuerpo de respuesta ahora incluye una nueva clave de allow_custom. Por favor mira esta sección para más información.

# PATCH /tag_types/{tag_type_id}

  • Este es un nuevo punto final que permite a los usuarios actualizar un solo tag_type.

*Nota: Este punto final requiere privilegios de administración. *

# DELETE /tag_types/{tag_type_id}
  • Nuevo punto final que elimina un solo tipo de etiqueta usando el tag_type_id como una consulta requerida
  • Este punto final requiere privilegios de administración.

# Servicio de contexto del medio ambiente

Utilice estas notas de migración para ayudar a cambiar de V0 del Environmental-Context-Service-api a V1. Este documento debe detallar todos los cambios en las versiones.

# Puntos finales desapercibidos

Tenga en cuenta que todos los puntos finales en V0 de esta API están en desuso para que los usuarios deben actualizar a la próxima versión disponible

Last Updated: 24/9/2024, 16:41:45