Hoppa till huvudinnehållet

Cognite OData-tjänster

Cognite innehåller OData-tjänster för hämtning av data från Cognite Data Fusion (CDF) med OData-klienter som Microsoft Power BI, Microsoft Excel och TIBCO Spotfire.

Open Data Protocol (OData) är en öppen standard som definierar de bästa metoderna för att bygga och använda RESTful API:er. OData erbjuder:

  • Standardiserad frågesyntax: Möjliggör konsekvent filtrering, sortering, paginering och projiceringar över olika datakällor.

  • Metadata-support: Klienter kan få information om datastruktur och typer via metadata- dokument.

  • Interoperabilitet: Alla klienter som stöder HTTP och förstår OData kan använda OData-tjänster.

Cognite tillhandahåller en asset-centric OData-tjänst och en OData-tjänst för datamodellering. Båda tjänsterna omfattar standard-API:erna för Cognite och implementerar en OData Version 4 API endast i skrivskyddande syfte. De översätter OData-förfrågningar till motsvarande Cognite API-anrop, och gör att du kan interagera med CDF-data med hjälp av OData-kompatibla klienter och verktyg.

Använd OData-tjänsterna​

Du interagerar med Cognite OData-tjänsterna genom att göra HTTP GET-förfrågningar till specifika slutpunkter.

Autentisera​

Om du vill autentisera med OData-tjänsterna måste du inkludera en bärartoken i HTTP-förfrågningarnas auktoriseringsrubrik.

Till exempel:

Authorization: Bearer {YourAccessToken}

Du kan få en åtkomsttoken med hjälp av lämpligt autentiseringsflöde för din inställning (t.ex. OAuth 2.0, OpenID Connect). Mer information finns i dokumentationen om autentisering.

Gör förfrågningar​

Exempel på GET-förfrågan​

För att hämta alla tillgångar i ett projekt:

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

Där:

  • {cluster}: CDF-klusternamnet (t.ex. westeurope-1).
  • {apiVersion}: API-versionen för OData-tjänsten (t.ex. v1).
  • {project}: Ditt CDF-projektnamn.
Frågeparametrar​

Använd frågeparametrar för att filtrera, sortera, välja och paginera data.

  • Filtrering – använd frågeparametern för $filter för att filtrera data.

    Example: Hämta tillgångar där Name är lika med 'Pump 1': GET .../Assets?$filter=Name eq 'Pump 1'

  • Välj fält – använd frågeparametern för $select för att hämta specifika fält.

    Example: Hämta bara Id och Name för tillgångar: GET .../Assets?$select=Id,Name

  • Sortering – använd frågeparametern för $orderby för att sortera resultat.

    Example: Ordna tillgångar i Name stigande ordning: GET .../Assets?$orderby=Name asc

  • Expandera relaterade enheter – använd frågeparametern $expand för att inkludera relaterade enheter. Example: Hämta en tillgång tillsammans med dess överordnade: GET .../Assets(702630644612)/Parent?$expand=Parent

    Obs! Vissa enheter och relationer stöder inte expansion. Se separat servicedokumentation för detaljer.

  • Kombinera frågeparametrar – du kan kombinera flera frågeparametrar för att förfina din förfrågan.

    Example: Hämta Id och Name för tillgångarna där Name börjar med 'Pump', ordnas efter Name och hämtar de första 10 resultaten: GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

Svarsformat​

OData-tjänsten returnerar svar i JSON-format, och följer OData-V4-standarden.

Exempelsvar:

{
  "@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
    }
  ]
}
Paginering i svar​

OData Service kan komma att paginera svaret för större resultatmängder. Svaret inkluderar en @odata.nextLink-egenskap med en URL för att hämta nästa sida med resultat.

Exempel:

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

Begränsningar och funktioner som stöds​

OData-tjänster strävar efter att följa OData- V4-standarden, men en del funktioner kan vara begränsade eller inte stödjas på grund av underliggande begränsningar hos Cognite-API:er.

Se separat servicedokumentation för detaljerad information om de funktioner som stöds samt begränsningar.

Senast uppdaterad