Ga verder naar hoofdinhoud

Cognite OData-services

Cognite biedt OData-services aan om gegevens op te halen uit Cognite Data Fusion (CDF) via OData-clients zoals Microsoft Power BI, Microsoft Excel en TIBCO Spotfire.

Open Data Protocol (OData) is een open standaard die aanbevolen procedures definieert voor het bouwen en gebruiken van RESTful API's. OData biedt:

  • Gestandaardiseerde query-syntaxis: Maakt consistente filtering, sortering, paginering en projecties mogelijk voor verschillende gegevensbronnen.

  • Ondersteuning voor metagegevens: Clients kunnen de gegevensstructuur en -typen ontdekken via metagegevensdocumenten.

  • Interoperabiliteit: Elke client die HTTP ondersteunt en OData begrijpt, kan OData-services gebruiken.

Cognite biedt een assetgerichte OData-service en en een OData-gegevensmodelleringsservice. Beide services omsluiten de standaard Cognite-API's en implementeren een OData Version 4 API voor alleen-lezen. Ze vertalen OData-aanvragen naar bijbehorende Cognite API-oproepen, zodat u kunt communiceren met uw CDF-gegevens via clients en tools die compatibel zijn met OData.

De OData-services gebruiken​

Als u wilt communiceren met de Cognite OData-services, maakt u HTTP GET-aanvragen voor specifieke eindpunten.

Authenticeren​

Als u wilt authenticeren met de OData-services, moet u een Bearer-token opnemen in de autorisatieheader van uw HTTP-aanvragen.

Bijvoorbeeld:

Authorization: Bearer {YourAccessToken}

U kunt een toegangstoken verkrijgen via de betreffende authenticatiestroom voor uw configuratie (bijvoorbeeld OAuth 2.0, OpenID Connect). Raadpleeg de authenticatiedocumentatie voor meer informatie.

Aanvragen maken​

Voorbeeld van een GET-aanvraag​

Alle assets ophalen in een project:

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

Waarbij het volgende geldt:

  • {cluster}: De naam van het CDF-cluster (bijvoorbeeld westeurope-1).
  • {apiVersion}: De versie van de OData-service-API (bijv. v1).
  • {project}: De naam van uw CDF-project.
Queryparameters​

Gebruik queryparameters om gegevens te filteren, sorteren, selecteren en pagineren.

  • Filteren: gebruik de queryparameter $filter om gegevens te filteren.

    Voorbeeld: Assets ophalen waarbij Name gelijk is aan 'Pump 1': GET .../Assets?$filter=Name eq 'Pump 1'

  • Velden selecteren: gebruik de queryparameter $select om specifieke velden op te halen.

    Voorbeeld: Alleen de Id en Name van assets ophalen: GET .../Assets?$select=Id,Name

  • Sorteren: gebruik de queryparameter $orderby om resultaten te sorteren.

    Voorbeeld: Sorteer assets oplopend op Name: GET .../Assets?$orderby=Name asc

  • Verwante entiteiten uitbreiden: gebruik de queryparameter $expand om gerelateerde entiteiten op te nemen. Voorbeeld: Een asset ophalen samen met de bovenliggende asset: GET .../Assets(702630644612)/Parent?$expand=Parent

    Opmerking: Niet alle entiteiten en relaties ondersteunen uitbreiding. Raadpleeg de betreffende servicedocumentatie voor meer informatie.

  • *Queryparameters combineren: u kunt meerdere queryparameters combineren om uw aanvraag te verfijnen.

    Voorbeeld: De Id en Name ophalen van assets waarvan de Name begint met 'Pump', geordend op Name, en de eerste 10 resultaten ophalen: GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

Opmaak van reacties​

De OData-services retourneren reacties in JSON-indeling, volgens de OData V4-standaard.

Voorbeeld van een reactie:

{
  "@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 in reacties​

De OData-service kan de reactie pagineren in het geval van grote resultatensets. De reactie bevat een @odata.nextLink-eigenschap met een URL om de volgende pagina met resultaten op te halen.

Voorbeeld:

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

Beperkingen en ondersteunde functies​

De OData services zijn bedoeld om te voldoen aan de OData V4-standaard, maar sommige functies zijn mogelijk beperkt of worden niet ondersteund vanwege onderliggende beperkingen van de Cognite-API's.

Raadpleeg de betreffende servicedocumentatie voor gedetailleerde informatie over ondersteunde functies en beperkingen.

Laatst bijgewerkt