Utiliser les fonctions d’API web

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

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 ces fonctions qui nécessitent des paramètres, la meilleure pratique consiste à transmettre 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 [Organization URI]/api/data/v9.2/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

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

Vous pouvez obtenir une 400 Bad Request - Invalid URL erreur si vous dépassez la longueur maximale du segment OData
Il existe un problème lié à l’utilisation de valeurs DateTimeOffset avec la syntaxe inline, comme expliqué dans l’article suivant : DateTimeOffset en tant que paramètre de requête #204.

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

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

Lorsqu’une valeur de paramètre est utilisée 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 :

Functions
CalculateRollupField	IncrementKnowledgeArticleViewCount	InitializeFrom
IsValidStateTransition	RetrieveDuplicates	RetrieveLocLabels
RetrievePrincipalAccess	RetrieveRecordWall	ValidateRecurrenceRule

Lorsque vous transmettez une référence à un enregistrement existant, utilisez 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 [Organization URI]/api/data/v9.2/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

Seules les fonctions trouvées dans , ou créées en tant qu'une API personnalisée peuvent être liées. 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 à la RetrieveUserPrivilegesRequest classe utilisée par le Kit de développement logiciel (SDK) pour .NET. Dans l’API web, cette fonction est liée au systemuser type d’entité qui représente la propriété RetrieveUserPrivilegesRequest.UserId . Au lieu de retourner une instance de la RetrieveUserPrivilegesResponse classe, 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 CSDL.

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 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/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é. Elle est définie dans le CSDL 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 à la WhoAmIRequest classe et retourne un WhoAmIResponse type complexe qui correspond à la WhoAmIResponse classe utilisée par le Kit de développement logiciel (SDK) pour .NET. 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

Il existe deux façons dont les fonctions peuvent être utilisées pour contrôler les données retournées avec des requêtes. Certaines fonctions permettent de déterminer les colonnes ou les conditions qu’elles renvoient, et vous pouvez 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 possède un message complémentaire dans le Kit de développement logiciel (SDK) qui accepte soit un paramètre de type ColumnSet, soit un paramètre de type QueryBase. Les options de requête système OData fournissent les mêmes fonctionnalités afin que ces fonctions n’aient pas les mêmes paramètres que leurs messages complémentaires dans le Kit de développement logiciel (SDK). Le tableau suivant présente la liste de ces fonctions composables dans cette version.

Functions
RetrieveAllChildUsersSystemUser	RetrieveBusinessHierarchyBusinessUnit	RetrieveUnpublishedMultiple
SearchByBodyKbArticle	SearchByKeywordsKbArticle	SearchByTitleKbArticle

Fonctions de requête

Les fonctions répertoriées dans le Web API Query Function Reference fichier sont destinées à être utilisées 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 [Organization URI]/api/data/v9.2/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12

Limitations des fonctions de requête

L’une des limitations 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 [Organization URI]/api/data/v9.2/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 [Organization URI]/api/data/v9.2/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. Par exemple, plutôt que d’essayer de nier la Last7Days fonction de requête de cette manière (qui échoue avec la même erreur que celle mentionnée précédemment) :

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

Utilisez la OlderThanXDays fonction de requête comme suit :

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

Voir aussi

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-10-04