Utiliser des actions API Web

Article
10/31/2017

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Les actions et les fonctions représentent des opérations réutilisables que vous pouvez effectuer avec l'API Web. Utilisez une demande POST avec des actions répertoriées dans Web API Action Reference pour effectuer les opérations qui ont des effets secondaires. Vous pouvez également définir les actions personnalisées dont vous pourrez disposer.

Contenu de la rubrique

Actions non liées

Actions liées

Utiliser une action personnalisée

Spécifier le type de paramètre d'entité

Actions non liées

Les actions sont définies dans d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Par exemple, voici la définition de WinOpportunity Action représentée dans le langage CSDL.

<Action Name="WinOpportunity">
  <Parameter Name="OpportunityClose" Type="mscrm.opportunityclose" Nullable="false" />
  <Parameter Name="Status" Type="Edm.Int32" Nullable="false" />
</Action>

L'action WinOpportunity correspond à WinOpportunityRequest utilisant le service d'organisation. Utilisez cette action pour définir l'état d'une opportunité sur Conclu(e) et créez un objet opportunityclose EntityType pour enregistrer l'événement. Cette action ne contient aucune valeur de retour. Si elle aboutit, l'opération est terminée.

Le paramètre OpportunityClose requiert une entité JSONopportunityclose à créer dans l'opération. Cette entité doit être associée à l'opportunité émettant la propriété de navigation à valeur unique opportunityid. Dans JSON, la définition est basée sur l'annotation @odata.bind comme décrit dans Associer des entités lors de la création.

Le paramètre Status doit être défini sur le statut "en" pour l'objet opportunity à sa fermeture. Vous trouverez sa valeur par défaut dans la propriété opportunity EntityTypestatuscode. L'option Conclu(e) a la valeur 3. L'option Conclu(e) a la valeur 3. Vous vous demandez pourquoi il est nécessaire de définir cette valeur lorsqu'il existe une seule option de raison du statut, à savoir Conclu(e) ? La raison est que vous pouvez définir des options de statut personnalisées pour représenter une conclusion, comme Grande conclusion ou Petite conclusion, donc la valeur ne peut pas être différente de 3 dans ce cas.

L'exemple suivant est la demande et la réponse HTTP pour appeler l'action WinOpportunity d'une opportunité avec une valeur opportunityid de b3828ac8-917a-e511-80d2-00155d2a68d2.

Demande

POST cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "Status": 3,
 "OpportunityClose": {
  "subject": "Won Opportunity",
  "opportunityid@odata.bind": "cc_WebAPI_ServiceURI/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)"
 }
}

Réponse

HTTP/1.1 204 No Content
OData-Version: 4.0

Actions liées

Dans d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_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 Paramètre 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. Par exemple, voici la définition de l'objet AddToQueue Action représentée dans le langage 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 est équivalente à l'objet AddToQueueRequest utilisée par le service de l'organisation. Dans l'API Web, cette action est liée à l'objet queue EntityType qui représente la propriété AddToQueueRequest.DestinationQueueId. Cette action accepte plusieurs paramètres supplémentaires et renvoie un objet AddToQueueResponse ComplexType correspondant à la AddToQueueResponse renvoyée par le service de l'organisation. 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 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.

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 recevrez le message d'erreur suivant : Status Code:400 Request message has unresolved parameters.

L’exemple suivant illustre la chaîne de connexion utilisant l'objet AddToQueue Action 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 d'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 :Spécifier le type de paramètre d'entité

Demande

POST cc_WebAPI_ServiceURI/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": "cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Utiliser une action personnalisée

Si vous définissez des actions personnalisées pour votre organisation ou solution, elles seront également incluses dans le d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Pour plus d'informations sur la création des actions avec les outils de personnalisation dans l'application, voir la rubrique TechNetActions. Pour plus d'informations sur la création et l'utilisation de vos propres actions personnalisées, voir Créer vos propres actions.

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.

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

Supposons que vous voulez créer une action personnalisée qui ajoutera 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)} Regarding = {Contact{Contact}}
Retourner une référence à la note	Attribuer une valeur	NoteReference Value = {Note(Create the note (Note))}

Créer la note

Créer l'enregistrement

Title = {NoteTitle(Arguments)}

Note Body = {NoteText(Arguments)}

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

Spécifier le type de paramètre d'entité

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.+<nom logique de l'entité>.

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

Deux autres exemples sont AddMembersTeam Action et RemoveMembersTeam Action car le paramètre Members est une collection de systemuser EntityType qui hérite sa clé primaire ownerid de principal EntityType. Si vous transmettez le 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 team EntityType, 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 suivant peut s'afficher : "EdmEntityObject passed should have the key property value set.".

Voir aussi

Microsoft Dynamics 365

Utiliser des actions API Web

Contenu de la rubrique

Actions non liées

Actions liées

Utiliser une action personnalisée

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

Spécifier le type de paramètre d'entité

Voir aussi

Ressources supplémentaires