Utiliser les actions de l’API Web

Article
09/21/2023

Les actions et les fonctions représentent des opérations réutilisables que vous pouvez effectuer avec l’API Web. Utilisez une requête POST avec les actions répertoriées dans Web API Action Reference pour effectuer des opérations qui ont des effets secondaires. Vous pouvez également définir des actions personnalisées. Pour plus d’informations, voir : Créer vos propres messages.

Les actions sont définies dans le document CSDL $métadonnées. Voir Actions de l’API web pour en savoir plus.

Actions non liées

Le XML suivant est la définition de l’action Merge représentée dans le document de service $metadata.

<Action Name="Merge">
   <Parameter Name="Target" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="Subordinate" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="UpdateContent" 
      Type="mscrm.crmbaseentity" />
   <Parameter Name="PerformParentingChecks" 
      Type="Edm.Boolean" 
      Nullable="false" />
</Action>

L’action Merge correspond à MergeRequest en utilisant le SDK pour .NET. Utilisez cette action pour fusionner une paire d’enregistrements en double. Cette action ne contient aucune valeur de retour. Si elle aboutit, l’opération est terminée.

L’exemple suivant est la requête et la réponse HTTP pour appeler l’action Merge pour deux enregistrements de compte.

Demande :

POST [Organization URI]/api/data/v9.2/Merge HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
  "Target": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "cc1e2c4a-e577-ec11-8d21-000d3a554dcd"
  },
  "Subordinate": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "e408fa45-3a70-ec11-8943-00224823561e"
  },
  "PerformParentingChecks": false
}

Réponse :

HTTP/1.1 204 No Content
OData-Version: 4.0

Plus d’informations : Fusionner les lignes de table à l’aide de l’API web

Actions liées

Une action peut être liée de deux manières. La manière la plus courante est que l’action soit liée à une entité. Moins fréquemment, il peut également être lié à une collection d’entités.

Dans le Document de métadonnées $ CSDL, lorsqu’un élément Action représente une action liée, il possède un attribut IsBound avec la valeur true. Le premier élément Parameter défini dans l’action représente l’entité à laquelle l’opération est liée. Lorsque l’attribut du paramètre Type est une collection, l’opération est liée à une collection d’entités.

En appelant une fonctionnalité associée, vous devez inclure le nom complet de la fonction notamment l’espace de noms Microsoft.Dynamics.CRM. Si vous n’incluez pas le nom complet, vous recevez l’erreur suivante : Status Code:400 Request message has unresolved parameters.

Actions liées à une table

À titre d’exemple d’action liée à une entité, voici la définition de l’action AddToQueue représentée dans le CSDL :

 <ComplexType Name="AddToQueueResponse">
     <Property Name="QueueItemId" 
        Type="Edm.Guid" 
        Nullable="false" />
 </ComplexType>
 <Action Name="AddToQueue" 
    IsBound="true">
  <Parameter Name="entity" 
    Type="mscrm.queue" 
    Nullable="false" />
  <Parameter Name="Target" 
    Type="mscrm.crmbaseentity" 
    Nullable="false" />
  <Parameter Name="SourceQueue" 
    Type="mscrm.queue" />
  <Parameter Name="QueueItemProperties" 
    Type="mscrm.queueitem" />
  <ReturnType Type="mscrm.AddToQueueResponse" 
    Nullable="false" />
</Action>

Cette action de liaison d’entités est équivalente à AddToQueueRequest utilisée par le SDK pour .NET. Dans l’API Web, cette action est liée au type d’entité queue qui représente AddToQueueRequest.DestinationQueueId propriété. Cette action accepte plusieurs paramètres supplémentaires et renvoie un type complexe AddToQueueResponse correspondant à AddToQueueResponse renvoyé par le SDK pour .NET. Lorsqu’une action renvoie un type complexe, la définition du type complexe apparaît directement au-dessus de l’action dans le langage CSDL.

Une action liée à une entité doit être appelée à l’aide d’un URI pour 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 montre comment utiliser l’action AddToQueue pour ajouter une lettre à une file d’attente. Comme le type de paramètre Target n’est pas spécifique (mscrm.crmbaseentity), vous devez déclarer explicitement le type de l’objet à l’aide de la valeur de propriété @odata.type du nom complet de l’entité, notamment l’espace de noms Microsoft.Dynamics.CRM. Dans ce cas, Microsoft.Dynamics.CRM.letter. Pour plus d’informations, voir : Spécifier le type de paramètre d’entité

Demande :

POST [Organization URI]/api/data/v9.0/queues(56ae8258-4878-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "Target": {
  "activityid": "59ae8258-4878-e511-80d4-00155d2a68d1",
  "@odata.type": "Microsoft.Dynamics.CRM.letter"
 }
}

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.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Actions liées à une collection de tables

Il est moins courant de trouver des actions liées à une collection d’entités. Voici celles que vous pouvez trouver :

FulfillSalesOrder dans Dynamics 365 for Sales

CreateMultiple

UpdateMultiple

À titre d’exemple d’action liée à une entité collection, voici la définition de l’action ExportTranslation représentée dans le document de $métadonnées CSDL :

<ComplexType Name="ExportTranslationResponse">
   <Property Name="ExportTranslationFile" 
    Type="Edm.Binary" />
</ComplexType>
<Action Name="ExportTranslation" 
    IsBound="true">
   <Parameter Name="entityset" 
    Type="Collection(mscrm.solution)" 
    Nullable="false" />
   <Parameter Name="SolutionName" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
   <ReturnType Type="mscrm.ExportTranslationResponse" 
    Nullable="false" />
</Action>

Cette action de liaison de collection d’entités est équivalente à ExportTranslationRequest utilisée par le SDK pour .NET. Dans l’API Web, cette action est liée au type d’entité solution. Mais plutôt que de transmettre une valeur à la demande, la liaison de collection d’entités applique simplement la contrainte selon laquelle l’URI de la demande doit inclure le chemin vers le jeu d’entités spécifié.

L’exemple suivant montre comment utiliser l’action ExportTranslation, qui exporte un fichier binaire contenant des données sur les valeurs de chaîne localisables qui peuvent être mises à jour pour modifier ou ajouter des valeurs localisables. Notez comment l’action liée à la collection d’entités suit le nom de l’ensemble d’entités pour l’entité de solution : solutions.

Demande :

POST [Organization URI]/api/data/v9.1/solutions/Microsoft.Dynamics.CRM.ExportTranslation HTTP/1.1
Accept: application/json
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "SolutionName":"MySolution"
}

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.1/$metadata#Microsoft.Dynamics.CRM.ExportTranslationResponse",
    "ExportTranslationFile": "[Binary data Removed for brevity]"
}

Utiliser une action personnalisée

Une action personnalisée peut être une API personnalisée ou une action de processus personnalisée. Quelle que soit la manière dont elle est créée, il y a une opération correspondante que vous pouvez utiliser. Avec une API personnalisée, l’opération peut être une fonction. Pour plus d’informations, voir : Créer vos propres messages

L’exemple suivant concerne une action de processus personnalisé.

Exemple d’action personnalisée : Ajouter une note à un contact

Supposons que vous voulez créer une action personnalisée qui ajoute une note à un contact spécifique. Vous pouvez créer une action personnalisée liée à l’entité contact avec les propriétés suivantes.

Étiquette d’interface utilisateur	valeur
Nom du processus	AddNoteToContact
Nom unique	new_AddNoteToContact
Entité	Contact
Catégorie	Action

Arguments de processus

Nom	Type	Obligatoire	Direction
NoteTitle	Chaîne	Obligatoire	Entrée
NoteText	Chaîne	Obligatoire	Entrée
NoteReference	EntityReference	Obligatoire	Sortie

Étapes

Nom	Type d’étape	Description
Créer la note	Créer l’enregistrement	Title = {NoteTitle(Arguments)} Note Body = {NoteText(Arguments)} Concernant = {Contact{Contact}}
Retourner une référence à la note	Attribuer une valeur	NoteReference Value = {Note(Create the note (Note))}

Après avoir publié et activé l’action personnalisée, lorsque vous téléchargez le CSDL, vous trouverez cette nouvelle action.


<Action Name="new_AddNoteToContact" 
    IsBound="true">
  <Parameter Name="entity" 
    Type="mscrm.contact" 
    Nullable="false" />
  <Parameter Name="NoteTitle" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
  <Parameter Name="NoteText" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
  <ReturnType Type="mscrm.annotation" 
    Nullable="false" />
</Action>

La requête avec la réponse HTTP suivante montre comment appeler l’action personnalisée et la réponse qu’elle renvoie en cas de réussite.

Demande :

POST [Organization URI]/api/data/v9.2/contacts(94d8c461-a27a-e511-80d2-00155d2a68d2)/Microsoft.Dynamics.CRM.new_AddNoteToContact HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "NoteTitle": "New Note Title",
 "NoteText": "This is the text of the note"
}

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#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

Spécifiez le paramètre de type de table

Lorsqu’une action requiert une entité comme paramètre et le type d’entité est ambigu, vous devez utiliser la propriété @odata.type pour spécifier le type d’entité. La valeur de cette propriété est le nom complet de l’entité, qui suit le modèle suivant : Microsoft.Dynamics.CRM.+<entity logical name>.

Comme le montre la section Actions liées ci-dessus, le paramètre Target à l’action AddToQueue est une activité. Mais puisque toutes les activités héritent du type d’entité activitypointer, vous devez inclure la propriété suivante dans l’entité JSON pour spécifier que le type d’entité est une lettre :"@odata.type": "Microsoft.Dynamics.CRM.letter".

Deux autres exemples sont les actions AddMembersTeam et RemoveMembersTeam, car le paramètre Members est une collection du type d’entité systemuser, qui hérite de sa clé primaire ownerid depuis le type d’entité principal. Si vous transmettez le JSON suivant pour représenter un seul utilisateur système dans la collection, il est clair que l’entité est un utilisateur système et non un type d’entité team, qui hérite également du type d’entité principal.

{
 "Members": [{
  "@odata.type": "Microsoft.Dynamics.CRM.systemuser",
  "ownerid": "5dbf5efc-4507-e611-80de-5065f38a7b01"
 }]
}

Si vous ne spécifiez pas le type d’entité dans ce cas, l’erreur suivante peut s’afficher : "EdmEntityObject passed should have the key property value set.".

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é).

Utiliser les actions de l’API Web

Actions non liées

Actions liées

Actions liées à une table

Actions liées à une collection de tables

Utiliser une action personnalisée

Exemple d’action personnalisée : Ajouter une note à un contact

Spécifiez le paramètre de type de table

Voir aussi

Commentaires

Ressources supplémentaires