Partage via

Utiliser les fonctions d’API web

Les fonctions sont des opérations réutilisables que vous pouvez effectuer à l’aide de l’API web. L’API web comprend deux types de fonctions :

  • Fonctions : utilisez une GET requête avec les fonctions répertoriées dans la Web API Function Reference liste pour effectuer des opérations qui n’ont aucun effet secondaire. Ces fonctions récupèrent généralement des données, soit une collection, soit un type complexe. Chaque fonction a un message correspondant dans le service d’organisation.

  • Fonctions de requête : utilisez les fonctions répertoriées dans la Web API Query Function Reference liste pour évaluer les propriétés et les valeurs dans la composition d’une requête. Chaque fonction de requête a une valeur correspondante ConditionOperator .

Passage de paramètres à une fonction

Pour les fonctions qui nécessitent des paramètres, transmettez les valeurs à l’aide d’alias de paramètre.

Par exemple, lorsque vous utilisez la fonction GetTimeZoneCodeByLocalizedName, vous devez inclure les valeurs des paramètres LocalizedStandardName et LocaleId. Vous pouvez utiliser la syntaxe inline suivante :

GET/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

Toutefois, quelques problèmes peuvent entraîner l’échec des requêtes, sauf si vous envoyez ces requêtes à l’aide d’alias de paramètre :

Évitez ces problèmes en transmettant les valeurs à l’aide d’alias de paramètre, comme indiqué dans l’exemple de code suivant :

GET /GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033

Lorsque vous utilisez une valeur de paramètre plusieurs fois, les alias de paramètre vous permettent de le réutiliser pour réduire la longueur de l’URL.

Passer la référence d’enregistrement à une fonction

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

CalculateRollupField

IncrementKnowledgeArticleViewCount

InitializeFrom

IsValidStateTransition

RetrieveDuplicates

RetrieveLocLabels

RetrievePrincipalAccess

RetrieveRecordWall

ValidateRecurrenceRule

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

GET /systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(aaaabbbb-0000-cccc-1111-dddd2222eeee)'}

L’annotation @odata.id peut être l’URI complet ou un URI relatif.

Fonctions liées et indépendantes

Vous pouvez lier uniquement les fonctions trouvées dans Web API Function Reference ou les fonctions que vous créez en tant qu’API personnalisée. Les fonctions de requête ne sont jamais liées.

Fonctions liées

Dans le document CSDL $metadata, lorsqu’un Function élément représente une fonction liée, il a un IsBound attribut avec la valeur true. Le premier Parameter élément 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.

L’exemple suivant est la définition de la fonction RetrieveUserPrivileges et du 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 liée équivaut au SDK pour la classe .NET RetrieveUserPrivilegesRequest. Dans l’API web, cette fonction est liée au systemuser type d’entité qui représente la propriété UserId de RetrieveUserPrivilegesRequest dans le Kit de développement logiciel (SDK) pour .NET. Au lieu de retourner une instance du Kit de développement logiciel (SDK) pour la classe .NET RetrieveUserPrivilegesResponse, cette fonction retourne un RetrieveUserPrivilegesResponse type complexe. Lorsqu’une fonction retourne un type complexe, sa définition apparaît généralement directement au-dessus de la définition de la fonction dans le document CSDL $metadata.

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

Important

Appelez une fonction liée à l’aide d’un URI pour définir la première valeur de paramètre. Vous ne pouvez pas le définir en tant que valeur de paramètre nommée.

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

Requête :

GET [Organization URI]/api/data/v9.2/systemusers(da455fec-68b7-ec11-9840-000d3a13d713)/Microsoft.Dynamics.CRM.RetrieveUserPrivileges
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/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 indépendantes

La WhoAmI fonction n’est pas liée à une entité. Il est défini dans le document CSDL $metadata sans IsBound attribut.

<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 au SDK pour la classe .NET WhoAmIRequest et retourne un WhoAmIResponse type complexe qui correspond au SDK pour la classe .NET WhoAmIResponse. Cette fonction n’a aucun paramètre.

Lorsque vous appelez une fonction indépendante, utilisez simplement le nom de la fonction, comme illustré dans l’exemple suivant :

Requête :

GET [Organization URI]/api/data/v9.2/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.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",  
 "BusinessUnitId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",  
 "UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",  
 "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"  
}

Composer une requête avec des fonctions

Vous pouvez utiliser des fonctions de deux façons pour contrôler les données retournées par des requêtes. Certaines fonctions vous permettent de contrôler les colonnes et les conditions qu’elles retournent. Vous pouvez également utiliser des fonctions de requête pour évaluer les conditions d’une requête.

Fonctions composables

Certaines fonctions répertoriées dans Web API Function Reference retournent une collection d’entités. Un sous-ensemble de ces fonctions est composable, ce qui signifie que vous pouvez inclure une option de requête système $select ou $filter pour contrôler les colonnes retournées dans les résultats. Ces fonctions ont un IsComposable attribut dans le CSDL. Chacune de ces fonctions a un message complémentaire dans le Kit de développement logiciel (SDK) qui accepte un SDK pour la classe .NET ColumnSet ou le SDK pour le paramètre de type de classe .NET QueryBase . Les options de requête système OData fournissent les mêmes fonctionnalités. Ces fonctions n’ont donc pas les mêmes paramètres que leurs messages complémentaires dans le Kit de développement logiciel (SDK) pour .NET. Le tableau suivant présente une liste de fonctions composables :

RetrieveAllChildUsersSystemUser

RetrieveBusinessHierarchyBusinessUnit

RetrieveUnpublishedMultiple

SearchByBodyKbArticle

SearchByKeywordsKbArticle

SearchByTitleKbArticle

Fonctions de requête

Utilisez les fonctions répertoriées dans la Web API Query Function Reference liste pour composer une requête. Vous pouvez les utiliser de manière similaire aux fonctions de requête OData, mais il existe des différences importantes. Vous devez utiliser le nom complet de la fonction et inclure les noms des paramètres.

L’exemple suivant utilise la LastXHours fonction de requête pour retourner toutes les entités de compte modifiées au cours des 12 dernières heures :

GET /accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

Limitations des fonctions de requête

Une limitation des fonctions de requête est que vous ne pouvez pas utiliser l’opérateur not pour négation des fonctions de requête.

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

GET /systemusers?$select=fullname,systemuserid&$filter=not Microsoft.Dynamics.CRM.EqualUserId(PropertyName=@p1)&@p1='systemuserid'

Plusieurs fonctions de requête ont une fonction de requête négative correspondante. Par exemple, NotEqualUserId annule EqualUserId, donc la requête suivante retourne les résultats attendus:

GET /systemusers?$select=fullname,systemuserid&$filter=Microsoft.Dynamics.CRM.NotEqualUserId(PropertyName=@p1)&@p1='systemuserid'

D’autres fonctions de requête peuvent être supprimées de différentes manières. Plutôt que d’essayer de nier la Last7Days fonction de requête comme ceci (ce qui échoue avec la même erreur que celle mentionnée précédemment) :

GET /accounts?$select=name&$filter=not Microsoft.Dynamics.CRM.Last7Days(PropertyName=@p1)&@p1='createdon'

Utilisez la OlderThanXDays fonction de requête comme suit :

GET /accounts?$select=name&$filter=Microsoft.Dynamics.CRM.OlderThanXDays(PropertyName=@p1,PropertyValue=@p2)&@p1='createdon'&@p2=7

Voir aussi

Fonctions et actions de l’API web - Exemple (C#)
Fonctions et actions de l’API web - Exemple (JavaScript côté client)
Exemple de Fonctions et Actions d'API Web (PowerShell)
Interroger des données à l’aide de l’API web
Utiliser des actions API Web

  • Last updated on