Saltar al contenido principal

Servicios Cognite OData

Cognite proporciona servicios OData para obtener datos de Cognite Data Fusion (CDF) utilizando clientes OData como Microsoft Power BI, Microsoft Excel y TIBCO Spotfire.

Open Data Protocol (OData) es un estándar abierto que define buenas prácticas para crear y consumir API RESTful. OData ofrece:

  • Sintaxis de consulta estandarizada: Permite filtrado, ordenación, paginación y proyecciones consistentes entre diferentes fuentes de datos.

  • Compatibilidad con metadatos: Los clientes pueden descubrir la estructura y los tipos de datos a través de documentos de metadatos.

  • Interoperabilidad: Cualquier cliente que admita HTTP y comprenda OData puede consumir servicios OData.

Cognite proporciona un servicio centrado en activos OData y un servicio de modelado de datosOData. Ambos servicios envuelven las API estándar de Cognite e implementan una OData Version 4 API para fines de solo lectura. Traducen las solicitudes OData en llamadas correspondientes a la Cognite API, lo que le permite interactuar con datos CDF mediante herramientas y clientes compatibles con OData.

Uso de los servicios OData​

Para interactuar con los servicios OData de Cognite, debe realizar solicitudes HTTP GET a puntos de conexión específicos.

Autenticación​

Para autenticarse con los servicios OData, debe incluir un token de portador en el encabezado de autorización de sus solicitudes HTTP.

Por ejemplo:

Authorization: Bearer {YourAccessToken}

Puede obtener un token de acceso mediante el flujo de autenticación adecuado para su configuración (por ejemplo, OAuth 2.0, OpenID Connect). Para obtener más detalles, consulte la Documentación de autenticación.

Hacer solicitudes​

Ejemplo de solicitud GET​

Para recuperar todos los activos de un proyecto:

GET https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/Assets

Donde:

  • {cluster}: El nombre del clúster CDF (por ejemplo, westeurope-1).
  • {apiVersion}: La versión de la API del servicio OData (por ejemplo, v1).
  • {project}: El nombre de su proyecto CDF.
Parámetros de consulta​

Use parámetros de consulta para filtrar, ordenar, seleccionar y paginar datos.

  • Filtrado: use el parámetro de consulta $filter para filtrar datos.

    Ejemplo: Recuperar activos donde Name es igual a 'Pump 1': GET .../Assets?$filter=Name eq 'Pump 1'

  • Selección de campos: use el parámetro de consulta $select para recuperar campos específicos.

    Ejemplo: Recuperar solo el Id y el Name de los activos: GET .../Assets?$select=Id,Name

  • Clasificación: use el parámetro de consulta $orderby para ordenar los resultados.

    Ejemplo: Ordenar activos por Name en orden ascendente: GET .../Assets?$orderby=Name asc

  • Expansión de entidades relacionadas: use el parámetro de consulta $expand para incluir entidades relacionadas. Ejemplo: Recuperar un activo junto con su elemento principal: GET .../Assets(702630644612)/Parent?$expand=Parent

    Nota: No todas las entidades y relaciones admiten la expansión. Consulte la documentación de cada servicio para obtener más detalles.

  • Combinación de parámetros de consulta: puede combinar varios parámetros de consulta para refinar su solicitud.

    Ejemplo: Recuperar Id y Name de los activos donde Name comienza con 'Pump', ordenados por Name, y recuperar los primeros 10 resultados: GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

Formato de respuesta​

Los servicios OData devuelven respuestas en formato JSON, siguiendo el estándar OData V4.

Respuesta de ejemplo:

{
  "@odata.context": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/$metadata#Assets/",
  "value": [
    {
      "Id": "12345",
      "DataSetId": null,
      "ExternalId": "WMT:VAL",
      "Name": "Pump 1",
      "Description": "Main pump"
      // other properties
    }
  ]
}
Paginación en respuestas​

Si los conjuntos de resultados son grandes, el servicio OData puede paginar la respuesta. La respuesta incluye una propiedad @odata.nextLink con una URL para recuperar la siguiente página de resultados.

Ejemplo:

{
  "@odata.context": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/$metadata#Assets",
  "value": [ // records ],
  "@odata.nextLink": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/Assets?$skipToken=123"
}

Limitaciones y funciones admitidas​

Los servicios OData procuran cumplir con el estándar OData V4, pero algunas funciones pueden estar limitadas o no ser compatibles debido a las restricciones subyacentes de las API Cognite.

Consulte la documentación de cada servicio para obtener información detallada sobre las funciones admitidas y las limitaciones.

Actualizado por última vez