Fehlercodes und Fehlerbehandlung | Graph-API-Konzepte

Gilt für: Graph-API | Azure Active Directory (AD)

Für Clientanwendungen, die die Azure AD Graph-API verwenden, sollte eine Fehlerbehandlungslogik implementiert werden, um optimal auf verschiedene Umstände zu reagieren und ihren Benutzern ein bestmögliches Nutzungserlebnis zu bieten. Dieser Artikel behandelt die Fehler, die von der Azure AD Graph-API zurückgegeben werden, und bietet Hilfestellungen zu deren Behandlung.

Behandeln von Graph-API-Fehlern

Fehlertypen

Graph-API-Fehler sind in die folgenden Kategorien unterteilt.

• Clientfehler. Clientfehler werden durch HTTP-Statuscodes 4xx dargestellt. In diese Kategorie fallen Objekte mit ungültigen Werten, Objekte mit fehlenden Eigenschaften oder Eigenschaftswerten, Zugriffsversuche auf nicht existierende Ressourcen, Aktualisierungsversuche für schreibgeschützte Eigenschaften und Anforderungen ohne das benötigte Autorisierungstoken. Korrigieren Sie das zugrunde liegende Problem und senden Sie die Anforderung erneut, um diese Art von Fehlern zu beheben.
• Serverfehler. Serverfehler werden durch HTTP-Statuscodes 5xx dargestellt, wie z. B. vorübergehende Verzeichnisfehler. Die meisten dieser Fehler sind vorübergehend und können durch eine Wiederholung der Anfrage behoben werden.
• Netzwerk-/Protokollfehler. Bei Anforderung und Antwort kann eine Vielzahl netzwerkbedingter Fehler auftreten, wie z. B. Namensauflösungsfehler, vorzeitig geschlossene Verbindungen und SSL-Vermittlungsfehler. Die meisten dieser Fehler können nicht durch Wiederholungen behoben werden; stattdessen muss die zugrunde liegende Ursache korrigiert werden. Manche Fehler wie z. B. Namensauflösungsfehler oder Zeitüberschreitungen können jedoch durch eine Wiederholung der Anfrage behoben werden.

Struktur der Fehlermeldungen

Graph-API-Fehler haben einen formatierten Text, der aus einem HTTP-Statuscode, einer Nachricht und Werten besteht. Verwenden Sie in der Fehlerbehandlungslogik die Eigenschaften des Fehlertexts.

Hinweis: Nicht alle HTTP-Antworten enthalten den Text mit Code/Nachricht/Werten, da die Anforderung durch Proxy- und Gatewaydienste geleitet wird. Sie sollten daher auch eine Standardlogik implementieren, die Fehler allein anhand des HTTP-Statuscodes behandelt.

Es folgt ein Beispiel für einen HTTP 400 Request_BadRequest-Fehler.

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

Jeder Meldungstext verfügt über die Eigenschaften „code“, „message“ und „values“.

• code: Entwerfen Sie eine Fehlerbehandlungslogik, deren Verzweigungen auf Code basieren.

  "code" : "Request_BadRequest"
  

• message: Ein Sprache-/Wert-Tupel, das eine lesbare Fehlermeldung darstellt. Der Inhalt befindet sich im value-Feld. Die Anforderung im folgenden Beispiel schlägt fehl, weil der Wert der mailNickname-Eigenschaft fehlt.

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

• values: Eine Sammlung von Name-Wert-Paaren, die weitere Informationen über den Fehler enthalten. Im folgenden Beispiel sind keine Werte enthalten.

  "values" : null
  

Referenz zu Fehlercodes

HTTP-Fehlercodes

In der folgenden Tabelle sind Fehlercodes, Fehlermeldungen und Korrekturmaßnahmen aufgeführt.

Im Allgemeinen werden HTTP 500-Fehler bei Wiederholungen ausgegeben, insbesondere wenn diese über immer längere Zeitintervalle verteilt werden ("Wiederholung bei einem Backoffintervall") und wenn ein zufälliger Verteilungsfaktor vorliegt. 400er Fehler weisen auf ein Problem hin, das vor der Wiederholung behoben werden muss.

Zusätzliche Ressourcen

• Referenz zur Azure AD Graph-API