Kódy chyb a zpracování chyb | Rozhraní Graph API koncepty

  • Článek

Platí pro: Graph API | Azure Active Directory (AD)

Klientské aplikace, které používají rozhraní Graph API Azure Active Directory (AD) by měla implementovat logiku pro reagovat jako řádně nejblíže různých podmínky a dosažení optimálního výkonu možné zákazníkům zpracování chyb. Téma popisuje typy chyb, Azure AD Graph API vrátí, obsahuje obecné pokyny o tom, jak je zpracovat.

Důležité

Důrazně doporučujeme použít Microsoft Graph místo Azure AD Graph API pro přístup k prostředkům Azure Active Directory. Náš vývojový program jsou nyní soustředit na Microsoft Graph a dále jsou plánované pro Azure AD Graph API. Je velmi omezený počet scénářů, pro které Azure AD Graph API může být vhodné; Další informace najdete v tématu Microsoft Graph nebo Azure AD Graph příspěvku na blogu v Office Dev Center.

Zpracování chyb rozhraní Graph API

Typy chyb

V následujících kategoriích dojít k chybám Graph API.

  • Chyby klienta. Chyby klienta jsou reprezentované pomocí stavové kódy HTTP 400-series. Obsahují objekty, s neplatnými hodnotami, objekty, které chybí požadované vlastnosti nebo hodnoty vlastností, pokusu o přístup k neexistující prostředku, pokus o aktualizaci vlastnost určenou jen pro čtení a vynechání požadované autorizační token. Vyřešit tyto chyby, opravte problém základní před opakováním žádosti.
  • Chyby serveru. Chyby serveru jsou reprezentované pomocí řady 500 stavové kódy HTTP, jako je například selhání přechodného adresáře. Většina tyto chyby jsou přechodné a lze vyřešit opakováním žádosti.
  • Sítě a protokolu chyb. Různé chyby související se sítí může dojít při odesílání požadavku nebo získat odpověď, například chyb překladu názvu hostitele, předčasně uzavřené připojení a chyb vyjednávání protokolu SSL. Většina z těchto chyb nelze vyřešit opakováním; Základní problém je vyřešený. Některé chyby, například chybami rozlišení názvu hostitele nebo vypršení časových limitů, však může vyřešit opakováním žádosti.

Struktura chybová zpráva

Rozhraní API chyby grafu mají formátovaný text, který se skládá ze stavového kódu protokolu HTTP, zprávu a hodnoty. Použijte vlastnosti těla Chyba v vaše zpracování logiky chyb.

Poznámka:: některá HTTP odpovědí nemusí zahrnovat text odpovědi kódu, zprávy nebo hodnoty, vzhledem k tomu, že požadavek je směrován prostřednictvím služby proxy a brány. Nezapomeňte zahrnout výchozí logiku, která dokáže zpracovat chyby podle stavový kód HTTP samostatně.

Následuje příklad chybu 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
    }
 }

Každý tělo zprávy obsahuje kód, zprávu a hodnoty vlastnosti.

  • Kód: návrh logika zpracování chyb do větve založené na kódu.

    "code" : "Request_BadRequest"

  • Zpráva: řazené kolekce členů jazyka/hodnota představující čitelná pro člověka chybová zpráva. Obsah je v poli hodnota. V následujícím příkladu se požadavek nezdaří, protože hodnota mailNickname chybí vlastnost.

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

  • Hodnoty: kolekce dvojic název hodnota, které poskytují další informace o povaze chyby. V následujícím příkladu jsou zahrnuty žádné hodnoty.

    "values" : null

Referenční informace k chybovým kódem

Kódy chyb HTTP

Následující tabulka uvádí rozhraní Graph API kódy chyb, chybové zprávy a akce vzít v úvahu při opravě chyby.

Obecně platí, chyby protokolu HTTP 500-series reagovat na opakovaných pokusů, pokud možno distribuován přes stále dlouhé časové intervaly ("opakování s intervalem back vypnout") a s náhodných distribuční faktorem. chyby 400-series naznačují problém, který je potřeba opravit před opakováním pokusu.

Kód stavu HTTP Kód chyby Chybová zpráva Podrobnosti
400 Directory_ExpiredPageToken Hodnota tokenu Zadaná stránka vypršela platnost a již lze zahrnout do vaší žádosti.
400 Directory_ResultSizeLimitExceeded Byl překročen Limit velikosti výsledek Žádost nejde dokončit, protože je přidružen příliš mnoho výsledků. Tato chyba nastane velmi zřídka.
400 DomainVerificationCodeNotFound Ověření domény nezdaří, protože proces ověření nelze najít záznam TXT s odpovídající ověřovací kód.
400 ObjectConflict Název domény už v neověřené domény v této společnosti.
400 ObjectConflict Název domény už v ověřené domény v této společnosti.
400 ObjectInUse Nelze odstranit doménu aktuálně odkazuje uživatele, skupiny nebo víceklientské aplikace
400 ObjectPendingDeletion Nelze ověřit již existující domény, která čeká na odstranění.
400 ObjectPendingTakeover Nelze odstranit doménu právě převzetí klienta
400 Request_BadRequest Chybný požadavek. Před opakováním opravte žádosti. Označuje chybu v požadavku, například neplatnou hodnotu vlastnosti nebo argument nepodporované dotazu. Před opakováním opravte žádosti.
400 Request_DataContractVersionMissing Parametr verze kontraktů dat chybí. Verze rozhraní api zahrnout jako parametr dotazu s všechny požadavky.
400 Request_InvalidDataContractVersion Zadaná verze rozhraní api je neplatný. Hodnota musí přesně shodovat na podporovanou verzi.
400 Request_InvalidRequestUrl Adresa url požadavku byl neplatný. Požadavek by měl být jako /tenantdomainname/Entity nebo /$metadata. Název domény klienta může být ověřené, neověřené domény názvy nebo id kontextu.
400 Request_UnsupportedQuery Požadavek GET není podporováno. Opravte parametry žádosti a zkuste to znovu.
401 Authentication_ExpiredToken Vypršela platnost přístupového tokenu. Obnovte ji před odesláním požadavku. Vypršela platnost tokenu přístupu. Obnovte token a potom odešlete znovu.
401 Authentication_MissingOrMalformed Chybějící nebo nesprávně přístupový Token. Access_token hodnota v hlavičce autorizace je chybějící nebo nesprávně. Tato hodnota je vyžadována. Použijte hodnotu v ověřovací token.
401 Authorization_IdentityDisabled Objekt volání aplikace je zakázaná. Objekt zadaný v tokenu přístupu je v adresáři, ale je zakázán. Znovu povolit účet v adresáři a zkuste to znovu.
401 Authorization_IdentityNotFound Nelze vytvořit identitu volajícího aplikace. Objekt zadaný v tokenu přístupu nebyl nalezen v adresáři. Tomu může dojít, protože token je zastaralá, objekt byl odstraněn z adresáře nebo synchronizace adresářů je zpožděno.
403 Authentication_Unauthorized Neoprávněného požadavku. Token obsahuje neplatné nebo nepodporované deklarace identity. Získání tokenu žádost znovu a poté opakujte žádost.
403 Authorization_RequestDenied Zadaná pověření nemají dostatečná oprávnění k vytvoření této žádosti. Požadavek byl odepřen v důsledku nedostatečných oprávnění. Například objekt bez oprávnění správce nemá oprávnění k odstranění prostředku.
403 Directory_QuotaExceeded Adresář objekt limit kvóty {tenantName} byla překročena. Požádejte správce zvyšte maximální kvótu nebo odstranit objekty, které chcete snížit použité kvótu. Byla překročena kvóta adresáře. Klient může být příliš mnoho objektů nebo objekty může mít příliš mnoho hodnot. Také k tomu dochází, když pro objekt zabezpečení v vytvořeno příliš mnoho objektů. Zvýšení počtu maximální povolené objekt pro klienta nebo objekt, nebo snižte počet hodnot, které jsou součástí žádost o vytvoření nebo aktualizaci.
404 Directory_ObjectNotFound Nelze číst informace o společnosti z adresáře.
404 Request_ResourceNotFound Prostředek {resource} neexistuje nebo jeden z jeho dotazované vlastnost referenčního objekty nejsou k dispozici. V prostředku označeném identifikátorem URI neexistuje. Zkontrolovat, jestli hodnota a opakujte žádost.
409 Request_MultipleObjectsWithSameKeyValue Jediný zdroj byl očekáván výsledek však nalezeno několik prostředků. Aktualizujte prosím objekty vyřešení konfliktu. Této chybě může dojít, pokud jsou dva nebo více objektů, které mají stejnou hodnotu klíče, například pokud mají dva uživatelé stejné UserPrincipalName.
429 Příliš mnoho požadavků. K této chybě dojde, když probíhá požadavky omezeny. Navrhované čekací doba je vrácený v opakovat po hodnotu hlavičky odpovědi. Opakujte požadavek za doporučený počet sekund čekání.
500 Service_InternalServerError Došlo vnitřní chybě serveru. Při zpracování požadavku došlo k chybě interního serveru.
502 [All] “... Služba není k dispozici..." Funguje jako brána nebo proxy serveru došlo k chybě z jiného serveru při zpracování požadavku. Počkejte několik minut a opakujte žádost.
503 Directory_ConcurrencyViolation Došlo k chybě z důvodu souběžných požadavkům na klienta. Stručně počkejte a zkuste zopakovat.
503 Došlo k chybě během ověřování DNS (Poznámka: může být způsobeno z různých důvodů, jako je služba DNS je aktuálně dolů).
Authentication_Unknown Vnitřní chybu serveru. Tento kód chyby se používá, když se nevztahují ostatní kódy chyb.
Authentication_UnsupportedTokenType Typ tokenu uvedené není zpracován. Jsou podporovány pouze nosné tokeny. Typ tokenu není podporována. Zkontrolovat, jestli typ tokenu před dalším pokusem žádosti.
Directory_BindingRedirection Informace o klienta není k dispozici místně. Získání informací o používejte následující adresy URL. Když klient oddílu není k dispozici v datovém centru, klienti se musí připojit k adrese URl vrácený v odpovědi.
Directory_BindingRedirectionInternalServerError Informace o klienta není k dispozici místně. Na server došlo k vnitřní chybě při pokusu o naplnění nejbližší koncové body datového centra. Když dojde k výjimce přesměrování vazby, se naplní seznam nejbližší datacenter koncových bodů pro službu. Tato chyba označuje výjimku při vyplňování seznamu. Zadejte dotaz znovu.
Directory_CompanyNotFound Nelze číst informace o společnosti z adresáře. Došlo k chybě při načítání informací o společnosti z adresářové služby.
Directory_ReplicaUnavailable Upřednostňované repliky není k dispozici. Zkuste to prosím znovu bez všechny repliky hlavičky klíče relace. Vynechat hlavičky x-ms repliky relace key a poté opakujte.
Headers_DataContractVersionMissing Záhlaví verze kontraktů dat chybí. Zahrnout x-ms-dirapi-data-contract-version ve vaší žádosti. V požadavku chybí kontrakt verze klienta.
Headers_HeaderNotSupported Záhlaví {0} není aktuálně podporován. Žádost obsahuje nepodporovaný záhlaví HTTP. Změnit záhlaví a akci opakujte.
Request_InvalidReplicaSessionKey Zadaný klíč relace repliky není platný. Opravte klíč relace repliky a zkuste požadavek znovu.
Request_ThrottledPermanently Vaše žádost je omezen trvale. Zavolejte technickou podporu na adresu problém. Klient opakovaně a trvalé překročil limit míra žádosti o token. Požadavky z klienta, byly zamítnuty, dokud je vyjednána službu znovu. Pokud potřebujete pomoc Kontaktujte Microsoft Support.

Další zdroje informací