Types d'API Web et opérations
Date de publication : janvier 2017
S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Pour utiliser l'API Web, vous devez trouver des informations sur les éléments que vous pouvez utiliser. Le service se décrit via les documents de service et de métadonnées auxquels vous pouvez accéder. Cette rubrique présente des concepts importants et décrit comment trouver les informations nécessaires à l'aide de la documentation générée à partir des documents de service et de métadonnées ainsi que la documentation des types d'entités système, des fonctions et des actions.
Contenu de la rubrique
Terminologie
Documents de service
Types d'entités
Propriétés
Propriétés de navigation
Actions
Fonctions
Types complexes
Types d'énumération
Terminologie
L'API Web est implémentée à l'aide de la version 4 de la norme OData qui utilise un ensemble spécifique de termes que vous devez connaître. Le Modèle de données d'entité (EDM) est le modèle de données abstrait utilisé pour décrire les données exposées par un service OData. Le tableau suivant contient une liste sélectionnée de termes définis dans la Partie 1 de la version 4.0 d'OData : Protocol Plus Errata 02 que vous devez comprendre.
Terme |
Définition |
|---|---|
Types d'entités |
Types structurés nommés avec une clé. Ils définissent les propriétés et les relations nommées d'une entité. Les types d'entités peuvent dériver par simple héritage d'autres types d'entités. |
Entités |
Instances de types d'entités (par exemple, account, opportunity). |
Ensembles d'entités |
Collections nommées d'entités (par exemple, accounts est un ensemble d'entités contenant des entités account). La clé d'une entité identifie de manière unique l'entité dans un ensemble d'entités. |
Types complexes |
Types structurés nommés sans clés, composés d'un ensemble de propriétés. Les types complexes sont souvent utilisés comme valeurs de propriété dans les entités de modèle, ou comme paramètres ou valeurs de retour pour les opérations. |
Types d'énumération ou Types d'enum |
Types primitifs nommés dont les valeurs sont des constantes nommées avec des valeurs entières sous-jacentes. |
Fonctions |
Opérations qui n'ont pas d'effets secondaires et qui peuvent prendre en charge d'autres compositions, par exemple, avec des opérations de filtre, des fonctions ou des actions supplémentaires |
Actions |
Opérations qui ont des effets secondaires, par exemple la modification des données, et qui ne peuvent pas prendre en charge d'autres compositions pour éviter tout comportement non déterministe |
Documents de service
Il existe deux documents de service que vous pouvez référencer pour en savoir plus sur l'API Web.
Document de service
La requête suivante, tapée dans le champ d'adresse de votre navigateur, renvoie le document de service, une liste complète de tous les ensembles d'entités disponibles pour votre organisation. Notez que [URI de l'organisation] représente l'URL de votre organisation.
[URI de l'organisation]/api/data/v8.2
Les ensembles d'entités sont renvoyés sous la forme d'un tableau JSON. Chaque élément du tableau a trois propriétés, comme indiqué dans ce tableau.
Propriété |
Description |
|---|---|
name |
Il s'agit du nom de l'ensemble d'entités. Ces données proviennent de la propriété EntityMetadata EntityType EntitySetName de l'entité. |
kind |
Pour l'API Web, seuls les ensembles d'entités sont répertoriés. |
url |
Cette valeur est identique à celle de la propriété name et représente la partie du chemin d'accès aux ressources pour récupérer les données de l'entité. |
Ces informations peuvent être récupérées à l'aide d'une requête GET et peuvent être utiles pour obtenir la liste de tous les ensembles d'entités disponibles avec le service.
Document de métadonnées CSDL
Une requête GET à l'URL suivante renvoie un document Common Schema Definition Language (CSDL) assez volumineux (plus de 3,5 Mo), ou un document de métadonnées qui décrit les données et les opérations exposées par le service.
[URI de l'organisation]/api/data/v8.2/$metadata
Ce document peut être utilisé comme source de données pour générer des classes qui fournissent des objets fortement typés pour le service. Mais si vous n'utilisez pas les classes générées, vous pouvez consulter la documentation générée à partir de ces informations à la place. La Web API Reference utilise principalement les informations de ce document provenant d'un système non personnalisé.
Pour en savoir plus sur ce document, consultez la Partie 3 de la version 4.0 d'OData : Common Schema Definition Language (CSDL) Plus Errata 02.
Conseil
Avant de lire le reste de cette rubrique, téléchargez le document CSDL pour votre organisation et examinez comment les types, les fonctions et les actions décrits sont inclus dans le document CSDL et la documentation associée.
Types d'entités
La Web API EntityType Reference répertorie chacun des types d'entités système exposés via l'API Web qui stockent les données d'entreprise. Un type d'entité est un type structuré nommé avec une clé. Il définit les propriétés et les relations nommées d'une entité. Les types d'entités peuvent dériver par simple héritage d'autres types d'entités. La Web API Metadata EntityType Reference répertorie chacun des types d'entités utilisés pour gérer les métadonnées du système. Toutes deux sont des types d'entités, mais vous les utilisez de manière différente. Pour plus d'informations sur l'utilisation des entités de modèle, voir Utiliser l'API Web avec les métadonnées Dynamics 365. Chaque type d'entité est inclus dans un élément EntityType de CSDL. Vous trouverez ci-dessous la définition de account EntityType provenant de CSDL avec des propriétés et des propriétés de navigation supprimées.
<EntityType Name="account" BaseType="mscrm.crmbaseentity">
<Key>
<PropertyRef Name="accountid" />
</Key>
<!--Properties and navigation properties removed for brevity-->
<Annotation Term="Org.OData.Core.V1.Description" String="Business that represents a customer or potential customer. The company that is billed in business transactions." />
</EntityType>
Chaque page de référence EntityType de la documentation du Kit de développement logiciel (SDK) utilise les informations de CSDL ou des métadonnées pour afficher les informations suivantes lorsqu'elles sont disponibles.
Informations |
Description |
|---|---|
Description |
Description de l'entité. Les informations de la propriété EntityMetadata EntityType Description sont incluses dans l'élément EntityType à l'aide de l'élément Annotation avec la valeur d'attribut Term de Org.OData.Core.V1.Description. |
URL de la collection |
URL permettant d'accéder à la collection de chaque type. Les informations de la propriété EntityMetadata EntityType EntitySetName sont incluses à l'aide de l'élément EntityContainer de CSDL. L'attribut Name de chaque élément EntitySet contrôles l'accès aux données via l'URL. |
Type de base |
Il s'agit du type d'entité dont le type d'entité hérite. L'attribut BaseType de l'élément EntityType contient le nom du type d'entité. Ce nom a pour préfixe l'alias de l'espace de noms Microsoft.Dynamics.CRM : mscrm.Pour plus d'informations :Héritage de type |
Nom complet |
Ces informations ne figurent pas dans CSDL, elles sont extraites de la propriété EntityMetadata EntityType DisplayName. |
Clé primaire |
Valeur de propriété contenant l'identificateur unique pour référencer une instance d'entité. La valeur de la propriété EntityMetadata EntityType PrimaryIdAttribute est incluse dans l'élément EntityType Key. Chaque entité ne peut avoir qu'une seule clé primaire. Les clés secondaires ne sont pas répertoriées ici.Pour plus d'informations :Clés secondaires |
Attribut principal |
De nombreuses entités nécessitent la définition d'une valeur d'attribut principal ; cette information est donc incluse pour vous faciliter la tâche. Ces informations ne figurent pas dans CSDL, elles sont extraites de la propriété EntityMetadata EntityType PrimaryNameAttribute. des métadonnées. |
Propriétés |
Pour plus d'informations, consultez Propriétés. |
Propriétés de navigation à valeur unique |
Pour plus d'informations, consultez Propriétés de navigation à valeur unique. |
Propriétés de navigation à valeur de collection |
Pour plus d'informations, consultez Propriétés de navigation à valeur de collection. |
Opérations liées au type d'entité |
Lorsqu'une opération est liée à un type d'entité spécifique, elle est répertoriée pour vous faciliter la tâche. |
Opérations utilisant le type d'entité |
Cette liste affiche les opérations qui peuvent utiliser le type d'entité. Elle est dérivée en collectant les références à toutes les opérations qui font référence au type actuel dans les paramètres ou en tant que valeur de retour. |
Types d'entités qui héritent du type d'entité. |
Cette liste inclut les types d'entités qui héritent directement du type d'entité. Pour plus d'informations, voir Héritage de type. |
Modifier le nom d'un ensemble d'entités
Par défaut, le nom de l'ensemble d'entités correspond à la valeur de la propriété EntityMetadata EntityType LogicalCollectionName (EntityMetadataLogicalCollectionName). Si vous souhaitez remplacer le nom d'une entité personnalisée par un autre nom d'ensemble d'entités, vous pouvez mettre à jour la valeur de la propriété EntityMetadata EntityType EntitySetName (EntityMetadata.EntitySetName) pour utiliser un autre nom.
Clés secondaires
Microsoft Dynamics 365 permet de créer des clés secondaires, mais seule la clé primaire est disponible dans la documentation du SDK de Microsoft Dynamics 365.
Aucune clé secondaire n'est définie pour les entités du système. Si vous définissez des clés secondaires pour une entité, elles sont incluses dans l'élément EntityType de CSDL en tant que Annotation comme suit :
<Annotation Term="OData.Community.Keys.V1.AlternateKeys">
<Collection>
<Record Type="OData.Community.Keys.V1.AlternateKey">
<PropertyValue Property="Key">
<Collection>
<Record Type="OData.Community.Keys.V1.PropertyRef">
<PropertyValue Property="Alias" String="key name" />
<PropertyValue Property="Name" PropertyPath="key name" />
</Record>
</Collection>
</PropertyValue>
</Record>
</Collection>
</Annotation>
Les informations relatives aux clés secondaires peuvent également être extraites des métadonnées à l'aide de la propriété de navigation à valeur de collection EntityMetadata EntityType Keys avec l'API Web ou à l'aide de la propriété EntityMetadata.Keys avec le service d'organisation.
Héritage de type
L'héritage permet de partager des propriétés communes et de classer des types d'entités en groupes. Tous les types d'entités de l'API Web héritent de deux des types d'entités suivants. Tous les types d'entité commerciale héritent de crmbaseentity EntityType et toutes les entités de modèle héritent de crmmodelbaseentity EntityType.
Entité de base |
Description |
|---|---|
Toutes les entités commerciales héritent de cette entité. Elle ne possède aucune propriété. Elle sert uniquement d'entité de base abstraite. |
|
Toutes les entités d'activité héritent de cette entité. Elle définit l'ensemble commun de propriétés et de propriétés de navigation pour les entités d'activité. |
|
Les entités systemuser EntityType et team EntityType héritent de la propriété commune ownerid de cette entité. |
|
Seule l'entité MetadataBase EntityType hérite directement de cette entité. Elle ne possède aucune propriété. Elle sert uniquement d'entité de base abstraite. |
|
Toutes les entités de modèle héritent de cette entité. Elle fournit les propriétés MetadataId et HasChanged pour toutes les entités de modèle. |
|
Toutes les entités de modèle qui représentent différents types d'attributs héritent de cette entité. |
|
Les entités de modèle qui représentent des attributs incluant un ensemble d'options héritent de cette entité. |
|
Ce type d'entité de modèle fournit un ensemble commun de propriétés utilisées par les types d'entités de modèle BooleanOptionSetMetadata EntityType et OptionSetMetadata EntityType qui héritent de celui-ci. |
|
Ce type d'entité fournit un ensemble commun de propriétés utilisées par les types d'entités de modèle ManyToManyRelationshipMetadata EntityType et OneToManyRelationshipMetadata EntityType qui héritent de celui-ci. |
Propriétés
Chaque type d'entité peut avoir des propriétés déclarées qui correspondent aux attributs. Dans le contenu Web API EntityType Reference et Web API Metadata EntityType Reference, les propriétés qui sont héritées d'un type d'entité de base sont combinées dans la liste des propriétés déclarées pour chaque type d'entité. L'héritage est indiqué dans la description de chaque propriété.
Dans les éléments EntityType de CSDL, chaque propriété est incluse dans un élément Property avec une valeur d'attribut Name qui correspond aux propriétés que vous définissez dans le code. La valeur d'attribut Type spécifie le type de données de la propriété. Les propriétés des types d'entité commerciale utilisent généralement les types primitifs OData.
Vous trouverez ci-dessous un exemple de la propriété account EntityType name définie dans CSDL.
<Property Name="name" Type="Edm.String" Unicode="false">
<Annotation Term="Org.OData.Core.V1.Description" String="Type the company or business name." />
</Property>
La description de la propriété est disponible dans un élément Annotation avec la propriété d'attribut Term de Org.OData.Core.V1.Description. Cette description est extraite de la valeur de la propriété AttributeMetadata EntityType Description. Certaines propriétés ont une description.
Chaque propriété peut être calculée. Cela signifie que la valeur peut être définie par le système. Cela est spécifié dans un élément Annotation avec la valeur d'attribut Term de Org.OData.Core.V1.Computed.
Chaque propriété peut également avoir des limitations sur son éventuelle mise à jour. Cela est défini dans un élément Annotation avec la valeur d'attribut Term de Org.OData.Core.V1.Permissions. Le seul groupe d'options est Org.OData.Core.V1.PermissionType/Read, qui indique que la propriété est en lecture seule.
Types primitifs
OData prend en charge une large éventail de types de données mais Microsoft Dynamics 365 ne les utilise pas tous. Le tableau suivant décrit comment les types de services d'organisation de Dynamics 365 sont mappés aux types primitifs OData.
Type de service d'organisation |
Type d'API Web |
Description |
|---|---|---|
BigInt |
Edm.Int64 |
Entier 64 bits signé |
Boolean |
Edm.Boolean |
Logique à valeur binaire |
CalendarRules |
Propriétés de navigation à valeur unique |
Propriétés de navigation à valeur unique spécifiques à calendarrule EntityType. |
Client |
Propriétés de navigation à valeur unique |
Le client d'une entité avec ce type de propriété peut être une propriété de navigation à valeur unique définie sur un type d'entité account ou contact qui utilise les propriétés de navigation à valeur unique respectives. Lorsque l'une des propriétés de collection à valeur unique respectives est définie, l'autre est désactivée. |
DateTime |
Edm.DateTimeOffset |
Date et heure avec un décalage du fuseau horaire, aucune seconde intercalaire |
Décimal |
Edm.Decimal |
Valeurs numériques avec précision et échelle fixes |
Double |
Edm.Double |
Nombre à virgule flottante binary64 IEEE 754 (15 à 17 nombres décimaux) |
Nom de l’entité |
Edm.String |
Séquence de caractères UTF-8 |
Image |
Edm.Binary |
Données binaires |
Entier |
Edm.Int32 |
Entier 32 bits signé |
Recherce |
Propriété de navigation à valeur unique |
Référence à une entité spécifique |
ManagedProperty |
Non applicable |
Utilisation interne uniquement. |
Mémo |
Edm.String |
Séquence de caractères UTF-8 |
Devise |
Edm.Decimal |
Valeurs numériques avec précision et échelle fixes |
Propriétaire |
Propriété de navigation à valeur unique |
Référence à principal EntityType. Les types d'entités systemuser et team héritent leur propriété ownerid du type d'entité prinicipal. |
PartyList |
Propriété de navigation à valeur de collection pour le type d'entité activityparty. |
La propriété activitypartyparticipationtypemask contient une valeur pour représenter le rôle du participant. Pour plus d'informations, voir Types de groupe d’activité. |
Liste de choix |
Edm.Int32 |
Entier 32 bits signé |
État |
Edm.Int32 |
Entier 32 bits signé |
Statut |
Edm.Int32 |
Entier 32 bits signé |
Chaîne |
Edm.String |
Séquence de caractères UTF-8 |
Uniqueidentifier |
Edm.Guid |
Identificateur unique 16 octets (128 bits) |
Propriétés de recherche
Pour la plupart des propriétés de navigation à valeur unique, vous trouverez une propriété en lecture seule calculée qui utilise la convention d'affectation de noms suivante : _<name>_value où <name> correspond au nom de la propriété de navigation à valeur unique. L'exception à ce modèle est lorsqu'un attribut de recherche de l'entité peut accepter plusieurs types de références d'entité. Un exemple courant est la façon dont l'attribut customerid de l'entité incident peut être défini sur une référence qui est une entité contact ou account. Dans les Single-valued navigation properties de incident EntityType, vous trouverez customerid_account et customerid_contact comme propriétés de navigation à valeur unique distinctes pour refléter le client associé à une opportunité. Si vous définissez une de ces propriétés de navigation à valeur unique, l'autre est définie sur null, car toutes deux sont liées à l'attribut customerid. Dans les Properties de incident EntityType, vous trouverez une propriété de recherche _customerid_value qui contient la même valeur que celle définie pour les propriétés de navigation à valeur unique contenant une valeur.
En général, vous devez éviter d'utiliser les propriétés de recherche et utiliser les propriétés de navigation à valeur unique correspondantes à la place. Ces propriétés ont été incluses, car elles peuvent être utiles pour certains scénarios d'intégration. Ces propriétés sont en lecture seule et calculées, car elles reflètent simplement les modifications appliquées à l'aide de la propriété de navigation à valeur unique correspondante.
Lorsque vous incluez des propriétés de recherche dans une requête, vous pouvez demander d'inclure des annotations qui fournissent des informations supplémentaires sur les données définies pour les attributs sous-jacents qui ne sont pas représentés par une propriété de navigation à valeur unique.Pour plus d'informations :Extraire les données sur les propriétés de recherche
Propriétés de navigation
Dans OData, les propriétés de navigation vous permettent d'accéder aux données associées à l'entité actuelle. Lorsque vous récupérez une entité, vous pouvez choisir de développer les propriétés de navigation pour inclure les données associées. Il existe deux types de propriétés de navigation : à valeur unique et à valeur de collection.
Propriétés de navigation à valeur unique
Ces propriétés correspondent aux attributs de recherche qui prennent en charge les relations plusieurs-à-un et permettent de définir une référence à une autre entité. Dans l'élément EntityType de CSDL, elles sont définies en tant qu'élément NavigationProperty avec un attribut Type défini sur un type unique. Vous trouverez ci-dessous un exemple de la propriété de navigation à valeur unique account EntityType createdby définie dans CSDL :
<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby">
<ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" />
</NavigationProperty>
Chaque propriété de navigation qui représente une propriété de navigation à valeur unique a une propriété de navigation à valeur de collection correspondante indiquée par la valeur d'attribut Partner. Chaque propriété de navigation à valeur unique a également un élément ReferentialConstraint avec la valeur d'attribut Property qui représente la propriété de recherche en lecture seule calculée qui permet de récupérer la valeur GUID correspondante de l'entité associée.Pour plus d'informations :Propriétés de recherche
Propriétés de navigation à valeur de collection
Ces propriétés correspondent aux relations un-à-plusieurs ou plusieurs-à-plusieurs. Dans l'élément EntityType de CSDL, elles sont définies en tant qu'élément NavigationProperty avec un attribut Type défini sur une collection d'un type. Vous trouverez ci-dessous la propriété de navigation à valeur de collection account EntityType Account_Tasks qui représente une relation un-à-plusieurs :
<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />
Lorsque la propriété de navigation à valeur de collection représente une relation plusieurs-à-plusieurs, le nom de la propriété de navigation et le nom du partenaire sont identiques. Vous trouverez ci-dessous la propriété de navigation à valeur de collection account EntityType accountleads_association qui représente une relation plusieurs-à-plusieurs :
<NavigationProperty Name="accountleads_association" Type="Collection(mscrm.lead)" Partner="accountleads_association" />
La différence entre les relations un-à-plusieurs et plusieurs-à-plusieurs n'est pas importante lorsque l'API Web est utilisé. Le mode d'association des entités est le même quel que soit le type de relation. Bien que les relations plusieurs-à-plusieurs utilisent toujours les entités avec intersection en arrière-plan, seules quelques entités avec intersection système spéciales sont incluses dans la Web API EntityType Reference. Par exemple, campaignactivityitem EntityType est techniquement une entité avec intersection, mais elle est incluse, car elle a plus de propriétés qu'une entité avec intersection ordinaire.
Une entité avec intersection ordinaire a uniquement les quatre propriétés de base requises pour gérer la relation plusieurs-à-plusieurs. Lorsque vous créez une relation plusieurs-à-plusieurs personnalisée entre des entités, une entité avec intersection ordinaire est créée pour prendre en charge la relation. Comme vous devez utiliser les propriétés de navigation pour exécuter des opérations impliquant les relations plusieurs-à-plusieurs, les entités avec intersection ordinaires ne sont pas documentées mais restent disponibles avec l'API Web. Ces types d'entités avec intersection sont accessibles en utilisant un nom d'ensemble d'entités qui utilise la convention d'affectation de noms suivante : <nom logique de l'entité avec intersection>+ 'collection'. Par exemple, vous pouvez extraire des informations du type d'entité avec intersection contactleads à l'aide de [URI de l'organisation]/api/data/v8.2/contactleadscollection. Vous devez uniquement utiliser ces entités avec intersection ordinaires dans les cas où vous souhaitez appliquer le suivi des modifications.
Actions
Les Actions sont des opérations qui ont des effets secondaires, par exemple la modification des données, et qui ne peuvent pas prendre en charge d'autres compositions pour éviter tout comportement non déterministe.
La rubrique Web API Action Reference répertorie chacune des actions système disponibles.Pour plus d'informations :Utiliser des actions API Web.
Fonctions
Les Fonctions sont des opérations qui n'ont pas d'effets secondaires et qui peuvent prendre en charge d'autres compositions, par exemple, avec des opérations de filtre, des fonctions et des actions supplémentaires.
Il existe deux types de fonctions définies dans l'API Web :
La rubrique Web API Function Reference répertorie chacune des fonctions système disponibles.
La rubrique Web API Query Function Reference répertorie les fonctions conçues pour être utilisées comme critères d'une requête.
Pour plus d'informations :Utiliser des fonctions API Web
Types complexes
Les Types complexes sont des types structurés nommés sans clés, composés d'un ensemble de propriétés. Les types complexes sont souvent utilisés comme valeurs de propriété dans les entités de modèle, ou comme paramètres ou valeurs de retour pour les opérations.
La rubrique Web API ComplexType Reference répertorie tous les types complexes du système. Les Types complexes sont des types structurés nommés sans clés, composés d'un ensemble de propriétés. Ils sont souvent utilisés comme valeurs de propriété dans les entités de modèle, ou comme paramètres ou valeurs de retour pour les opérations. Vous trouverez ci-dessous l'élément WhoAmIResponse ComplexType de CSDL.
<ComplexType Name="WhoAmIResponse">
<Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
<Property Name="UserId" Type="Edm.Guid" Nullable="false" />
<Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
Types d'énumération
Les Types d'énumération ou EnumTypes sont des types primitifs nommés dont les valeurs sont des constantes nommées avec des valeurs entières sous-jacentes.
La rubrique Web API EnumType Reference répertorie tous les types d'énumération du système. Les Types d'énumération sont des types primitifs nommés dont les valeurs sont des constantes nommées avec des valeurs entières sous-jacentes. Vous trouverez ci-dessous l'élément AccessRights EnumType de CSDL.
<EnumType Name="AccessRights">
<Member Name="None" Value="0" />
<Member Name="ReadAccess" Value="1" />
<Member Name="WriteAccess" Value="2" />
<Member Name="AppendAccess" Value="4" />
<Member Name="AppendToAccess" Value="16" />
<Member Name="CreateAccess" Value="32" />
<Member Name="DeleteAccess" Value="65536" />
<Member Name="ShareAccess" Value="262144" />
<Member Name="AssignAccess" Value="524288" />
</EnumType>
Voir aussi
Utilisez l'API Web Microsoft Dynamics 365
Authentification Microsoft Dynamics 365 avec l'API Web
Effectuer des opérations à l'aide de l'API Web
Microsoft Dynamics 365
© 2017 Microsoft. Tous droits réservés. Copyright