Utiliser des fonctions API Web

Article
10/31/2017

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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.

Contenu de la rubrique

Transmission de paramètres à une fonction

Transmettre une référence d'une entité à une fonction

Fonctions liées et non liées

Composer une requête avec des fonctions

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 GetTimeZoneCodeByLocalizedName Function, 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 cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)

Toutefois, il existe un problème non résolu concernant l'utilisation de valeurs DateTimeOffset avec la syntaxe intégrée, comme décrit dans l'article suivant : DateTimeOffset comme paramètre de requête n° 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 cc_WebAPI_ServiceURI/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.

Transmettre une référence d'une entité à une fonction

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

CalculateRollupField Function	IncrementKnowledgeArticleViewCount Function	InitializeFrom Function
IsValidStateTransition Function	RetrieveDuplicates Function	RetrieveLocLabels Function
RetrievePrincipalAccess Function	RetrieveRecordWall Function	ValidateRecurrenceRule Function

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 RetrievePrincipalAccess Function vous pouvez utiliser l'Uri suivant pour spécifier la récupération de l'accès à un contact spécifique :

GET cc_WebAPI_ServiceURI/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

Seuls 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 d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_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. Par exemple, voici la définition de la CalculateTotalTimeIncident Function et du CalculateTotalTimeIncidentResponse ComplexType dans le CSDL.

<ComplexType Name="CalculateTotalTimeIncidentResponse">
  <Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
  <Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
  <ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>

Cette fonction liée est équivalente à l'objet CalculateTotalTimeIncidentRequest utilisée par le service de l'organisation. Dans l'API Web, cette fonction est liée à l'objet incident EntityType qui représente la propriété CalculateTotalTimeIncidentRequest.IncidentId. Au lieu de renvoyer une CalculateTotalTimeIncidentResponse, cette fonction renvoie un CalculateTotalTimeIncidentResponse ComplexType. Lorsqu'une fonction renvoie un type complexe, sa définition apparaît 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 illustre un exemple d'utilisation de CalculateTotalTimeIncident Function, qui est lié à l'entité de l'incident.

Demande

GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() 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":"cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse","TotalTime":30
}

Fonctions non liées

La WhoAmI Function 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 WhoAmIRequest et renvoie un WhoAmIResponse ComplexType qui correspond à la WhoAmIResponse utilisée par le service de l'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 cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$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és 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.

GetDefaultPriceLevel Function	RetrieveAllChildUsersSystemUser Function	RetrieveBusinessHierarchyBusinessUnit Function
RetrieveByGroupResource Function	RetrieveByResourceResourceGroup Function	RetrieveMembersBulkOperation Function
RetrieveParentGroupsResourceGroup Function	RetrieveSubGroupsResourceGroup Function	RetrieveUnpublishedMultiple Function
SearchByBodyKbArticle Function	SearchByKeywordsKbArticle Function	SearchByTitleKbArticle Function

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 Fonctionnalités de requête standard, 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 indique comment utiliser la LastXHours Function pour renvoyer toutes les entités de compte modifiées au cours des 12 dernières heures.

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

Voir aussi

Microsoft Dynamics 365

Utiliser des fonctions API Web

Contenu de la rubrique

Transmission de paramètres à une fonction

Transmettre une référence d'une entité à une fonction

Fonctions liées et non liées

Fonctions liées

Fonctions non liées

Composer une requête avec des fonctions

Fonctions composables

Fonctions de requête

Voir aussi

Ressources supplémentaires