Utiliser les fonctions de l’API Web

Article
08/24/2023

Les fonctions sont des opérations réutilisables que vous pouvez exécuter à l’aide de 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. Ces fonctions récupèrent généralement des données, une collection ou un type complexe. Chaque fonction 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. Chaque fonction de requête 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. Vous pouvez utiliser la syntaxe intégrée suivante :

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

Cependant, il existe un problème au moment 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.

Évitez le problème DateTimeOffset en transmettant les valeurs comme des paramètres comme illustré dans l’exemple de code suivant :

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

Si une valeur de paramètre est utilisée à plusieurs reprises, les alias des paramètres vous permettent de les réutiliser afin de réduire la longueur de l’URL.

Passer une référence à un enregistrements à une fonction

Certaines fonctionnalités 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 :

Fonctions
CalculateRollupField	IncrementKnowledgeArticleViewCount	InitializeFrom
IsValidStateTransition	RetrieveDuplicates	RetrieveLocLabels
RetrievePrincipalAccess	RetrieveRecordWall	ValidateRecurrenceRule

Quand vous transmettez une référence à un enregistrements existant, utilisez l’annotation @odata.id de l’Uri pour l’enregistrements. 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 enregistrement de 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 l’URI complet ou un URI relatif.

Fonctions liées et non liées

Seules les fonctions trouvées dans Web API Function Reference ou créées en tant qu’API personnalisée 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.

L’exemple suivant est 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 SDK pour .NET. Dans l’API web, cette fonction est liée au type d’entité systemuser qui représente la propriété RetrieveUserPrivilegesRequest.UserId. 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

Invoquez une fonction lié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 utilise la fonction RetrieveUserPrivileges, qui est liée à la table systemuser.

Demande :

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 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 SDK pour .NET. Cette fonction n’a aucun paramètre.

Lorsque vous invoquez 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 renvoient 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 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 SDK 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 SDK. 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 OData, 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 utilise 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, qui utilise EqualUserId, échoue avec l’erreur suivante : 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, NotEqualUserId infirme EqualUserId, la requête suivante renvoie donc 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 précédemment) :

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

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).