Utiliser les fonctions de l'API Web

Article
05/11/2022
3 minutes de lecture

Notes

Vous n’êtes pas sûr de l’entité par rapport à la table ? Voir Développeurs : Comprendre la terminologie dans Microsoft Dataverse.

Les actions et les fonctions représentent des opérations réutilisables que vous pouvez effectuer avec l'API Web. Il existe deux types de fonction dans l'API Web :

Fonctions
Utilisez une demande GET avec des fonctions répertoriées dans Web API Function Reference pour effectuer les opérations qui n'ont aucun effet secondaire. Généralement, ces fonctionnalités récupèrent des données. Elles renvoient une collection ou un type complexe. Chacune de ces fonctions contient un message correspondant au service de l'organisation.

Fonctions de requête
Utilisez les fonctions répertoriées dans Web API Query Function Reference pour évaluer les propriétés et les valeurs dans la composition d'une requête. Chacune de ces fonctions contient une valeur ConditionOperator correspondante.

Transmission de paramètres à une fonction

Pour les fonctions qui nécessitent des paramètres, il est recommandé de passer les valeurs à l’aide des paramètres. Par exemple, lorsque vous utilisez la fonction GetTimeZoneCodeByLocalizedName, vous devez inclure les valeurs de paramètre LocalizedStandardName et LocaleId. Par conséquent, vous pouvez utiliser la syntaxe intégrée suivante comme indiqué ci-dessous.

GET [Organization URI]/api/data/v9.0/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

Cependant, il existe un problème lors de l’utilisation des valeurs DateTimeOffset avec la syntaxe en ligne, comme expliqué dans l’article suivant : DateTimeOffset comme paramètre de requête #204.

Par conséquent, il est recommandé de transmettre les valeurs comme des paramètres comme illustré dans l'exemple de code suivant. Si vous suivez cette recommandation, vous pouvez éviter le problème non résolu qui s'applique à DateTimeOffset.

GET [Organization URI]/api/data/v9.0/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

Les alias des paramètres vous permettent également de réutiliser des valeurs de paramètres afin de réduire la longueur de l'URL lorsque la valeur du paramètre est utilisée plusieurs fois.

Passer une référence à une table à une fonction

Certaines fonctionnalités nécessitent la transmission d'une référence à une entité existante. Par exemple, les fonctions suivantes ont un paramètre qui nécessite un type d’entité crmbaseentity :

Fonctions
CalculateRollupField	IncrementKnowledgeArticleViewCount	InitializeFrom
IsValidStateTransition	RetrieveDuplicates	RetrieveLocLabels
RetrievePrincipalAccess	RetrieveRecordWall	ValidateRecurrenceRule

Lorsque vous transmettez une référence à une entité existante, utilisez l’annotation @odata.id de l’Uri pour l’entité. Par exemple, si vous utilisez la fonction RetrievePrincipalAccess, vous pouvez utiliser l’Uri suivant pour spécifier la récupération de l’accès à un contact spécifique :

GET [Organization URI]/api/data/v9.0/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'}

L'annotation @odata.id peut être un Uri complet, mais un Uri relatif fonctionne également.

Fonctions liées et non liées

Seules les fonctions se trouvant dans Web API Function Reference peuvent être liées. Les fonctions de requête ne sont jamais liées.

Fonctions liées

Dans le document de $métadonnées CSDL, lorsqu’un élément Function représente une fonction liée, il possède un attribut IsBound avec la valeur true. Le premier élément Parameter défini dans la fonction représente l'entité à laquelle la fonction est liée. Lorsque l’attribut Type du paramètre est une collection, la fonction est liée à une collection d’entités.

À titre d’exemple, voici la définition de la fonction RetrieveUserPrivileges et le type complexe RetrieveUserPrivilegesResponse dans le CSDL.

<ComplexType Name="RetrieveUserPrivilegesResponse">
  <Property Name="RolePrivileges" Type="Collection(mscrm.RolePrivilege)" />
</ComplexType
<Function Name="RetrieveUserPrivileges" IsBound="true">
    <Parameter Name="entity" Type="mscrm.systemuser" Nullable="false" />
    <ReturnType Type="mscrm.RetrieveUserPrivilegesResponse" Nullable="false" />
</Function>

Cette fonction de liaison d’entités est équivalente à la catégorie RetrieveUserPrivilegesRequest utilisée par le service Organisation. Dans l’API web, cette fonction est liée au type d’entité systemuser qui représente la RetrieveUserPrivilegesRequest.UserId propriété. Au lieu de renvoyer une instance de catégorie RetrieveUserPrivilegesResponse, cette fonction renvoie un type complexe RetrieveUserPrivilegesResponse. Lorsqu’une fonction renvoie un type complexe, sa définition apparaît généralement directement au-dessus de la définition de la fonction dans le CSDL.

Pour appeler une fonctionnalité liée, ajoutez le nom complet de la fonction à l'URL et incluez tous les paramètres nommés dans les parenthèses suivant le nom de la fonction. Le nom complet de la fonction comprend l'espace de nom Microsoft.Dynamics.CRM. Les fonctions qui ne sont pas liées ne doivent pas utiliser le nom complet.

Important

Une fonction liée doit être appelée à l'aide d'un URI afin de définir la première valeur de paramètre. Vous ne pouvez pas la définir comme une valeur de paramètre nommée.

L’exemple suivant montre un exemple utilisant la fonction RetrieveUserPrivileges, qui est liée à la table systemuser.

Requête

GET [Organization URI]/api/data/v9.2/systemusers(da455fec-68b7-ec11-9840-000d3a13d713)/Microsoft.Dynamics.CRM.RetrieveUserPrivileges HTTP/1.1
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Response

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  

{
  "@odata.context": "[Organization URI]/api/data/v8.2/$metadata#Microsoft.Dynamics.CRM.RetrieveUserPrivilegesResponse",
  "RolePrivileges": [
    {
      "Depth": "Global",
      "PrivilegeId": "20db4bf7-60c4-4eb9-ab95-0949766fef1a",
      "BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
      "PrivilegeName": "prvCreateflowsession"
    },
    {
      "Depth": "Global",
      "PrivilegeId": "d8db8e4c-5b76-48eb-b5ec-171b8c661917",
      "BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
      "PrivilegeName": "prvWriteworkflowbinary"
    },
    ... <full list of privileges removed for brevity>
    {
      "Depth": "Global",
      "PrivilegeId": "b234db9f-27a2-4d12-8b51-fc34fbef9d87",
      "BusinessUnitId": "dfe37870-c8ac-ec11-9841-0022482088be",
      "PrivilegeName": "prvWriteflowsession"
    }
  ]
}

Fonctions non liées

La fonction WhoAmI n’est pas liée à une entité. Elle est définie dans le CSDL sans attribut IsBound.

<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>  
<Function Name="WhoAmI">  
  <ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />  
</Function>

Cette fonction correspond à la catégorie WhoAmIRequest et renvoie un type complexe WhoAmIResponse qui correspond à la catégorie WhoAmIResponse utilisée par le service Organisation. Cette fonction n’a aucun paramètre.

Lorsque vous appelez une fonction non liée, utilisez uniquement le nom de la fonction comme illustré dans l'exemple suivant.

Demande

GET [Organization URI]/api/data/v9.0/WhoAmI() HTTP/1.1  
Accept: application/json  
OData-MaxVersion: 4.0  
OData-Version: 4.0

Réponse

HTTP/1.1 200 OK  
Content-Type: application/json; odata.metadata=minimal  
OData-Version: 4.0  
{  
 "@odata.context": "[Organization URI]/api/data/v9.0/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",  
 "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1",  
 "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1",  
 "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1"  
}

Composer une requête avec des fonctions

Deux méthodes permettent d'utiliser des fonctions pour contrôler les données renvoyées avec des requêtes. Certaines fonctions permettent de contrôler les colonnes ou les conditions qu'elles renvoient et vous utilisez des fonctions de requête pour évaluer des conditions dans une requête.

Fonctions composables

Certaines fonctions répertoriées dans Web API Function Reference renverront une collection d'entités. Un sous-ensemble de ces fonctions sont composables, ce qui signifie que vous pouvez inclure une option de requête système $select ou $filter supplémentaires pour contrôler les colonnes renvoyées dans les résultats. Ces fonctions ont un attribut IsComposable dans le CSDL. Chacune de ces fonctions comporte un message complémentaire dans le service de l'organisation qui accepte un ColumnSet ou un paramètre du type QueryBase . Les options de requête système OData offrent la même fonctionnalité afin que ces fonctions n'aient pas les mêmes paramètres que leurs messages complémentaires dans le service de l'organisation. Le tableau suivant répertorie une liste de ces fonctions composables dans cette version.

Fonctions
RetrieveAllChildUsersSystemUser	RetrieveBusinessHierarchyBusinessUnit	RetrieveUnpublishedMultiple
SearchByBodyKbArticle	SearchByKeywordsKbArticle	SearchByTitleKbArticle

Fonctions de requête

Les fonctions répertoriées dans Web API Query Function Reference sont prévues pour vous permettre de composer une requête. Ces fonctions peuvent être utilisées de façon similaires aux Fonctions de requête intégrées, mais il existe des différences importantes.

Vous devez utiliser le nom complet de la fonction et inclure des noms des paramètres. L’exemple suivant montre comment utiliser la fonction de requête LastXHours pour renvoyer toutes les entités de compte modifiées au cours des 12 dernières heures.

GET [Organization URI]/api/data/v9.0/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

Limites des fonctions de requête

L’une des limites des fonctions de requête est que vous ne pouvez pas utiliser l’opérateur not pour les annuler.

Par exemple, la requête suivante utilisant la fonction de requête EqualUserId échouera avec l’erreur : Not operator along with the Custom Named Condition operators is not allowed.

GET [Organization URI]/api/data/v9.1/systemusers?$select=fullname,systemuserid&$filter=not Microsoft.Dynamics.CRM.EqualUserId(PropertyName=@p1)&@p1='systemuserid'

Plusieurs fonctions de requête contiennent une fonction de requête d’annulation complémentaire. Par exemple, vous pouvez utiliser la fonction de requête NotEqualUserId. La requête suivante renvoie les résultats attendus :

GET [Organization URI]/api/data/v9.1/systemusers?$select=fullname,systemuserid&$filter=Microsoft.Dynamics.CRM.NotEqualUserId(PropertyName=@p1)&@p1='systemuserid'

D’autres fonctions de requête peuvent être annulées de différentes façons. Par exemple, plutôt que d’essayer de nier la fonction de requête Last7Days comme celle-ci (qui échouera avec la même erreur que celle mentionnée ci-dessus) :

GET [Organization URI]/api/data/v9.1/accounts?$select=name&$filter=not Microsoft.Dynamics.CRM.Last7Days(PropertyName=@p1)&@p1='createdon'

Utilisez la fonction de requête OlderThanXDays comme celle-ci :

GET [Organization URI]/api/data/v9.1/accounts?$select=name&$filter=Microsoft.Dynamics.CRM.OlderThanXDays(PropertyName=@p1,PropertyValue=@p2)&@p1='createdon'&@p2=7

Voir aussi

Exemple de fonctions et d’actions de l’API web (C#)
Exemple de fonctions et d'actions de l'API Web (JavaScript côté client)
Effectuer des opérations à l'aide de l'API Web
Composer des demandes Http et gérer les erreurs
Interroger les données à l'aide de l'API Web
Créer une table à l’aide de l’API web
Récupérer une table à l’aide de l’API web
Mettre à jour et supprimer des tables à l’aide de l’API Web
Associer et dissocier les tables à l'aide de l'API Web
Utiliser des actions API Web
Exécuter des opérations par lots à l'aide de l'API Web
Emprunter l’identité d’un autre utilisateur à l’aide de l’API Web
Effectuer les opérations conditionnelles à l’aide de l’API Web