Pular para o conteúdo principal

Serviços do OData do Cognite

O Cognite fornece serviços do OData para buscar dados de Cognite Data Fusion (CDF) usando clientes do OData como Microsoft Power BI, Microsoft Excel e TIBCO Spotfire.

Open Data Protocol (OData) é um padrão aberto que define as melhores práticas para construir e consumir APIs RESTful. O OData oferece:

  • Sintaxe de consulta padronizada: Habilita filtragem, classificação, paginação e projeções consistentes em diferentes fontes de dados.

  • Suporte de metadados: Os clientes podem descobrir a estrutura de dados e os tipos por meio de documentos de metadados.

  • Interoperabilidade: Qualquer cliente que suporte HTTP e entenda o OData pode consumir os serviços do OData.

A Cognite oferece um serviço do OData centrado em ativos e um serviço de modelagem de dados do OData. Ambos os serviços envolvem as APIs do Cognite padrão, implementando uma OData Version 4 API para fins de somente leitura. Eles traduzem solicitações do OData em chamadas do Cognite API correspondentes, permitindo que você interaja com dados do CDF usando clientes e ferramentas compatíveis com OData.

Uso dos serviços do OData​

Para interagir com os serviços do Cognite e do OData, você faz requisições HTTP GET para pontos de extremidades específicos.

Autenticar​

Para autenticar-se nos serviços do OData, você deve incluir um token de portador no cabeçalho de autorização das suas solicitações HTTP.

Por exemplo:

Authorization: Bearer {YourAccessToken}

Você pode obter um token de acesso utilizando o fluxo de autenticação apropriado para a sua configuração (por exemplo, OAuth 2.0, OpenID Connect). Para obter mais detalhes, consulte a Documentação de autenticação.

Fazer solicitações​

Exemplo de solicitação GET​

Para recuperar todos os ativos em um projeto:

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

Onde:

  • {cluster}: O nome do cluster do CDF (por exemplo, westeurope-1).
  • {apiVersion}: A versão da API do serviço do OData (por exemplo, v1).
  • {project}: Seu nome do projeto do CDF.
Parâmetros de consulta​

Utilize parâmetros de consulta para filtrar, ordenar, selecionar e paginar dados.

  • Filtragem - use o parâmetro de consulta $filter para filtrar os dados.

    Exemplo: Recupere ativos onde Name é igual a 'Pump 1': GET .../Assets?$filter=Name eq 'Pump 1'

  • Seleção de campos - use o parâmetro de consulta $select para recuperar campos específicos.

    Exemplo: Recupere apenas Id e Name dos ativos: GET .../Assets?$select=Id,Name

  • Classificação - use o parâmetro de consulta $orderby para classificar os resultados.

    Exemplo: Classifique ativos pela ordem crescente Name: GET .../Assets?$orderby=Name asc

  • Expansão de entidades relacionadas - use o parâmetro de consulta $expand para incluir entidades relacionadas. Exemplo: Recupere um ativo junto com seu pai: GET .../Assets(702630644612)/Parent?$expand=Parent

    Observação: Nem todas as entidades e relações são compatíveis com expansão. Consulte a documentação do serviço individual para obter mais detalhes.

  • Combinação de parâmetros de consulta - você pode combinar vários parâmetros de consulta para refinar sua solicitação.

    Exemplo: Recupere Id e Name dos ativos em que Name começa com 'Pump', classificados por Name, e recupere os primeiros 10 resultados: GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

Formato de resposta​

Os serviços do OData retornam respostas no formato JSON, seguindo o padrão V4 do OData.

Resposta de exemplo:

{
  "@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
    }
  ]
}
Paginação nas respostas​

O serviço do OData pode paginar a resposta para conjuntos de resultados grandes. A resposta inclui uma propriedade @odata.nextLink com uma URL para recuperar a próxima página de resultados.

Exemplo:

{
  "@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"
}

Limitações e funcionalidades compatíveis​

Os serviços do OData visam conformar-se ao padrão V4 do OData, mas alguns funcionalidades podem ser limitados ou não compatíveis devido a restrições subjacentes das APIs do Cognite.

Consulte a documentação do serviço individual para obter informações detalhadas sobre os funcionalidades e limitações compatíveis.

Última atualização em por