Zum Hauptinhalt wechseln

Cognite OData-Services

Cognite stellt OData-Services für den Abruf von Daten aus Cognite Data Fusion (CDF) bereit. Zum Einsatz kommen dabei OData-Clients wie Microsoft Power BI, Microsoft Excel und TIBCO Spotfire.

Open Data Protocol (OData) ist ein offener Standard zur Festlegung von Best Practices für die Entwicklung und Nutzung von RESTful APIs. OData bietet die folgenden Vorteile:

  • Standardisierte Abfragesyntax: Ermöglicht konsistente Filterung, Sortierung, Paginierung und Projektion über verschiedene Datenquellen.

  • Metadatenunterstützung: Clients können die Datenstruktur und -typen mithilfe von Metadatendokumenten erkunden.

  • Interoperabilität: Clients, die HTTP unterstützen und OData verstehen, können OData-Services nutzen.

Cognite stellt einen anlagenbezogenen OData-Service und einen OData-Service für die Datenmodellierung zur Verfügung. Beide Services umfassen die standardmäßigen Cognite-APIs und implementieren eine OData Version 4 API für schreibgeschützte Zwecke. Sie übersetzen OData-Anfragen in entsprechende Cognite API-Aufrufe, sodass Sie mithilfe von OData-kompatiblen Clients und Tools mit CDF-Daten interagieren können.

Nutzung der OData-Services​

Um mit den Cognite OData-Services zu interagieren, stellen Sie HTTP-GET-Anfragen an spezifische Endpunkte.

Authentifizierung​

Für die Authentifizierung gegenüber den OData-Services müssen Sie in den Autorisierungsheader Ihrer HTTP-Anfragen einen Bearer-Token einfügen.

Zum Beispiel:

Authorization: Bearer {YourAccessToken}

Sie können ein Zugriffstoken über den für Ihr System geeigneten Authentifizierungsweg (z. B. OAuth 2.0, OpenID Connect) erhalten. Weitere Details finden Sie in der Authentifizierungsdokumentation.

Anfragen stellen​

Beispiel für eine GET-Anfrage​

Zum Abruf aller Anlagenteile in einem Projekt:

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

Mit:

  • {cluster}: Der CDF-Clustername (z. B. westeurope-1).
  • {apiVersion}: Die API-Version des OData-Service (z. B. v1).
  • {project}: Der Name Ihres CDF-Projekts.
Abfrageparameter​

Verwenden Sie Abfrageparameter zum Filtern, Sortieren, Auswählen und Paginieren von Daten.

  • Filtern - Verwenden Sie den Abfrageparameter $filter zum Filtern von Daten.

    Beispiel: Abruf von Anlagenteilen, bei denen Name gleich 'Pump 1' ist: GET .../Assets?$filter=Name eq 'Pump 1'

  • Auswahl von Feldern - Verwenden Sie den Abfrageparameter $select zum Abruf bestimmter Felder.

    Beispiel: Abruf ausschließlich von Id und Name von Anlagenteilen: GET .../Assets?$select=Id,Name

  • Sortieren - Verwenden Sie den Abfrageparameter $orderby zum Sortieren von Ergebnissen.

    Beispiel: Aufsteigende Sortierung von Anlagenteilen auf Basis von Name: GET .../Assets?$orderby=Name asc

  • Erweiterung zugehöriger Entitäten - Verwenden Sie den Abfrageparameter $expand, um zugehörige Entitäten einzuschließen. Beispiel: Abruf eines Anlagenteils zusammen mit seinem übergeordneten Element: GET .../Assets(702630644612)/Parent?$expand=Parent

    Hinweis: Die Erweiterung wird nicht von allen Entitäten und Beziehungen unterstützt. Für detaillierte Informationen siehe die entsprechende Service-Dokumentation.

  • *Kombinieren von Abfrageparametern - Sie können mehrere Abfrageparameter kombinieren, um Ihre Anfrage zu verfeinern.

    Beispiel: Abruf von Id und Name von Anlagenteilen, bei denen Name mit 'Pump' beginnt, sortiert nach Name, Abruf der zehn ersten Ergebnisse: GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

Antwortformat​

Die OData-Services geben Antworten im JSON-Format zurück und folgen dabei dem OData-Standard V4.

Beispielantwort:

{
  "@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
    }
  ]
}
Paginierung in Antworten​

Im Fall von umfangreichen Antworten kann der OData-Service die Antwort paginieren. Die Antwort umfasst eine @odata.nextLink-Eigenschaft mit einer URL für den Abruf der nächsten Seite mit Ergebnissen.

Beispiel:

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

Einschränkungen und unterstützte Merkmale​

Die OData-Services zielen auf die Einhaltung des OData-Standards V4 ab, allerdings gibt es aufgrund der zugrundeliegenden Einschränkungen der Cognite-APIs bei einigen Merkmalen Einschränkungen oder bestimmte Merkmale werden überhaupt nicht unterstützt.

Für detaillierte Informationen über unterstützte Merkmale und Einschränkungen siehe die entsprechende Service-Dokumentation.

Zuletzt aktualisiert