Exemple de fonctions et d’actions de l’API Web
Notes
Vous n’êtes pas sûr de l’entité par rapport à la table ? Voir Développeurs : Comprendre la terminologie dans Microsoft Dataverse.
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 Dataverse. 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.
Les sections suivantes contiennent un bref examen des opérations de l’API web Dataverse 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 Dataverse. 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_AddNoteToContactdans 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
Les Fonctions sont des opérations qui n’ont pas d’effets secondaires. Une fonction peut être liée à une ligne de table ou à une collection de table (type d’entité). 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 en utilisant la fonction WhoAmI. 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.
Obtenez la demande et la réponse pour la fonction WhoAmI.
Requête
GET https://[Organization URI]/api/data/v9.0/WhoAmI HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Response
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 273
{
"@odata.context":"https://[Organization URI]/api/data/v9.0/$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, voir : Transmission de paramètres à une fonction
Demande
GET https://[Organization URI]/api/data/v9.0/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/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 154
{
"@odata.context":"https://[Organization URI]/api/data/v9.0/$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, voir : Fonctions liées
Demande
GET https://[Organization URI]/api/data/v9.0/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/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 148
{
"@odata.context":"https://[Organization URI]/api/data/v9.0/$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
Les 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 clôt une opportunité et la marque comme gagnée en appelant l’action WinOpportunity. L’entité de type opportunity a été créée en tant qu’exemple de données plus tôt dans le programme. Pour plus d’informations : Actions non liées
Demande
POST https://[Organization URI]/api/data/v9.0/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":"https://[Organization URI]/api/data/v9.0/opportunities(47920da5-fb4a-e611-80d5-00155da84802)"
}
}
Réponse
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 la fonction WhoAmI et l’entité de type systemuser pour obtenir une référence à la file d’attente de l’utilisateur actuel. Nous avons également besoin de référence à l’entité de type letter. Cette lettre a été créée en tant qu’exemple de données précédemment dans le programme. Puis l’action AddToQueue 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
POST https://[Organization URI]/api/data/v9.0/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/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 170
{
"@odata.context":"https://[Organization URI]/api/data/v9.0/$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 Dataverse. 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, voir : 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 unNoteTitleet l’autre est unNoteText. Cette action personnalisée ajoute une note à un type d’entité contact. Vous trouverez ci-dessous une capture d’écran de la page Informations pour cette action personnalisée.
sample_CreateCustomer: action personnalisée non liée qui nécessite différents paramètres en fonction du type de client créé. Par exemple, lorsqueAccountTypeest « compte », il nécessite uniquement le paramètreAccountName. LorsqueAccountTypeest « contacts », les paramètresContactFirstNameetContactLastNamesont requis. Vous trouverez ci-dessous une capture d’écran de la page Informations pour cette action personnalisée.
Utilisation d’une action personnalisée liée avec paramètres
Cet exemple appelle l’action personnalisée sample_AddNoteToContact qui est liée à la table des contacts avec les paramètres requis. Cette action personnalisée ajoute une remarque à un contact existant. Cette action renvoie une ligne 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
POST https://[Organization URI]/api/data/v9.0/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/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 149
{
"@odata.context":"https://[Organization URI]/api/data/v9.0/$metadata#annotations/$entity",
"annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802"
}
La demande et la réponse de l’annotation.
Demande
GET https://[Organization URI]/api/data/v9.0/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/1.1 200 OK
OData-Version: 4.0
Content-Length: 450
{
"@odata.context":"https://[Organization URI]/api/data/v9.0/$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
POST https://[Organization URI]/api/data/v9.0/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/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
POST https://[Organization URI]/api/data/v9.0/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"
}
Response
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."
}
}
Sortie de la console
Expected custom error: ContactFirstName and ContactLastName are required when CustomerType is contact.
Voir aussi
Utilisation de l’API web Dataverse
Utiliser des fonctions API Web
Utiliser des actions API Web
Exemple de fonctions et d’actions de l’API Web (C#)
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é).
Commentaires
Envoyer et afficher des commentaires pour