Documents de service de l’API web

Les points de terminaison OData fournissent des documents de service qui décrivent les fonctionnalités du service. La compréhension de ces documents de service vous aidera à utiliser les ressources disponibles dans l’environnement avec lequel vous travaillez.

Document de service

Effectuez une demande GET sur le point de terminaison de l’API web pour voir le document de service pour votre environnement.

Le point de terminaison de votre API web ressemblera à ceci : https://yourorg.api.crm.dynamics.com/api/data/v9.2/. Cette partie : yourorg.api.crm dépend de votre environnement. Voir Afficher les ressources des développeurs pour savoir comment les trouver.

Utilisation d’Insomnia

Si vous utilisez Insomnia avec les paramètres d’environnement recommandés, utilisez simplement la variable d’environnement _.webapiurl.

Utiliser PowerShell avec Visual Studio Code

Si vous avez installé les Prérequis pour Démarrage rapide : API web avec PowerShell et Visual Studio Code, vous pouvez afficher le document de service dans Visual Studio Code à l’aide de ce script PowerShell après avoir modifié la variable $environmentUrl.

$environmentUrl = 'https://yourorg.crm.dynamics.com/' # change this
## Login if not already logged in
if ($null -eq (Get-AzTenant -ErrorAction SilentlyContinue)) {
   Connect-AzAccount | Out-Null
}
# Get an access token
$token = (Get-AzAccessToken -ResourceUrl $environmentUrl).Token
# Common headers
$baseHeaders = @{
   'Authorization'    = 'Bearer ' + $token
   'Accept'           = 'application/json'
   'OData-MaxVersion' = '4.0'
   'OData-Version'    = '4.0'
}
# View service document
Invoke-RestMethod -Uri ($environmentUrl + 'api/data/v9.2/') -Method 'Get' -Headers $baseHeaders
| ConvertTo-Json | Out-File -FilePath "service-document.json"
code "service-document.json"

Si cela ne fonctionne pas, consultez les étapes de résolution des problèmes dans Démarrage rapide : API web avec PowerShell et Visual Studio Code

Avec votre navigateur

Vous pouvez envoyer des requêtes GET en utilisant votre navigateur. Tapez l’URL du point de terminaison de l’API web dans la barre d’adresse de votre navigateur.

Conseil

Installez une extension de navigateur pour formater le JSON renvoyé et le rendre plus facile à lire, puis si vous utilisez Microsoft Edge, recherchez des extensions qui utilisent le formateur JSON.

Vous devriez voir des résultats comme celui-ci :

{
    "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata",
    "value": [
        {
            "name": "accountleadscollection",
            "kind": "EntitySet",
            "url": "accountleadscollection"
        },
        {
            "name": "accounts",
            "kind": "EntitySet",
            "url": "accounts"
        },
    ...

Le document de service fournit une liste de tous les EntitySets disponibles dans votre environnement. Un EntitySet est le nom d’une ressource qui fait référence à une table dans Dataverse. Vous utiliserez le nom de le jeu d’entités dans l’URL pour effectuer des opérations sur les données d’une table spécifique.

Conseil

Utilisez Ctrl+F sur les résultats de ce document pour trouver le nom correct de l’ensemble d’entités.

Nom du jeu d’entités

Utilisez toujours le nom du jeu d’entités plutôt que le nom de la collection logique. Par défaut, le nom de l’ensemble d’entités correspond à la valeur de la propriété EntityMetadata.LogicalCollectionName de table, mais vous ne devez pas en dépendre.

Modifier le nom de l’ensemble d’entités

Si vous souhaitez remplacer le nom d’une table personnalisée par un autre nom d’ensemble d’entités, vous pouvez mettre à jour la valeur de la propriété EntityMetadata.EntitySetName pour utiliser un autre nom. En savoir plus sur les propriétés de table que vous pouvez modifier

Important

Vous ne devriez changer que le EntitySetName d’une table lorsque vous la créez et avant qu’un code ne soit écrit à l’aide de la table. Cela brisera tout code utilisant l’ancien nom.

Document de $métadonnées CSDL

Ajoutez $metadata au point de terminaison de l’API web pour récupérer le document de $métadonnées CSDL.

Par exemple : https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata

Ce document XML décrit toutes les tables et opérations que vous pouvez utiliser dans votre environnement.

Vous pouvez télécharger le document CSDL $metadata en utilisant Visual Studio Code et Powershell en utilisant ces instructions.

Important

Ce document est la source de vérité pour tout ce qui concerne l’API web. Vous voudrez le consulter fréquemment. Utilisez Ctrl+F sur ce document pour localiser les éléments EntityType, Action, Function, ComplexType ou EnumType que vous utiliserez. Les noms respectent la casse.

Annotations des métadonnées

Pour obtenir encore plus d’informations à partir des $métadonnées, ajoutez ?annotations=true à l’URL.

Par exemple : https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata?annotations=true

Définir ce paramètre inclut de nombreux types d’annotations qui peuvent être utiles. La plupart des annotations ne sont pas incluses par défaut, car elles augmentent la taille totale du document.

Ces annotations peuvent également être renvoyées en ajoutant l’en-tête de demande Prefer: odata.include-annotations="*". Cet en-tête de demande est également compatible avec d’autres types de demandes. Le paramètre de requête annotations=true ne fonctionne que pour le document $métadonnées.

Espace de noms du service

À proximité du haut du document de $métadonnées, vous trouverez cet élément XML :

    <edmx:DataServices>
        <Schema Namespace="Microsoft.Dynamics.CRM" Alias="mscrm" xmlns="http://docs.oasis-open.org/odata/ns/edm">

Cela vous informe que tous les éléments du service sont dans l’espace de noms Microsoft.Dynamics.CRM et que mscrm est l’alias de l’espace de noms. Dans certaines situations, vous devrez utiliser le nom complet d’un objet, cela nécessitera donc l’utilisation de la valeur de l’espace de noms.

Étapes suivantes

Découvrez les types d’entité.

Types d’entités

Voir aussi

Types d’API web et opérations
Types d’entité de l’API web
Propriétés de l’API web
Propriétés de navigation de l’API web
Actions de l’API web
Fonctions de l’API web
Types Complex et Enumeration de l’API web
Utilisation de l’API web Dataverse

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).