Condividi tramite

Comporre richieste HTTP e gestire gli errori

  • Articolo

 

Data di pubblicazione: gennaio 2017

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

L'interazione con l'API Web avviene tramite la composizione e l'invio di richieste HTTP. È necessario sapere come impostare le intestazioni HTTP appropriate e gestire eventuali errori inclusi nella risposta.

In questo argomento

Versioni e URL API Web

Metodi HTTP

Intestazioni HTTP

Individuare i codici di stato

Analizzare gli errori dalla risposta

Versioni e URL API Web

Per accedere all'API Web devi creare un URL mediante i componenti nella tabella seguente.

Elemento

Descrizione

Protocollo

Il protocollo appropriato, https:// o http://.

URL di base

Questo è l'URL normalmente utilizzato per aprire l'applicazione Web.

  • Per Microsoft Dynamics 365 (online): utilizza <tenant name>.crm.dynamics.com.

  • Per Distribuzione con connessione Internet: utilizza l'URL corretto per la tua istanza. Questo sarà: <organization name>.<domain name>.

  • Per Dynamics 365 (locale): utilizza <server name>/<organization name>

Percorso API Web

Il percorso all'API Web è /api/data/.

Versione

La versione viene espressa in questo modo: v[Major_version].[Minor_version][PatchVersion]/. Le versioni valide per questa versione sono:

  • v8.0/ Per Aggiornamento 0.1 di Microsoft Dynamics CRM Online 2016 e Aggiornamento 0.1 di Microsoft Dynamics CRM 2016

  • v8.1/ Per Aggiornamento 1 di Microsoft Dynamics CRM Online 2016 e Microsoft Dynamics CRM 2016 Service Pack 1

  • v8.2/ per Aggiornamento di dicembre 2016 per Dynamics 365 (online e locale)

Il valore specifico utilizzato non è importante con questa versione se sono stati applicati i corrispondenti aggiornamenti o Service Pack. Per ulteriori informazioni, vedere Compatibilità della versione

Risorsa

Nome dell'entità, funzione o azioni da utilizzare.

L'URL che verrà utilizzato sarà composto con queste parti: protocollo + URL di base + percorso API Web + versione + risorsa.

Compatibilità della versione

In questa versione è stata applicata una serie di modifiche additive con ogni aggiornamento o Service Pack. Quando si applicano aggiornamenti, vengono aggiunte le stesse funzionalità alle versioni secondarie successive. Per questo motivo, se puoi utilizzare la versione 8.2, le versioni 8.1 e 8.0 includeranno le stesse funzionalità. Questo è possibile perché tutte le modifiche sono additive o correzioni di bug che risolvono i problemi elencati in Limitazioni API Web di Microsoft Dynamics 365. Non sono state aggiunte modifiche importanti.

Nota

La versione principale (v9) successiva include funzionalità disponibili solo utilizzando tale versione. Le versioni successive secondarie possono offrire funzionalità aggiuntive che non verranno riportate nelle versioni secondarie precedenti. Il codice scritto per le versioni v8.x continuerà a funzionare nelle versioni v9.x quando si fa riferimento a v8.2 nell'URL utilizzato.

Per la versione v8.x, utilizza la versione più recente possibile e tieni presente che gli aggiornamenti o Service Pack in questa versione principale non introdurranno modifiche importanti. Tuttavia, questo sarà diverso nelle versioni future in cui sarà necessario prestare maggiore attenzione alla versione del servizio interessato.

Metodi HTTP

Le richieste HTTP possono applicare vari metodi diversi. Quando si utilizza l'API Web, si utilizzano solo i metodi elencati nella tabella seguente.

Metodo

Uso

GET

Da utilizzare per il recupero di dati, incluse le chiamate alle funzioni. Il codice di stato previsto per un recupero corretto è 200 OK.

POST

Da utilizzare per la creazione di entità o la chiamata ad azioni.

PATCH

Da utilizzare per l'aggiornamento di entità o l'esecuzione di operazioni upsert.

DELETE

Da utilizzare per l'eliminazione di entità o di singole proprietà delle entità.

PUT

Da utilizzare in situazioni limitate per aggiornare singole proprietà delle entità. Questo metodo non è consigliato per l'aggiornamento della maggior parte delle entità. Si utilizza per l'aggiornamento delle entità modello.

Intestazioni HTTP

Benché il protocollo OData consenta entrambi i formati JSON e ATOM, l'API Web supporta solo JSON. È pertanto possibile applicare le seguenti intestazioni.

Ogni richiesta deve includere il valore dell'intestazione Accept di application/json, anche quando non è previsto alcun corpo di risposta. Qualsiasi errore visualizzato nella risposta verrà restituito come JSON. Benché il codice dovrebbe funzionare anche se l'intestazione non è inclusa, si consiglia di includerla come procedura consigliata.

La versione corrente di OData è 4.0, ma le versioni future possono permettere nuove funzionalità. Per evitare ambiguità sulla versione di OData che verrà applicata al codice in tale punto in futuro, è opportuno includere sempre un'istruzione esplicita della versione corrente di OData e la versione massima da applicare nel codice. Utilizzare entrambe le intestazioni OData-Version e OData-MaxVersion impostate su un valore 4.0.

Tutte le intestazioni HTTP devono includere almeno le intestazioni seguenti.

Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0

Ogni richiesta che include dati JSON nel corpo della richiesta deve includere un'intestazione Content-Type con un valore di application/json.

Content-Type: application/json

È possibile utilizzare intestazioni aggiuntive per abilitare funzionalità specifiche.

  • Per restituire i dati pe le operazioni di creazione (POST) o aggiornamento (PATCH) per le entità, includi la preferenza return=representation. Quando la preferenza è applicata alla richiesta POST, una risposta completata avrà lo stato 201 (Created). Per una richiesta PATCH, una risposta completata avrà lo stato 200 (OK). Senza questa preferenze, entrambe le operazioni restituiranno lo stato 204 (No Content) per riflettere che non sono stati restituiti dati nel corpo della risposta per impostazione predefinita.

    Nota

    Questa funzionalità è stata aggiunta con Aggiornamento di dicembre 2016 per Dynamics 365 (online e locale).

  • Per restituire valori formattati con una query, includi la odata.include-annotationspreferenza impostata su Microsoft.Dynamics.CRM.formattedvalueutilizzando l'intestazione Prefer.Ulteriori informazioni:Includere valori formattati

  • L'intestazione Prefer si utilizza anche con l'opzione odata.maxpagesize per specificare quante pagine si desidera restituire.Ulteriori informazioni:Specifica il numero di entità da restituire in una pagina

  • Per rappresentare un altro utente quando il chiamante dispone dei privilegi necessari a tale scopo, aggiungere l'intestazione MSCRMCallerID con il valore systemuserid dell'utente da rappresentare.Ulteriori informazioni:Rappresentare un altro utente usando l'API Web.

  • Per applicare la concorrenza ottimistica, puoi applicare l'intestazione If-Match con un valore Etag.Ulteriori informazioni:Applicare la concorrenza ottimistica.

  • Per abilitare il rilevamento duplicati per una richiesta di POST, puoi utilizzare l'intestazione MSCRM.SuppressDuplicateDetection: false.Ulteriori informazioni:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

  • Per determinare se un'operazione upsert deve effettivamente creare o aggiornare un'entità, puoi utilizzare le intestazioni If-Match e If-None-Match.Ulteriori informazioni:Upsert di un'entità.

  • Quando si eseguono operazioni batch, è necessario applicare un numero di intestazioni diverse nella richiesta, con ciascuna parte inviata nel corpo.Ulteriori informazioni:Eseguire operazioni in batch usando l'API Web.

Individuare i codici di stato

Indipendentemente dal fatto che la richiesta HTTP abbia esito positivo o negativo, la risposta include un codice di stato. I codici di stato restituiti dall'API Web Microsoft Dynamics 365 includono i seguenti.

Codice

Descrizione

Tipo

200 OK

Quando l'operazione restituisce dati nel corpo della risposta, si riceve quanto segue.

Migrazione completata

201 Created

Prevedi questa operazione quando viene completata l'operazione POST dell'entità ed hai specificato la preferenza return-representation nella richiesta.

Nota

Questa funzionalità è stata aggiunta con Aggiornamento di dicembre 2016 per Dynamics 365 (online e locale).

Migrazione completata

204 No Content

Quando l'operazione ha esito negativo ma non restituisce dati nel corpo della risposta, si riceve quanto segue.

Operazione completata

304 Not Modified

Quando si verifica se un'entità è stata modificata dall'ultimo recupero, si riceve quanto segue.Ulteriori informazioni:Recuperi condizionali

Reindirizzamento

403 Forbidden

Per i seguenti tipi di errori, si riceve quanto segue:

  • AccessDenied

  • AttributePermissionReadIsMissing

  • AttributePermissionUpdateIsMissingDuringUpdate

  • AttributePrivilegeCreateIsMissing

  • CannotActOnBehalfOfAnotherUser

  • CannotAddOrActonBehalfAnotherUserPrivilege

  • CrmSecurityError

  • InvalidAccessRights

  • PrincipalPrivilegeDenied

  • PrivilegeCreateIsDisabledForOrganization

  • PrivilegeDenied

  • unManagedinvalidprincipal

  • unManagedinvalidprivilegeedepth

Errore client

401 Unauthorized

Per i seguenti tipi di errori, si riceve quanto segue:

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

Errore client

413 Payload Too Large

Quando la lunghezza richiesta è troppo grande, si riceve quanto segue.

Errore client

400 BadRequest

Quando un argomento non è valido, si riceve quanto segue.

Errore client

404 Not Found

Quando la risorsa non esiste, si riceve quanto segue.

Errore client

405 Method Not Allowed

Questo errore si verifica in caso di combinazioni errate di metodo e risorsa. Ad esempio, non è possibile utilizzare DELETE o PATCH in una raccolta di entità.

Per i seguenti tipi di errori, si riceve quanto segue:

  • CannotDeleteDueToAssociation

  • InvalidOperation

  • NotSupported

Errore client

412 Precondition Failed

Per i seguenti tipi di errori, si riceve quanto segue:

  • ConcurrencyVersionMismatch

  • DuplicateRecord

Errore client

500 Internal Server Error

Questo errore è previsto quando una richiesta POST per creare un'entità consente il rilevamento duplicati e l'entità per creare sarebbe un duplicato.Ulteriori informazioni:244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

Errore server

501 Not Implemented

Quando un'operazione richiesta non viene implementata, si riceve quanto segue.

Errore server

503 Service Unavailable

Quando il servizio API Web non è disponibile, si riceve quanto segue.

Errore server

Analizzare gli errori dalla risposta

I dettagli sugli errori sono inclusi come JSON nella risposta. Gli errori avranno il formato che segue.

    { "error":{ "code": "
            <This code is not related to the http status code and is frequently empty>", "message": "
            <A message describing the error>", "innererror": { "message": "
            <A message describing the error, this is frequently the same as the outer message>", "type": "Microsoft.Crm.CrmHttpException", "stacktrace": "
            <Details from the server about where the error occurred>" } } }

Vedere anche

Eseguire operazioni tramite l'API Web
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
Utilizzare le azioni 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