Condividi tramite

Utilizzare le azioni API Web

  • Articolo

 

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Le azioni e le funzioni rappresentano operazioni riutilizzabili che puoi eseguire utilizzando l'API Web. Utilizza una richiesta POST con le azioni elencate in Web API Action Reference per eseguire operazioni con effetti collaterali. Puoi inoltre definire delle azioni personalizzate da tenere disponibili per l'utilizzo.

In questo argomento

Azioni non associate

Azioni associate

Utilizzare un'azione personalizzata

Specificare il tipo di parametro di entità

Azioni non associate

Le azioni vengono definite nel d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Ad esempio, la seguente è la definizione dell'WinOpportunity Action rappresentata nel linguaggio CSDL.

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

L'azione WinOpportunity corrisponde all'oggetto WinOpportunityRequest che utilizza il servizio dell'organizzazione. Utilizza questa azione per impostare lo stato di un'opportunità su Acquisita e creare un oggetto opportunityclose EntityType per registrare l'evento. Questa azione non include un valore restituito. Se ha esito positivo, l'operazione è completata.

Il parametro OpportunityClose richiede una rappresentazione JSON dell'entità opportunityclose da creare nell'operazione. Questa entità deve essere correlata all'opportunità che rilascia la proprietà di navigazione a valore singolo opportunityid. In JSON viene impostata utilizzando l'annotazione @odata.bind come indicato in Associare le entità in fase di creazione.

Il parametro Status deve essere impostato sullo stato per l'oggetto opportunity quando viene chiuso. Il valore predefinito per questo oggetto si trova nella proprietà opportunity EntityTypestatuscode. L'opzione Acquisita corrisponde a un valore di 3. Perché è necessario impostare questo valore quando esiste solo un'opzione motivo stato che rappresenta Acquisita? Perché è possibile definire opzioni di stato personalizzate per rappresentare un'acquisizione, come ad esempio Acquisizione importante o Acquisizione poco importante, oppure perché il valore potrebbe potenzialmente differire da 3 in una determinata situazione.

Il seguente esempio è la richiesta HTTP e la risposta per chiamare l'azione WinOpportunity per un'opportunità con un valore opportunityid di b3828ac8-917a-e511-80d2-00155d2a68d2.

  • Richiesta

    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)"
 }
}

  • Risposta

    HTTP/1.1 204 No Content
OData-Version: 4.0

Azioni associate

Nel d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl, quando un elemento Action rappresenta un'azione associata, il relativo attributo IsBound contiene il valore true. Il primo elemento di Parametro definito all'interno dell'azione rappresenta l'entità a cui è associata l'operazione. Quando l'attributo Type del parametro è una raccolta, l'operazione è associata a una raccolta di entità. Ad esempio, la seguente è la definizione dell'AddToQueue Action rappresentata nel linguaggio 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>

Questa azione associata è equivalente all'oggetto AddToQueueRequest utilizzato dal servizio dell'organizzazione. Nell'API Web questa azione è associata all'oggetto queue EntityType che rappresenta la proprietà AddToQueueRequest.DestinationQueueId. Questa azione accetta diversi parametri aggiuntivi e restituisce un oggetto AddToQueueResponse ComplexType corrispondente all'oggetto AddToQueueResponse restituito dal servizio dell'organizzazione. Quando un'azione restituisce un tipo complesso, la definizione del tipo complesso appare direttamente sopra l'azione nel linguaggio CSDL.

Per impostare il valore del primo parametro, è necessario richiamare un'azione associata utilizzando un URI. Non è possibile impostarlo come valore di parametro denominato.

Quando si richiama una funzione associata, è necessario includere il nome completo della funzione includendo lo spazio dei nomi Microsoft.Dynamics.CRM. Se non includi il nome completo, otterrai il seguente errore: Status Code:400 Request message has unresolved parameters.

Nel seguente esempio viene mostrato l'utilizzo dell'AddToQueue Action per aggiungere una lettera a una coda. Poiché il tipo del tipo di parametro Target non è specifico (mscrm.crmbaseentity), è necessario dichiarare in modo esplicito il tipo dell'oggetto utilizzando il valore di proprietà @odata.type** del nome completo dell'entità, incluso lo spazio dei nomi Microsoft.Dynamics.CRM. In questo caso, **Microsoft.Dynamics.CRM.letter.Ulteriori informazioni:Specificare il tipo di parametro di entità

  • Richiesta

    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"
 }
}

  • Risposta

    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"
}

Utilizzare un'azione personalizzata

Se definisci delle azioni personalizzate per la tua organizzazione o la tua soluzioni, tali azioni non saranno incluse nel d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Per informazioni sulla creazione di azioni utilizzando gli strumenti di personalizzazione nell'applicazione, vedi l'argomento di TechNetAzioni. Per informazioni sulla creazione e l'utilizzo delle azioni personalizzate, vedi Creare azioni personalizzate.

Indipendentemente che le operazioni incluse nell'azione personalizzata abbiano effetti collaterali, possono potenzialmente modificare i dati e quindi vengono considerate azioni anziché funzioni. Non esistono modi di creare una funzione personalizzata.

Esempio di un'azione personalizzata: aggiungere una nota a un contatto

Mettiamo che desideri creare un'azione personalizzata per aggiungere una nuova nota a un contatto specifico. Puoi creare un'azione personalizzata associata all'entità contatto con le proprietà seguenti.

Etichetta interfaccia utente

Valore

Nome processo

AddNoteToContact

Nome univoco

new_AddNoteToContact

Entità

Contatto

Categorie

Azione

Argomenti processo

Nome

Tipo

Obbligatorio

Direzione

NoteTitle

Stringa

Obbligatorio

Input

NoteText

Stringa

Obbligatorio

Input

NoteReference

EntityReference

Obbligatorio

Output

Passaggi

Nome

Tipo di passaggio

Descrizione

Creare la nota

Crea record

Title = {NoteTitle(Arguments)}

Corpo nota = {NoteText(argomenti)}

Relativo a = {Contact{Contact}}

Restituire un riferimento alla nota

Assegna valore

Valore di NoteReference = {Note (Creare la nota (nota))}

Una volta pubblicata e attivata l'azione personalizzata, quando scarichi il CSDL troverai questa nuova azione definita.

<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>

Le seguenti richiesta e risposta HTTP mostrano come chiamare l'azione personalizzata e la risposta restituita se l'azione ha esito positivo.

  • Richiesta

    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"
}

  • Risposta

    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"
}

Specificare il tipo di parametro di entità

Quando un'azione richiede un'entità come parametro e il tipo di entità è ambiguo, è necessario utilizzare la proprietà @odata.type per specificare il tipo di entità. Il valore di questa proprietà è il nome completo dell'entità, che segue questo schema:
Microsoft.Dynamics.CRM.+<nome logico entità>.

Come illustrato nella sezione Azioni associate precedente, il parametro Target in AddToQueue Action è un'attività. Poiché al contrario, tutte le attività ereditano da activitypointer EntityType, è necessario includere la proprietà nell'entità JSON per specificare che il tipo di entità è una lettera: "@odata.type": "Microsoft.Dynamics.CRM.letter".

Altri due esempi sono AddMembersTeam Action e RemoveMembersTeam Action perché il parametro Members è una raccolta di systemuser EntityType che eredita la chiave primaria ownerid da principal EntityType. Se si passa il seguente JSON per rappresentare un singolo systemuser nella raccolta, è chiaro che l'entità è un systemuser e non un team EntityType, che eredita anche dal tipo di entità di sistema principale.

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

Se non si specifica il tipo di entità in questa situazione, verrà visualizzato l'errore seguente: "EdmEntityObject passed should have the key property value set.".

Vedere anche

Esempio di azioni e funzioni API Web (C#)
Esempio di azioni e funzioni API Web (JavaScript lato client)
Eseguire operazioni tramite l'API Web
Comporre richieste HTTP e gestire gli errori
Query di dati tramite l'API Web
Creare un'entità utilizzando l'API Web
Recupera un'entità utilizzando l'API Web
Aggiorna ed elimina le entità con l'API Web
Associa e annulla associazione entità con l'API Web
Utilizzare le funzioni API Web
Eseguire operazioni in batch usando l'API Web
Rappresentare un altro utente usando l'API Web
Eseguire operazioni condizionali tramite l'API Web

Microsoft Dynamics 365

© 2017 Microsoft. Tutti i diritti sono riservati. Copyright