Documents de service d’API web

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

Document de service

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

Votre point de terminaison d’API web ressemble à ceci : https://yourorg.api.crm.dynamics.com/api/data/v9.2/. Cette partie : yourorg.api.crm, dépend de votre environnement. Consultez Afficher les ressources du développeur pour découvrir comment le trouver.

Utilisation de l’insomnie

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

Utilisation de PowerShell avec Visual Studio Code

Si vous avez installé les prérequis pour l’API web de démarrage rapide 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 $environmentUrl variable.

$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
$secureToken = (Get-AzAccessToken `
   -ResourceUrl $environmentUrl `
   -AsSecureString).Token

# Convert the secure token to a string
$token = ConvertFrom-SecureString `
   -SecureString $secureToken `
   -AsPlainText


# 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 l’API web de démarrage rapide avec PowerShell et Visual Studio Code

Utilisation de votre navigateur

Vous pouvez envoyer GET des demandes à l’aide de votre navigateur. Tapez l’URL du point de terminaison de l’API web dans la barre d’adresses de votre navigateur.

Conseil / Astuce

Installez une extension de navigateur pour mettre en forme le JSON retourné et faciliter la lecture, puis si vous utilisez Microsoft Edge, recherchez des extensions à l’aide du formateur JSON.

Vous devriez voir des résultats ressemblant à ceci :

{
    "@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 la liste de tous les EntitySets disponibles dans votre environnement. EntitySet est le nom d’une ressource qui fait référence à une table dans Dataverse. Vous allez utiliser le nom du jeu d’entités dans l’URL pour effectuer des opérations sur les données d’une table spécifique.

Conseil / Astuce

Utilisez Ctrl+F sur les résultats de ce document pour rechercher le nom correct du jeu d’entités.

Nom de l'ensemble 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 , mais vous ne devez pas en dépendre.

Modification du nom du jeu d’entités

Si vous avez une table personnalisée que vous souhaitez adresser à l’aide d’un autre nom d’ensemble d’entités, vous pouvez mettre à jour la valeur de 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 devez modifier la EntitySetName table que lorsque vous la créez et avant que tout code ne soit écrit à l’aide de la table. Il interrompt tout code qui a utilisé l’ancien nom.

Document $metadata CSDL

Ajoutez $metadata au point de terminaison de l’API web pour récupérer le document CSDL (Common Schema Definition Language) $metadata document.

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 à l’aide de Visual Studio Code et de PowerShell à l’aide de ces instructions.

Important

Ce document est la source de vérité pour tout ce qui concerne l’API web. Vous voudrez y faire référence fréquemment. Utilisez-le Ctrl+F sur ce document pour localiser les informations spécifiques EntityType, Action, Functionou ComplexTypeEnumType que vous utiliserez. Les noms respectent la casse.

Annotations de métadonnées

Pour obtenir plus d’informations à partir du $metadata, ajoutez ?annotations=true à l’URL.

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

La définition de ce paramètre inclut de nombreux types d’annotations différents 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 retournées en ajoutant l’en-tête de requête Prefer: odata.include-annotations="*". Cet en-tête de requête fonctionne également pour d’autres types de requêtes. Le annotations=true paramètre de requête fonctionne uniquement pour le document $metadata.

Espace de noms de service

En haut de la $metadata vous trouverez cet élément XML :

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

Cet élément vous informe que tous les éléments du service se trouvent dans l’espace Microsoft.Dynamics.CRM de noms et que mscrm est l’alias de l’espace de noms. Dans certains cas, vous devez utiliser le nom complet d’un objet. Cela nécessite donc l’utilisation de la valeur d’espace de noms.

Étapes suivantes

Découvrez les types d’entités.

Types d’entités

Voir aussi

Types d’API Web et opérations
Types d’entités d’API web
Propriétés de l’API web
Propriétés de navigation de l’API web
Actions de l’API web
Fonctions d’API web
Types complexes et énumération d’API web
Utiliser l’API web Dataverse