Codici errore e gestione degli errori | Concetti relativi all'API Graph

Si applica a: API Graph | Azure Active Directory (AD)

Le applicazioni client che usano l'API Azure Active Directory (AD) Graph devono implementare la logica di gestione degli errori per reagire nel modo più appropriato a condizioni variabili e offrire la migliore esperienza possibile ai clienti. Questo argomento illustra i tipi di errori restituiti dal'API di Azure AD Graph e fornisce linee guida generali su come gestirli.

Gestione degli errori dell'API Graph

Tipi di errori

Gli errori dell'API Graph si verificano nelle categorie seguenti.

• Errori del client. Gli errori del client sono rappresentati dai codici di stato HTTP della serie 400. Includono oggetti con valori non validi, oggetti in cui mancano proprietà o valori di proprietà obbligatori, tentativi di accesso a risorse non esistenti, tentativi di aggiornamento di proprietà di sola lettura e omissione dei token di autorizzazione necessari. Per risolvere questi errori, risolvere innanzitutto il problema sottostante prima di inviare di nuovo la richiesta.
• Errori del server. Gli errori del server sono rappresentati dai codici di stato HTTP della serie 500, come ad esempio un errore della directory temporaneo. In genere si tratta di errori temporanei che possono essere risolti inviando di nuovo la richiesta.
• Errori di rete/protocollo. Durante l'invio di una richiesta o la ricezione di una risposta, possono verificarsi numerosi errori relativi alla rete, ad esempio errori di risoluzione del nome host, connessioni chiuse prematuramente ed errori di negoziazione SSL. La maggior parte di questi errori non si risolve con un nuovo tentativo in quanto è necessario risolvere il problema sottostante. Alcuni errori, tuttavia, come ad esempio gli errori di risoluzione del nome host o i timeout, potrebbero risolversi inviando di nuovo la richiesta.

Struttura dei messaggi di errore

Gli errori dell'API Graph presentano un corpo formattato composto da un codice di stato HTTP, un messaggio e i valori. Usare le proprietà del corpo della risposta dell'errore nella logica di gestione degli errori.

Nota: alcune risposte HTTP potrebbero tuttavia non includere il corpo della risposta con codice, messaggio e valori perché la richiesta è instradata tramite servizi proxy e gateway. Accertarsi di includere la logica predefinita in grado di gestire gli errori solo in base al codice di stato HTTP.

Di seguito è riportato un errore HTTP 400 Request_BadRequest.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;odata=minimalmetadata;charset=utf-8
 request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
 Date: Tue, 02 Jul 2013 01:48:19 GMT
 …
 
 {
     "odata.error" : {
         "code" : "Request_BadRequest",
         "message" : {
             "lang" : "en",
             "value" : "A value is required for property 'mailNickname' of resource 'Group'."
         },
     "values" : null
    }
 }

Ogni corpo del messaggio include le proprietà code, message e values.

• Code: progettare la logica di gestione degli errori in base al codice.

  "code" : "Request_BadRequest"
  

• Message: tupla linguaggio-valore che rappresenta un messaggio di errore leggibile. Il contenuto si trova nel campo value. Nell'esempio seguente la richiesta non riesce perché manca il valore della proprietà mailNickname.

  "message" : {
       "lang" : "en",
       "value" : "A value is required for property 'mailNickname' of resource 'Group'."
  }
  

• Values: raccolta di coppie nome-valore che fornisce altre informazioni sulla natura dell'errore. Nell'esempio seguente non è incluso alcun valore.

  "values" : null
  

Informazioni di riferimento per i codici di errore

Codici di errore HTTP

La tabella seguente elenca i codici errore e i messaggi di errore dell'API Graph e le azioni da eseguire per correggere gli errori.

In genere gli errori serie HTTP 500 si risolvono con la ripetizione dei tentativi, preferibilmente distribuiti in intervalli di tempo sempre più lunghi ("tentativo con un intervallo di backoff") e con un fattore di distribuzione casuale. Gli errori serie 400 indicano un problema che deve essere corretto prima di ritentare.

Risorse aggiuntive

• Azure AD Graph API reference (Informazioni di riferimento sull'API di Azure AD Graph)