Esempio di azioni e funzioni API Web
Data di pubblicazione: gennaio 2017
Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
In questo gruppo di esempi viene illustrato come eseguire le azioni e le funzioni associate e non associate, incluse le azioni personalizzate, tramite l'API Web di Microsoft Dynamics 365. Questo esempio è implementato come un progetto distinto per le lingue seguenti:
In questo argomento vengono illustrati la struttura e il contenuto dell'esempio a un livello superiore e indipendente dal linguaggio. Rivedere gli argomenti di esempio collegati in precedenza per i dettagli di implementazione specifici di linguaggio su come eseguire le operazioni descritte in questo argomento.
Dimostra
Questo esempio è suddiviso nelle sezioni principali seguenti, contenenti operazioni con funzioni e azioni dell'API Web che vengono descritte in maggiore dettaglio negli argomenti concettuali associati.
Sezione dell'argomento |
Argomenti associati |
|---|---|
Dati di esempio |
|
Utilizzo di una funzione non associata senza parametri |
|
Utilizzo di una funzione non associata con parametri |
|
Utilizzo di una funzione associata senza parametri |
|
Utilizzo di una azione non associata con parametri |
|
Utilizzo di una azione associata con parametri |
|
Utilizzo di una azione personalizzata associata con parametri |
|
Utilizzo di una azione personalizzata non associata con parametri |
|
Gestione delle eccezioni di un'azione personalizzata |
Le sezioni seguenti contengono una breve discussione delle operazioni dell'API Web di Dynamics 365 eseguite insieme ai messaggi HTTP corrispondenti e all'output associato alla console.
Dati di esempio
Per accertarsi che le operazioni in questo esempio funzionino correttamente, è innanzitutto necessario creare i dati di esempio sul server Dynamics 365. I dati di esempio verranno eliminati dal server a meno che l'utente sceglie di non eliminarli. I dati contenuti in questo esempio vengono creati singolarmente come segue.
Creare un account (ad esempio Fourth Coffee) e associarlo con un incidente che include tre attività da 30 minuti (90 minuti totali). Dopo la creazione delle attività, queste vengono quindi contrassegnate come completate. L'operazione calcolerà il tempo totale richiesto per completare queste tre attività.
{ title: "Sample Case", "customerid_account@odata.bind": accountUri, Incident_Tasks: [ { subject: "Task 1", actualdurationminutes: 30 }, { subject: "Task 2", actualdurationminutes: 30 }, { subject: "Task 3", actualdurationminutes: 30 } ] };Creare un account e associarlo a un'opportunità. Questa opportunità verrà contrassegnata come acquisita nell'operazione di esempio.
{ name: "Sample Account for WebAPIFunctionsAndActions sample", opportunity_customer_accounts: [{ name: "Opportunity to win" }] };Creare un impegno di tipo lettera. La lettera verrà aggiunta alla coda dell'utente corrente nell'operazione di esempio.
{ description: "Example letter" }Creare un contatto da utilizzare con un'azione sample_AddNoteToContact personalizzata nell'operazione di esempio.
{ firstname: "Jon", lastname: "Fogg" }
Operazioni di esempio
Le operazioni di esempio in questo argomento sono organizzate nei modi seguenti.
Utilizzo delle funzioni: queste operazioni illustrano funzioni associate e non associate che accettano parametri oppure no.
Utilizzo delle azioni: queste operazioni illustrano azioni associate e non associate che accettano parametri oppure no.
Azioni personalizzate: Queste operazioni illustrano azioni associate e non associate e come gestire le eccezioni di errore personalizzate.
Utilizzo delle funzioni
Funzioni sono operazioni che non hanno effetti collaterali. Una funzione può essere associata a un'istanza di entità o una raccolta di entità. Le funzioni di query non sono mai associate. Per ulteriori informazioni, vedere Utilizzare le funzioni API Web. In questa sezione vengono visualizzati alcuni esempi su come funzioni associate e non associate vengono utilizzate e come vengono passati i parametri.
Utilizzo di una funzione non associata senza parametri
Utilizzare una funzione non associata per recuperare il nome completo dell'utente corrente utilizzando WhoAmI Function. Questa operazione illustra come chiamare una funzione non associata che non accetta parametri. Questa operazione restituisce il nome completo dell'utente corrente.
Ottenere la richiesta e risposta per WhoAmI Function.
Richiesta HTTP
GET http://cc_WebAPI_ServiceURI/WhoAmI HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Risposta HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 273
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
"BusinessUnitId":"0d6cc84a-d3f6-e511-80d0-00155da84802",
"UserId":"b08dc84a-d3f6-e511-80d0-00155da84802",
"OrganizationId":"0f47eae2-a906-4ae4-9215-f09875979f6a"
}
Utilizzo di una funzione non associata con parametri
Utilizzare una funzione non associata per recuperare il codice del fuso orario. Questa operazione illustra come chiamare una funzione non associata che accetta parametri. Questa operazione viene restituito il codice del fuso orario corrente per il fuso orario specificato.Ulteriori informazioni:Passare i parametri a una funzione
Richiesta HTTP
GET http://cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific%20Standard%20Time'&@p2=1033 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Risposta HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 154
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.GetTimeZoneCodeByLocalizedNameResponse",
"TimeZoneCode":4
}
Output della console
Unbound function: GetTimeZoneCodeByLocalizedName
Function returned time zone Pacific Standard Time, with code '4'.
Utilizzo di una funzione associata senza parametri
Utilizzare una funzione associata per recuperare il tempo totale richiesto per completare tutte le attività di un incidente. Questa operazione illustra come chiamare una funzione associata che non accetta parametri. Questa operazione restituisce i minuti totali richiesti dall'incidente per chiudere tutte le relative attività. Questa funzione inoltre utilizza i dati di incidente creati per questo programma di esempio.Ulteriori informazioni:Funzioni associate
Richiesta HTTP
GET http://cc_WebAPI_ServiceURI/incidents(3d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Risposta HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 148
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse",
"TotalTime":90
}
Output della console
Bound function: CalculateTotalTimeIncident
Function returned 90 minutes - total duration of tasks associated with the incident.
Utilizzo delle azioni
Azioni sono operazioni che consentono effetti collaterali. Un'azione è associata o non associata. Per ulteriori informazioni, vedere Utilizzare le azioni API Web. In questa sezione vengono visualizzati alcuni esempi su come azioni associate e non associate vengono utilizzate e come vengono passati i parametri. Viene inoltre indicato come le azioni personalizzate vengono utilizzate e come gestire le eccezioni derivanti da queste azioni personalizzate.
Utilizzo di una azione non associata con parametri
Utilizzare un'azione non associata che accetta un set di parametri. Questa operazione chiude un'opportunità e la contrassegna come acquisita chiamando WinOpportunity Action.opportunity EntityType è stato creato come dati di esempio in precedenza nel programma.Ulteriori informazioni:Azioni non associate
Richiesta HTTP
POST http://cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
{
"Status":3,
"OpportunityClose":{
"subject":"Won Opportunity",
"opportunityid@odata.bind":"http://cc_WebAPI_ServiceURI/opportunities(47920da5-fb4a-e611-80d5-00155da84802)"
}
}
Risposta HTTP
HTTP/1.1 204 No Content
OData-Version: 4.0
Output della console
Unbound Action: WinOpportunity
Opportunity won.
Utilizzo di una azione associata con parametri
Utilizzare un'azione associata che accetta parametri. Questa operazione aggiunge una lettera nella coda dell'utente corrente. A tale scopo, viene utilizzata la WhoAmI Function e systemuser EntityType per ottenere un riferimento alla coda dell'utente corrente. È inoltre necessario il riferimento a letter EntityType. Questa lettera è stato creato come dati di esempio in precedenza nel programma. Quindi AddToQueue Action associata viene chiamata per aggiungere la lettera nella coda dell'utente corrente.Ulteriori informazioni:Azioni associate
Richiesta HTTP
POST http://cc_WebAPI_ServiceURI/queues(1f7bcc50-d3f6-e511-80d0-00155da84802)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 110
{
"Target":{
"activityid":"4c920da5-fb4a-e611-80d5-00155da84802",
"@odata.type":"Microsoft.Dynamics.CRM.letter"
}
}
Risposta HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 170
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
"QueueItemId":"67bdfabd-fc4a-e611-80d5-00155da84802"
}
Output della console
Bound Action: AddToQueue
QueueItemId returned from AddToQueue Action: 67bdfabd-fc4a-e611-80d5-00155da84802
Utilizzo delle azioni personalizzate
Se si definiscono azioni personalizzate per la soluzione, è possibile chiamarle tramite l'API Web di Dynamics 365. 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.Ulteriori informazioni:Utilizzare un'azione personalizzata.
In questo esempio include due azioni personalizzate. Entrambe richiedono parametri ma una è associata e l'altra è non associata.
sample_AddNoteToContact: un'azione personalizzata associata che accetta due parametri. Uno è NoteTitle e l'altro NoteText. Questa azione personalizzata aggiunge una nota a contact EntityType. Di seguito uno screenshot della pagina Informazioni per questa azione personalizzata.
.jpeg "Custom Action - AddNoteToContact information")
sample_CreateCustomer: Azione personalizzata non associata che richiede parametri diversi a seconda del tipo di cliente che si sta creando. Ad esempio, quando AccountType è "account", richiede solo il parametro AccountName. Quando AccountType è "contact", sono richiesti i parametri ContactFirstName e ContactLastName. Di seguito uno screenshot della pagina Informazioni per questa azione personalizzata.
.jpeg "Custom Action - CreateCustomer information")
Utilizzo di una azione personalizzata associata con parametri
Questo esempio chiama l'azione personalizzata sample_AddNoteToContact che è associata all'entità contatto con i parametri richiesti. Questa azione personalizzata aggiunge una nota a un contatto esistente. Questa azione restituisce un'entità con una proprietà annotationid. Per mostrare che la nota è stata aggiunta, annotationid viene utilizzata per richiedere le informazioni sulla nota.
La richiesta e la risposta dell'azione.
Richiesta HTTP
POST http://cc_WebAPI_ServiceURI/contacts(4d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.sample_AddNoteToContact HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 80
{
"NoteTitle":"The Title of the Note",
"NoteText":"The text content of the note."
}
Risposta HTTP
HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 149
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
"annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802"
}
La richiesta e la risposta dell'annotazione.
Richiesta HTTP
GET http://cc_WebAPI_ServiceURI/annotations(ba146d0b-fd4a-e611-80d5-00155da84802)?$select=subject,notetext&$expand=objectid_contact($select=fullname) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Risposta HTTP
HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: 450
{
"@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations(subject,notetext,objectid_contact,objectid_contact(fullname))/$entity",
"@odata.etag":"W/\"622978\"",
"subject":"The Title of the Note",
"notetext":"The text content of the note.",
"annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802",
"objectid_contact":{
"@odata.etag":"W/\"622968\"",
"fullname":"Jon Fogg",
"contactid":"4d920da5-fb4a-e611-80d5-00155da84802"
}
}
Output della console
Custom action: sample_AddNoteToContact
A note with the title 'The Title of the Note' and the content 'The text content of the note.' was created and associated with the contact Jon Fogg.
Utilizzo di una azione personalizzata non associata con parametri
Questa operazione chiama l'azione personalizzata sample_CreateCustomer per creare un cliente "account". I parametri richiesti vengono passati per un CustomerTypeaccount.
Richiesta HTTP
POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103
{
"CustomerType":"account",
"AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}
Risposta HTTP
HTTP/1.1 204 No Content
OData-Version: 4.0
Gestione delle eccezioni di un'azione personalizzata
In questo esempio indica che azioni personalizzate possono restituire messaggi di errore personalizzati. Le eccezioni personalizzate si gestiscono nello stesso modo delle eccezioni standard. Per ottenere il messaggio di errore personalizzato dall'azione personalizzata sample_CreateCustomer , questo esempio crea un cliente "contact". Tuttavia, passiamo intenzionalmente parametri non corretti per questo parametro CustomerType. Questa operazione quindi rileva l'eccezione e visualizza il messaggio di errore, quindi continua con il programma di esempio.
Richiesta HTTP
POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103
{
"CustomerType":"contact",
"AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}
Risposta HTTP
HTTP/1.1 500 Internal Server Error
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 2760
{
"error":{
"code":"",
"message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
"innererror":{
"message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
...[truncated]
}
}
}
Output della console
Expected custom error: ContactFirstName and ContactLastName are required when CustomerType is contact.
Vedere anche
Utilizzare l'API Web di Microsoft Dynamics 365
Utilizzare le funzioni API Web
Utilizzare le azioni API Web
Esempio di azioni e funzioni API Web (C#)
Esempio di azioni e funzioni API Web (JavaScript lato client)
Microsoft Dynamics 365
© 2017 Microsoft. Tutti i diritti sono riservati. Copyright