Exemple de fonctions et d'actions de l'API Web
Date de publication : janvier 2017
S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Ce groupe d'exemples montre comment exécuter des fonctions et des actions liées et non liées, notamment des actions personnalisées, à l'aide de l'API Web Microsoft Dynamics 365. Cet exemple est mis en œuvre comme un projet distinct pour les langues suivantes :
Cette rubrique décrit la structure et le contenu de l'exemple à un niveau de langue neutre supérieur. Examinez les exemples de rubriques liées ci-dessus pour les détails de mise en œuvre spécifiques à chaque langue sur la façon d'exécuter les opérations décrites dans cette rubrique.
Montre ce qui suit
Cet exemple est composé des principales sections suivantes, qui contiennent les opérations de fonctions et d'actions de l'API Web qui sont décrites plus en détail dans les rubriques conceptuelles associées.
Section de la rubrique |
Rubrique(s) associée(s) |
|---|---|
Exemple de données |
|
Utilisation d'une fonction non liée sans paramètres |
|
Utilisation d'une fonction non liée avec paramètres |
|
Utilisation d'une fonction liée sans paramètres |
|
Utilisation d'une action non liée avec paramètres |
|
Utilisation d'une action liée avec paramètres |
|
Utilisation d'une action personnalisée liée avec paramètres |
|
Utilisation d'une action personnalisée non liée avec paramètres |
|
Gestion des exceptions d'action personnalisée |
Les sections suivantes contiennent un bref examen des opérations de l'API Web Dynamics 365 effectuées, ainsi que les messages HTTP et la sortie de la console associée correspondants.
Exemple de données
Pour vous assurer que les opérations de cet exemple fonctionnent correctement, nous créons d'abord des exemples de données sur le serveur Dynamics 365. Ces exemples de données seront supprimés du serveur sauf si l'utilisateur choisit de ne pas les supprimer. Les données de cet exemple sont créées séparément comme suit.
Créez un compte (par exemple : Fourth Coffee) et associez-le à un incident avec trois tâches de 30 minutes (90 minutes au total). Une fois les tâches créées, elles sont alors marquées comme terminées. L'opération calcule le temps total qu'elle a pris pour effectuer ces trois tâches.
{ title: "Sample Case", "customerid_account@odata.bind": accountUri, Incident_Tasks: [ { subject: "Task 1", actualdurationminutes: 30 }, { subject: "Task 2", actualdurationminutes: 30 }, { subject: "Task 3", actualdurationminutes: 30 } ] };Créez un compte et associez-le à une opportunité. Cette opportunité sera marquée comme conclue dans l'exemple d'opération.
{ name: "Sample Account for WebAPIFunctionsAndActions sample", opportunity_customer_accounts: [{ name: "Opportunity to win" }] };Créez une activité de lettre. La lettre est ajoutée à la file d'attente de l'utilisateur actuel dans l'exemple d'opération.
{ description: "Example letter" }Créez un contact à utiliser avec une action personnalisée sample_AddNoteToContact dans l'exemple d'opération.
{ firstname: "Jon", lastname: "Fogg" }
Exemples d'opérations
Les exemples d'opérations de cette rubrique sont organisés des manières suivantes.
Utilisation des fonctions : Ces opérations utilisent des fonctions liées et non liées qui acceptent les paramètres ou non.
Utilisation des actions : Ces opérations utilisent des actions liées et non liées qui acceptent les paramètres ou non.
Actions personnalisées : Ces opérations utilisent des actions liées et non liées et comment gérer les exceptions d'erreurs personnalisées.
Utilisation des fonctions
Fonctions sont des opérations qui n'ont pas d'effets secondaires. Une fonction peut être liée à une instance d'entité ou à une collection d'entités. Les fonctions de requête ne sont jamais liées. Pour plus d'informations, voir Utiliser des fonctions API Web. Cette section présente des exemples de la manière dont les fonctions liées et non liées sont utilisées et de la façon dont les paramètres sont transmis.
Utilisation d'une fonction non liée sans paramètres
Utilisez une fonction non liée pour récupérer le nom complet de l'utilisateur actuel à l'aide de WhoAmI Function. Cette opération montre comment appeler une fonction non liée qui n'accepte pas les paramètres. Cette opération renvoie le nom complet de l'utilisateur actuel.
Obtention de la demande et de la réponse pour WhoAmI Function.
Demande HTTP
GET http://cc_WebAPI_ServiceURI/WhoAmI HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Réponse HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 273
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
"BusinessUnitId":"0d6cc84a-d3f6-e511-80d0-00155da84802",
"UserId":"b08dc84a-d3f6-e511-80d0-00155da84802",
"OrganizationId":"0f47eae2-a906-4ae4-9215-f09875979f6a"
}
Utilisation d'une fonction non liée avec paramètres
Utilisez une fonction non liée pour récupérer le code de fuseau horaire. Cette opération montre comment appeler une fonction non liée qui accepte les paramètres. Cette opération renvoie le code de fuseau horaire actuel du fuseau horaire spécifié.Pour plus d'informations :Transmission de paramètres à une fonction
Demande HTTP
GET http://cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific%20Standard%20Time'&@p2=1033 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Réponse HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 154
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.GetTimeZoneCodeByLocalizedNameResponse",
"TimeZoneCode":4
}
Sortie de la console
Unbound function: GetTimeZoneCodeByLocalizedName
Function returned time zone Pacific Standard Time, with code '4'.
Utilisation d'une fonction liée sans paramètres
Utilisez une fonction liée pour récupérer le temps total qu'elle a pris pour effectuer toutes les tâches d'un incident. Cette opération montre comment appeler une fonction liée qui n'accepte pas les paramètres. Cette opération renvoie le nombre total de minutes que l'incident a pris pour fermer toutes ses tâches. Cette fonction fait appel également aux données de l'incident que nous avons créé pour cet exemple de programme.Pour plus d'informations :Fonctions liées
Demande HTTP
GET http://cc_WebAPI_ServiceURI/incidents(3d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Réponse HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 148
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse",
"TotalTime":90
}
Sortie de la console
Bound function: CalculateTotalTimeIncident
Function returned 90 minutes - total duration of tasks associated with the incident.
Utilisation des actions
Actions sont des opérations autorisent les effets secondaires. Une action est liée ou non liée. Pour plus d'informations, voir Utiliser des actions API Web. Cette section présente des exemples de la manière dont les actions liées et non liées sont utilisées et de la façon dont les paramètres sont transmis. Elle indique également comment les actions personnalisées sont utilisées et comment gérer les exceptions à ces actions personnalisées.
Utilisation d'une action non liée avec paramètres
Utilisez une action non lié qui reçoit un jeu de paramètres. Cette opération ferme une opportunité et la marque comme conclue en appelant l'WinOpportunity Action. L'opportunity EntityType a été créé en tant qu'exemple de données précédemment dans le programme.Pour plus d'informations :Actions non liées
Demande HTTP
POST http://cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
{
"Status":3,
"OpportunityClose":{
"subject":"Won Opportunity",
"opportunityid@odata.bind":"http://cc_WebAPI_ServiceURI/opportunities(47920da5-fb4a-e611-80d5-00155da84802)"
}
}
Réponse HTTP
HTTP/1.1 204 No Content
OData-Version: 4.0
Sortie de la console
Unbound Action: WinOpportunity
Opportunity won.
Utilisation d'une action liée avec paramètres
Utilisez une action lié qui accepte les paramètres. Cette opération ajoute une lettre à la file d'attente de l'utilisateur actuel. Pour ce faire, nous utilisons WhoAmI Function et systemuser EntityType pour obtenir une référence à la file d'attente de l'utilisateur actuel. Nous avons également besoin de référence à letter EntityType. Cette lettre a été créée en tant qu'exemple de données précédemment dans le programme. Puis l'action AddToQueue Action liée est appelée pour ajouter la lettre à la file d'attente de l'utilisateur actuel.Pour plus d'informations :Actions liées
Demande HTTP
POST http://cc_WebAPI_ServiceURI/queues(1f7bcc50-d3f6-e511-80d0-00155da84802)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 110
{
"Target":{
"activityid":"4c920da5-fb4a-e611-80d5-00155da84802",
"@odata.type":"Microsoft.Dynamics.CRM.letter"
}
}
Réponse HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 170
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
"QueueItemId":"67bdfabd-fc4a-e611-80d5-00155da84802"
}
Sortie de la console
Bound Action: AddToQueue
QueueItemId returned from AddToQueue Action: 67bdfabd-fc4a-e611-80d5-00155da84802
Utilisation des actions personnalisées
Si vous définissez des actions personnalisées pour votre solution, vous pouvez les appeler à l'aide de l'API Web Dynamics 365. Indépendamment du fait que les opérations incluses dans votre action personnalisée aient des effets secondaires, elles peuvent permettre de modifier les données et par conséquent, elles peuvent être considérées comme des actions plutôt que des fonctionnalités. Il n'existe aucun moyen de créer une fonctionnalité personnalisée.Pour plus d'informations :Utiliser une action personnalisée.
Cet exemple propose deux actions personnalisées. Toutes deux nécessitent des paramètres mais l'une est liée et l'autre est non liée.
sample_AddNoteToContact : action personnalisée liée qui accepte deux paramètres. L'un est un NoteTitle et l'autre est un NoteText. Cette action personnalisée ajoute une remarque à un contact EntityType. Vous trouverez ci-dessous une capture d'écran de la page Informations pour cette action personnalisée.
.jpeg "Custom Action - AddNoteToContact information")
sample_CreateCustomer : action personnalisée non liée qui nécessite différents paramètres en fonction du type de client créé. Par exemple, lorsque AccountType est « compte », il nécessite uniquement le paramètre AccountName. Lorsque AccountType est « contacts », les paramètres ContactFirstName et ContactLastName sont requis. Vous trouverez ci-dessous une capture d'écran de la page Informations pour cette action personnalisée.
.jpeg "Custom Action - CreateCustomer information")
Utilisation d'une action personnalisée liée avec paramètres
Cet exemple appelle l'action personnalisée sample_AddNoteToContact qui est liée à l'entité du contact avec les paramètres requis. Cette action personnalisée ajoute une remarque à un contact existant. Cette action renvoie une entité avec une propriété annotationid. Pour afficher que cette remarque a été ajoutée, l'annotationid est utilisé pour demander des informations sur la remarque.
La demande et la réponse de l'action.
Demande HTTP
POST http://cc_WebAPI_ServiceURI/contacts(4d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.sample_AddNoteToContact HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 80
{
"NoteTitle":"The Title of the Note",
"NoteText":"The text content of the note."
}
Réponse HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 149
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
"annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802"
}
La demande et la réponse de l'annotation.
Demande HTTP
GET http://cc_WebAPI_ServiceURI/annotations(ba146d0b-fd4a-e611-80d5-00155da84802)?$select=subject,notetext&$expand=objectid_contact($select=fullname) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Réponse HTTP
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: 450
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations(subject,notetext,objectid_contact,objectid_contact(fullname))/$entity",
"@odata.etag":"W/\"622978\"",
"subject":"The Title of the Note",
"notetext":"The text content of the note.",
"annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802",
"objectid_contact":{
"@odata.etag":"W/\"622968\"",
"fullname":"Jon Fogg",
"contactid":"4d920da5-fb4a-e611-80d5-00155da84802"
}
}
Sortie de la console
Custom action: sample_AddNoteToContact
A note with the title 'The Title of the Note' and the content 'The text content of the note.' was created and associated with the contact Jon Fogg.
Utilisation d'une action personnalisée non liée avec paramètres
Cette opération appelle l'action personnalisée sample_CreateCustomer pour créer un client« compte ». Les paramètres requis sont transmis pour CustomerType de account.
Demande HTTP
POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103
{
"CustomerType":"account",
"AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}
Réponse HTTP
HTTP/1.1 204 No Content
OData-Version: 4.0
Gestion des exceptions d'action personnalisée
Cet exemple indique que les actions personnalisées peuvent renvoyer des messages d'erreur personnalisés. Vous pouvez gérer les exceptions personnalisées de la même façon que vous gérez les exceptions standard. Pour recevoir le message d'erreur personnalisé de l'action personnalisée sample_CreateCustomer , cet exemple crée un client « contact ». Toutefois, nous transmettons volontairement des paramètres incorrects pour ce paramètre CustomerType. Cette opération intercepte ensuite l'exception et affiche le message d'erreur, puis continue avec l'exemple de programmes.
Demande HTTP
POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103
{
"CustomerType":"contact",
"AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}
Réponse HTTP
HTTP/1.1 500 Internal Server Error
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 2760
{
"error":{
"code":"",
"message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
"innererror":{
"message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
...[truncated]
}
}
}
Sortie de la console
Expected custom error: ContactFirstName and ContactLastName are required when CustomerType is contact.
Voir aussi
Utilisez l'API Web Microsoft Dynamics 365
Utiliser des fonctions API Web
Utiliser des actions API Web
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)
Microsoft Dynamics 365
© 2017 Microsoft. Tous droits réservés. Copyright