Utiliser des actions d’API web

Utilisez des actions d’API web pour effectuer des opérations réutilisables qui ont des effets secondaires dans Microsoft Dataverse. Envoyez une POST requête avec des actions répertoriées dans Web API Action Reference pour modifier des données, déclencher une logique métier ou appeler des processus personnalisés. Vous pouvez également définir des actions personnalisées. Pour plus d’informations, consultez Créer vos propres messages.

Les actions sont définies dans le document CSDL $metadata. Pour plus d’informations, consultez Actions de l’API web .

Actions non liées

Le code XML suivant montre 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 à la MergeRequest classe lorsque vous utilisez le Kit de développement logiciel (SDK) pour .NET. Utilisez cette action pour fusionner une paire d’enregistrements en double. Cette action n’inclut pas de valeur de retour. Si elle réussit, l’opération est terminée.

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

Requête :

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

Pour plus d’informations, consultez Fusionner les lignes de la table à l’aide de l’API web.

Actions liées

Vous pouvez lier une action à une entité ou à une collection d’entités. La liaison d’une action à une entité est plus courante.

Dans le document CSDL $metadata, un Action élément qui représente une action liée a un IsBound attribut défini sur true. Le premier Parameter élément défini dans l’action représente l’entité à laquelle l’opération est liée. Lorsque l’attribut Type du paramètre est une collection, l’opération est liée à une collection d’entités.

Lorsque vous appelez une fonction liée, incluez le nom complet de la fonction, y compris l’espace Microsoft.Dynamics.CRM de noms. Si vous n’incluez pas le nom complet, vous obtenez l’erreur suivante : Status Code:400 Request message has unresolved parameters.

Actions liées à une table

L’exemple suivant montre la définition de l’action AddToQueue et du type complexe AddToQueueResponse dans le CSDL, en tant qu’action liée à une entité.

<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 liée à l’entité équivaut à celle AddToQueueRequest utilisée par le Kit de développement logiciel (SDK) pour .NET. Dans l’API web, cette action est liée au type d’entité queue qui représente la propriété AddToQueueRequest.DestinationQueueId

Cette action accepte plusieurs paramètres supplémentaires et retourne un AddToQueueResponse type complexe correspondant à celui retourné par le SDK du .NET. Lorsqu’une action retourne un type complexe, la définition du type complexe apparaît directement au-dessus de l’action dans le CSDL.

Vous devez appeler une action liée à une entité à l’aide d’un URI pour définir la première valeur de paramètre. Vous ne pouvez pas le définir en tant que valeur de paramètre nommée.

L’exemple suivant montre comment utiliser l’action AddToQueue pour ajouter une lettre à une file d’attente. Étant donné que le type du paramètre Target n’est pas spécifique (mscrm.crmbaseentity), vous devez déclarer explicitement le type de l’objet en utilisant la valeur de la propriété @odata.type du nom complet de l’entité, y compris l’espace de noms Microsoft.Dynamics.CRM. Dans ce cas, Microsoft.Dynamics.CRM.letter. Pour plus d’informations, consultez Spécifier le type de paramètre d’entité.

Requête :

POST [Organization URI]/api/data/v9.2/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.2/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Actions liées à une collection de tables

Il est moins courant de rechercher des actions liées à une collection d’entités. La liste suivante inclut certaines actions que vous pouvez trouver :

FulfillSalesOrder dans Dynamics 365 for Sales

CreateMultiple

UpdateMultiple

Comme exemple d’action liée à une collection d’entités, la définition suivante montre l’action ExportTranslation représentée dans l'$metadata 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 liée à la collection d’entités équivaut à l’action ExportTranslationRequest utilisée par le Kit de développement logiciel (SDK) pour .NET. Dans l’API web, cette action est liée au type d’entité solution . Mais au lieu de passer une valeur à la requête, la contrainte de liaison de collection d’entités nécessite que l’URI de la requête inclue le chemin d’accès au 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 que vous pouvez mettre à jour pour modifier ou ajouter des valeurs localisables. Notez comment l’action liée à la collection d’entités se produit après le nom du jeu d’entités pour l’entité de solution : solutions.

Requête :

POST [Organization URI]/api/data/v9.2/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.2/$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. Chaque type d’action personnalisée a une opération correspondante que vous pouvez utiliser. Pour une API personnalisée, l’opération peut être une fonction. Pour en savoir plus, consultez Créer vos propres messages.

L’exemple suivant montre une action de processus personnalisée.

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

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

Étiquette de l’interface utilisateur	Valeur
Nom du processus	AjouterNoteAuContact
Nom unique	AjouterNouvelleNoteAuContact
Entité	Contact
Catégorie	Action

Arguments de processus

Nom	Type	Obligatoire	Direction
Titre de la note	Chaîne	Obligatoire	Input
NoteText	Chaîne	Obligatoire	Input
Remarque Référence	EntityReference	Obligatoire	Output

Étapes

Nom	Type d’étape	Descriptif
Créer la note	Créer l’enregistrement	Titre = {NoteTitle(Arguments)} Corps de la note = {NoteText(Arguments)} Concernant = {Contact{Contact}}
Renvoyer une référence à la note	Attribuer une valeur	Valeur de la référence de note = {Note (Créer la note (Remarque))}

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


<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 et la réponse HTTP suivantes montrent comment appeler l’action personnalisée et la réponse qu’elle retourne si elle réussit.

Requête :

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écifier le paramètre de type de table

Lorsqu’une action nécessite une entité en tant que paramètre et que le type d’entité est ambigu, utilisez la @odata.type propriété pour spécifier le type d’entité. La valeur de cette propriété est le nom complet de l’entité, qui suit ce modèle : Microsoft.Dynamics.CRM.+<nom> logique de l’entité.

Comme indiqué dans la section Actions liées , le Target paramètre de l’action AddToQueue est une activité. Toutefois, étant donné que toutes les activités héritent du activitypointer type d’entité, vous devez inclure la propriété suivante dans l’entité JSON pour spécifier 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, en héritant de sa clé primaire du type d'entité principal. Si vous transmettez le code JSON suivant pour représenter un utilisateur système unique 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, vous pouvez obtenir l’erreur suivante : "EdmEntityObject passed should have the key property value set.".

Voir aussi

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-03-14

Partage via

Utiliser des actions d’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écifier le paramètre de type de table

Voir aussi

Commentaires

Ressources supplémentaires