Vai al contenuto principale

Servizi OData di Cognite

Cognite fornisce i servizi OData per recuperare dati da Cognite Data Fusion (CDF) utilizzando client OData quali Microsoft Power BI, Microsoft Excel e TIBCO Spotfire.

Open Data Protocol (OData) è uno standard aperto che definisce le best practice per creare e utilizzare API RESTful. OData offre:

  • Sintassi di query standardizzate: Consente di applicare filtri, ordinamenti e di seguire impaginazioni e proiezioni in origini dati diverse.

  • Supporto per i metadati: I client possono scoprire i tipi e la struttura di dati tramite documenti di metadati.

  • Interoperabilità: Qualsiasi client che supporta HTTP e comprende OData può utilizzare i servizi OData.

Cognite fornisce un servizio OData asset-centric e un servizio OData di modellazione dei dati. Entrambi i servizi sono livelli intermedi tra le API Cognite standard, e implementano un'OData Version 4 API in sola lettura. Traducono le richieste OData in chiamate Cognite API corrispondenti, consentendo di interagire con i dati CDF utilizzando strumenti e client compatibili con OData.

Utilizzo dei servizi OData​

Per interagire con i servizi OData di Cognite, creare richieste GET HTTP a endpoint specifici.

Autenticazione​

Per eseguire l'autenticazione con i servizi OData, è necessario includere un token di connessione nell'intestazione di autorizzazione delle richieste HTTP.

Ad esempio:

Authorization: Bearer {YourAccessToken}

È possibile ottenere un token di accesso utilizzando il flusso di autenticazione appropriato per l'impostazione, ad esempio OAuth 2.0, OpenID Connect. Per ulteriori dettagli, vedere la documentazione relativa all'autenticazione.

Creazione di richieste​

Richiesta GET di esempio​

Per recuperare tutti gli asset in un progetto:

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

Dove:

  • {cluster}: Il nome del cluster CDF, ad esempio westeurope-1.
  • {apiVersion}: La versione API del servizio OData, ad esempio v1.
  • {project}: Il nome del progetto CDF.
Parametri di query​

Utilizzare i parametri di query per filtrare, ordinare, selezionare e impaginare dati.

  • Filtro: utilizzare il parametro di query $filter per filtrare i dati.

    Esempio: Recuperare asset dove Name è uguale a 'Pump 1': GET .../Assets?$filter=Name eq 'Pump 1'

  • Selezione di campi: utilizzare il parametro di query $select per recuperare campi specifici.

    Esempio: Recuperare solo l'Id e il Name degli asset: GET .../Assets?$select=Id,Name

  • Ordinamento: utilizzare il parametro di query $orderby per ordinare i risultati.

    Esempio: Ordinare gli asset in ordine crescente in base al Name: GET .../Assets?$orderby=Name asc

  • Espansione di entità correlate: utilizzare il parametro di query $expand per includere le entità correlate. Esempio: Recuperare un asset con il relativo elemento padre: GET .../Assets(702630644612)/Parent?$expand=Parent

    Nota: Non tutte le entità e le relazioni supportano l'espansione. Per dettagli, vedere la documentazione del servizio.

  • Combinazione di parametri di query: è possibile combinare più parametri di query per perfezionare la richiesta.

    Esempio: Recuperare l'Id e il Name degli asset dove Name inizia con 'Pump', ordinati in base al Name, quindi recuperare i primi 10 risultati: GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

Formato risposta​

I servizi OData restituiscono risposte in formato JSON, seguendo lo standard OData V4.

Risposta di esempio:

{
  "@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
    }
  ]
}
Impaginazione nelle risposte​

Il servizio OData può impaginare la risposta per set di risultati di grandi dimensioni. La risposta include una proprietà @odata.nextLink con un URL per recuperare la pagina di risultati successiva.

Esempio:

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

Limitazioni e funzionalità supportate​

I servizi OData sono progettati per essere conformi allo standard OData V4, ma alcune funzionalità potrebbero essere limitate o non supportate a causa di vincoli sottostanti nelle API Cognite.

Per informazioni dettagliate sulle limitazioni e le funzionalità supportate, vedere la documentazione del servizio.

Ultimo aggiornamento