Passer au contenu principal

Services OData de Cognite

Cognite fournit des services OData pour récupérer des données depuis Cognite Data Fusion (CDF) à l’aide de clients OData tels que Microsoft Power BI, Microsoft Excel et TIBCO Spotfire.

Open Data Protocol (OData) est un protocole d’échange de données ouvert qui définit les meilleures pratiques pour la génération et l’utilisation d’API RESTful. OData présente les avantages suivants :

  • Syntaxe de requête normalisée : Cela garantit la cohérence du filtrage, du tri, de la pagination et des projections dans différentes sources de données.

  • Prise en charge des métadonnées : Les clients peuvent découvrir les types et la structure de données via des documents de métadonnées.

  • Interopérabilité : Tout client prenant en charge HTTP et capable d’interpréter les commandes du protocole OData peut utiliser des services OData.

Cognite fournit un service OData axé sur les actifs et un service OData de modélisation des données. Ces deux services ont pour effet d’encapsuler les API Cognite standard et d’implémenter une OData Version 4 API à des fins de lecture seule. Ils traduisent les requêtes OData en appels Cognite API correspondants, ce qui vous permet d’interagir avec les données CDF à l’aide des clients et outils compatibles avec OData.

Utilisation des services OData​

Pour interagir avec les services OData de Cognite, vous exécutez des requêtes HTTP GET sur des points de terminaison spécifiques.

Authentification​

Pour s’authentifier auprès des services OData, vous devez inclure un jeton du porteur dans l’en-tête d’autorisation de vos requêtes HTTP.

Par exemple :

Authorization: Bearer {YourAccessToken}

Vous pouvez obtenir un jeton d’accès en appliquant le processus d’authentification approprié pour votre configuration (ex. : OAuth 2.0, OpenID Connect). Pour de plus amples détails, reportez-vous à la documentation du processus d’authentification.

Exécution de requêtes​

Exemple de requête GET​

Pour récupérer tous les actifs d’un projet :

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

Où :

  • {cluster} : Le nom du cluster CDF (europeouest-1, par exemple).
  • {apiVersion} : La version de l’API du service OData (v1, par exemple).
  • {project} : Le nom du projet CDF.
Paramètres de requête​

Utilisez des paramètres de requête pour filtrer, trier, sélectionner et paginer les données.

  • Filtrage : utilisez le paramètre de requête $filter pour filtrer les données.

    Exemple : Récupérer des actifs où Name est égal à 'Pump 1' : GET .../Assets?$filter=Name eq 'Pump 1'

  • Sélection des champs : utilisez le paramètre de requête $select pour récupérer des champs spécifiques.

    Exemple : Récupérer uniquement les éléments Id et Name des actifs : GET .../Assets?$select=Id,Name

  • Tri : utilisez le paramètre de requête $orderby pour trier les résultats.

    Exemple : Classer les actifs par Name dans l’ordre croissant : GET .../Assets?$orderby=Name asc

  • Expansion des entités apparentées : utilisez le paramètre de requête $expand pour inclure les entités apparentées. Exemple : Récupérez un actif ainsi que son parent : GET .../Assets(702630644612)/Parent?$expand=Parent

    Remarque : Les entités et les relations ne sont pas toutes compatibles avec la fonction d’expansion. Pour de plus amples détails, reportez-vous à la documentation de chaque service.

  • *Combinaison des paramètres de requête : il est possible de combiner plusieurs paramètres de requête pour affiner votre requête.

    Exemple : Récupérer les éléments Id et Name des actifs où Name commence par 'Pump', les classer par Name et récupérer les 10 premiers résultats : GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

Format des réponses​

Les services OData renvoient des réponses au format JSON, conformément à la norme OData V4.

Exemple de réponse :

{
  "@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
    }
  ]
}
Pagination dans les réponses​

Le service OData peut éventuellement paginer la réponse pour les ensembles de résultats volumineux. La réponse contient une propriété @odata.nextLink avec une URL pour récupérer la page de résultats suivante.

Exemple :

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

Limitations et fonctions prises en charge​

Les services OData visent la conformité avec la norme OData V4, mais certaines fonctionnalités peuvent être limitées ou incompatibles du fait des contraintes sous-jacentes aux API Cognite.

Pour obtenir des informations détaillées au sujet des fonctions prises en charge et des limitations qui s’y appliquent, reportez-vous à la documentation de chaque service.

Dernière mise à jour