Utiliser des actions d’API web

Les actions et les fonctions représentent des opérations réutilisables que vous pouvez effectuer à l’aide de l’API web. Utilisez une requête POST avec les actions listées dans Web API Action Reference pour effectuer des opérations qui entraînent des effets secondaires. Vous pouvez également définir des actions personnalisées. Pour plus d’informations, créez 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 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 à l’utilisation du MergeRequest 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 est la requête HTTP et la réponse à l’appel de 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

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

Actions liées

Il existe deux façons de lier une action. La méthode la plus courante consiste à lier l’action à une entité. Moins fréquemment, elle peut également être liée à une collection d’entités.

Dans le document CSDL $metadata, lorsqu’un Action élément représente une action liée, il a un IsBound attribut avec la valeur 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.

Lors de l’appel d’une fonction liée, vous devez inclure le nom complet de la fonction, y compris le namespace Microsoft.Dynamics.CRM. 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

Par exemple, voici la définition de l'action AddToQueue liée à une entité, telle que 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 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.

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 le définir en tant que valeur de paramètre nommée.

L’exemple suivant montre l’utilisation de l’action AddToQueue pour ajouter une lettre à une file d’attente. Étant donné que le type du Target paramètre n’est pas spécifique (mscrm.crmbaseentity), vous devez déclarer explicitement le type de l’objet à l’aide de la @odata.type valeur de propriété du nom complet de l’entité, y compris l’espace Microsoft.Dynamics.CRM de noms. Dans ce cas, Microsoft.Dynamics.CRM.letter. Plus d’informations : 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. Voici quelques-uns que vous pouvez trouver :

FulfillSalesOrder dans Dynamics 365 for Sales

CreateMultiple

UpdateMultiple

Par exemple, voici la définition suivante de l'action ExportTranslation liée à une collection d’entités, telle que représentée dans le $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 plutôt que de passer une valeur à la requête, la liaison de collection d’entités applique simplement la contrainte que l’URI de la demande doit inclure le chemin d’accès au jeu d’entités spécifié.

L’exemple suivant montre l’utilisation de 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.

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é. Dans les deux cas, il existe une opération correspondante que vous pouvez utiliser. Avec l’API personnalisée, l’opération peut être une fonction. Plus d’informations : Créer vos propres messages

L’exemple suivant concerne 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, lorsque vous téléchargez le CSDL, vous trouverez cette nouvelle action définie.


<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 en cas de réussite.

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, vous devez utiliser 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 ci-dessus, 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, qui hérite de sa clé primaire ownerid depuis le 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

Cette page a-t-elle été utile ?

Last updated on 2025-10-04

Partager 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