Obsługa błędów i kody błędów | Pojęcia dotyczące interfejsu API programu Graph
Dotyczy: interfejsu API programu Graph | Azure Active Directory (AD)
Aplikacje klienckie, które używają interfejsu API programu Graph usługi Azure Active Directory (AD), należy zaimplementować logiki zareagować jako bezpiecznie możliwie najbliżej do zmiennych warunkach i zapewnić najlepsze możliwe środowisko klientom obsługi błędów. Temacie omówiono typy błędów interfejsu API programu Azure AD Graph zwracające i zawiera ogólne wskazówki dotyczące sposobu ich obsługę.
Ważne
Zdecydowanie zaleca się używanie Microsoft Graph zamiast interfejsu API Azure AD Graph dostęp do zasobów usługi Azure Active Directory. Nasze programistycznych teraz jest skoncentrowana na program Microsoft Graph i interfejsu API usługi Azure AD Graph planowane żadne rozszerzenia funkcjonalności. Istnieje bardzo ograniczoną liczbę scenariuszy, w których interfejsu API usługi Azure AD Graph nadal może być odpowiednie; Aby uzyskać więcej informacji, zobacz Microsoft Graph lub Azure AD Graph wpis w blogu w Centrum deweloperów pakietu Office.
Obsługa błędów interfejsu API programu Graph
Typy błędów
Błędy interfejsu API Graph występują w ramach następujących kategorii.
- Klientów z błędami. Błędy klienta są reprezentowane przez kody stanu HTTP 400-serii. Obejmują one obiekty z nieprawidłowymi wartościami, obiekty, których nie ma wymaganych właściwości lub wartości właściwości, próba uzyskania dostępu do zasobu nieistniejącą podjęto próbę zaktualizowania właściwości tylko do odczytu i pominięcie token autoryzacji wymagane. Aby usunąć te błędy, napraw problem przed podjęciem próby wykonania żądania.
- Błędy serwera. Błędy serwera są reprezentowane przez kody stanu HTTP 500-series, takie jak Błąd przejściowy katalogu. Większość tych błędów jest przejściowy i można rozwiązać przez ponowną próbą wykonania żądania.
- Protokół błędy. Wiele błędów związanych z siecią mogą wystąpić podczas wysyłania żądania lub odbierania odpowiedzi, takie jak błędy rozpoznawania nazwy hosta, połączenia przedwcześnie zamknięte i błędów negocjacji protokołu SSL. Większość tych błędów nie można rozwiązać przez ponowną próbą; ma problem należy naprawić. Jednak błędy, takich jak błędy rozpoznawania nazwy hosta lub przekroczeń limitu czasu, może zostać rozwiązane przez ponowną próbą wykonania żądania.
Struktura komunikat błędu
Błędy interfejsu API Graph mają sformatowany treści, która składa się z kodem stanu HTTP, wiadomość i wartości. Użyj właściwości treść błędu w Twojej obsługi logiki błędów.
Uwaga: odpowiedzi HTTP niektóre może nie zawierać treść odpowiedzi wartości Kod/komunikatów, ponieważ żądanie jest kierowane za pośrednictwem serwera proxy i Brama usług. Należy uwzględnić domyślna logika, jaką może obsłużyć błędów w oparciu jedynie kod stanu HTTP.
Oto przykład błąd 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żdy treść wiadomości została kodu, wiadomości i wartości właściwości.
Kod: Projektowanie logika obsługi błędów do gałęzi na podstawie kodu.
"code" : "Request_BadRequest"Komunikat: krotka języka i wartości reprezentujący komunikat o błędzie zrozumiałą dla użytkownika. Zawartość jest w polu wartość. W poniższym przykładzie, żądanie nie działa, ponieważ wartość mailNickname brakuje właściwości.
"message" : { "lang" : "en", "value" : "A value is required for property 'mailNickname' of resource 'Group'." }Wartości: zbiór par nazw i wartości, które udostępniają więcej informacji na temat charakteru błędu. W poniższym przykładzie dołączono żadnych wartości.
"values" : null
Błąd kodu — odwołanie
Kody błędów HTTP
W poniższej tabeli wymieniono interfejsu API programu Graph kody błędów, komunikaty o błędach i akcje wziąć pod uwagę podczas poprawiania błędów.
Ogólnie rzecz biorąc, błędy HTTP 500-series uwzględniał ponownych prób, najlepiej rozłożone coraz długo przedziały czasu ("ponawiania z interwałem wycofania"), a współczynnik losowe dystrybucji. Seria 400 błędy wskazują na problem, które muszą zostać usunięte przed ponowną próbą.
| Kod stanu HTTP | Kod błędu | Komunikat o błędzie | Szczegóły |
|---|---|---|---|
| 400 | Directory_ExpiredPageToken | Wartość tokenu określona strona wygasła i nie można dołączyć do żądania. | |
| 400 | Directory_ResultSizeLimitExceeded | Przekroczono Limit rozmiaru wyników | Nie można przeprowadzić żądania, ponieważ jest on skojarzony z zbyt wiele wyników. Ten błąd występuje bardzo rzadko. |
| 400 | DomainVerificationCodeNotFound | Weryfikacja domeny kończy się niepowodzeniem, ponieważ proces weryfikacji nie można odnaleźć rekordu TXT z odpowiedniego kodu weryfikacji. | |
| 400 | ObjectConflict | Nazwa domeny już istnieje w niezweryfikowanej domeny w tej firmy. | |
| 400 | ObjectConflict | Nazwa domeny już istnieje w zweryfikowanej domeny w tej firmy. | |
| 400 | ObjectInUse | Nie można usunąć domeny obecnie wywoływane przez użytkownika, grupy lub aplikacji z wieloma dzierżawcami | |
| 400 | ObjectPendingDeletion | Nie można zweryfikować istniejącej domeny, która oczekuje na usunięcie. | |
| 400 | ObjectPendingTakeover | Nie można usunąć domeny właśnie przejęcia dzierżawy | |
| 400 | Request_BadRequest | Nieprawidłowe żądanie. Usuń żądanie przed ponowną próbą. | Wskazuje na błąd w żądaniu, takich jak nieprawidłową wartość właściwości lub argumentu kwerend nieobsługiwana. Usuń żądanie przed ponowną próbą. |
| 400 | Request_DataContractVersionMissing | Brak parametru wersja kontraktu danych. Obejmują wersja interfejsu api jako parametr zapytania z Twoich żądań. | |
| 400 | Request_InvalidDataContractVersion | Określona wersja interfejsu api jest nieprawidłowa. Wartość musi dokładnie odpowiadać obsługiwanej wersji. | |
| 400 | Request_InvalidRequestUrl | Adres url żądania jest nieprawidłowy. Żądania powinien być /tenantdomainname/Entity lub /$metadata. Nazwę domeny dzierżawy może być dowolny z domeny zweryfikowane, niezweryfikowane nazwy lub identyfikatora kontekstu. | |
| 400 | Request_UnsupportedQuery | Żądanie GET nie jest obsługiwane. Usuń parametry żądania i spróbuj ponownie. | |
| 401 | Authentication_ExpiredToken | Token dostępu wygasł. Odnów go przed przesłaniem żądania. | Token dostępu wygasł. Odnów token, a następnie prześlij ponownie. |
| 401 | Authentication_MissingOrMalformed | Token dostępu brakujące lub źle skonstruowany. | Wartość ' access_token ' w nagłówku autoryzacji lub jest on uszkodzony. Ta wartość jest wymagana. Użyj wartości z tokenu uwierzytelniania. |
| 401 | Authorization_IdentityDisabled | Wywołanie podmiot zabezpieczeń aplikacji jest wyłączone. | Podmiot zabezpieczeń określone w tokenie dostępu znajduje się w katalogu, ale jest ona wyłączona. Ponownie włączyć konto w katalogu i spróbuj ponownie. |
| 401 | Authorization_IdentityNotFound | Nie można ustanowić tożsamość aplikacji wywołującej. | Nie można odnaleźć podmiotu zabezpieczeń określone w tokenie dostępu w katalogu. Taka sytuacja może wystąpić, ponieważ token jest przestarzała, podmiot zabezpieczeń został usunięty z katalogu lub synchronizacji katalogów jest opóźnione. |
| 403 | Authentication_Unauthorized | Nieautoryzowanego żądania. | Token zawiera oświadczenia nieprawidłowy lub nieobsługiwany. Pobierz token żądanie ponownie, a następnie ponów żądanie. |
| 403 | Authorization_RequestDenied | Podane poświadczenia mają wystarczające uprawnienia do zgłoszenia tego żądania. | Żądanie zostało odrzucone z powodu niewystarczających uprawnień. Na przykład innych niż administracyjne podmiot zabezpieczeń nie ma uprawnień do usunięcia zasobu. |
| 403 | Directory_QuotaExceeded | Limit przydziału obiektów katalogu dla {tenantName} został przekroczony. Poproś administratora o Zwiększ limit przydziału, lub Usuń obiekty, aby zmniejszyć przydział używane. | Przekroczono limit przydziału katalogu. Dzierżawcy może być zbyt wiele obiektów lub obiekty może być zbyt wiele wartości. Występuje również podczas tworzenia zbyt wiele obiektów na dla podmiotu zabezpieczeń. Zwiększyć liczbę maksymalny dozwolony obiektu dla dzierżawy lub podmiot zabezpieczeń, lub Zmniejsz liczbę wartości dołączana do żądań tworzenia/aktualizacji. |
| 404 | Directory_ObjectNotFound | Nie można odczytać danych firmy z katalogu. | |
| 404 | Request_ResourceNotFound | Zasobu {resource} nie istnieje lub jednego ze swoich obiektów, którego dotyczy kwerenda właściwości odwołania nie są dostępne. | Zasobu określonego przez identyfikator URI nie istnieje. Popraw wartość i ponów żądanie. |
| 409 | Request_MultipleObjectsWithSameKeyValue | Oczekiwano jednego zasobu dla wyniku, ale znaleziono wiele zasobów. Zaktualizuj obiektów w celu rozwiązania konfliktu. | Ten błąd może wystąpić, gdy istnieją co najmniej dwa obiekty, które mają taką samą wartość klucza, np. Jeśli dwóch użytkowników ma tego samego UserPrincipalName. |
| 429 | Za dużo żądań. | Ten błąd występuje, gdy trwa żądań zdławionych. Czas oczekiwania sugerowane jest zwracana w ponownych prób po wartości nagłówka odpowiedzi. Ponów żądanie po upływie liczby sekund. | |
| 500 | Service_InternalServerError | Wystąpił wewnętrzny błąd serwera. | Wewnętrzny błąd serwera podczas przetwarzania żądania. |
| 502 | [All] | “... Usługa niedostępna,..." | Serwer działający jako brama lub serwer proxy napotkał błąd z innego serwera podczas przetwarzania żądania. Poczekaj kilka minut, a następnie ponów żądanie. |
| 503 | Directory_ConcurrencyViolation | Błąd z powodu równoczesnych żądań wysyłanych do dzierżawcy. Poczekaj chwilę i spróbuj ponownie. | |
| 503 | Napotkano błąd podczas weryfikacji DNS (Uwaga: może wynikać z różnych powodów, takich jak DNS jest obecnie nie działa). | ||
| Authentication_Unknown | Wewnętrzny błąd serwera. | Ten kod błędu jest używany podczas innych kodów błędów nie są stosowane. | |
| Authentication_UnsupportedTokenType | Typ tokenu przedstawione nie jest obsługiwana. Obsługiwane są tylko tokenów elementu nośnego. | Typ tokenu nie jest obsługiwany. Sprawdź, czy typ tokenu przed ponowną próbą wykonania żądania. | |
| Directory_BindingRedirection | Informacje o dzierżawy nie jest dostępna lokalnie. Aby uzyskać informacje, należy użyć następujących adresów URL. | Gdy partycji dzierżawy nie jest dostępna w centrum danych, klienci muszą łączyć się adres URl zwracany w odpowiedzi. | |
| Directory_BindingRedirectionInternalServerError | Informacje o dzierżawy nie jest dostępna lokalnie. Serwer napotkał błąd wewnętrzny podczas próby wypełnienia najbliższej punkty końcowe centrum danych. | W przypadku wystąpienia wyjątku przekierowania powiązania listę najbliższego centrum danych punktów końcowych dla usługi jest wypełnione. Ten błąd wskazuje Wystąpił wyjątek podczas wypełniania listy. Spróbuj ponownie zapytanie. | |
| Directory_CompanyNotFound | Nie można odczytać danych firmy z katalogu. | Wystąpił błąd podczas ładowania informacji o firmie z usługi katalogowej. | |
| Directory_ReplicaUnavailable | Preferowany repliki jest niedostępny. Spróbuj ponownie bez żadnych repliki nagłówka klucza sesji. | Pominąć ten nagłówek x-ms repliki kluczy sesji, a następnie spróbuj ponownie. | |
| Headers_DataContractVersionMissing | Brak nagłówka wersji kontraktu danych. Obejmują x-ms-dirapi-data-contract-version w żądaniu. | Wersja kontraktu klienta brakuje żądania. | |
| Headers_HeaderNotSupported | Nagłówek {0} nie jest obecnie obsługiwane. | Żądanie zawiera nieobsługiwany nagłówka HTTP. Zmień nagłówka i ponownie spróbuj przesłać żądanie. | |
| Request_InvalidReplicaSessionKey | Podany klucz sesji repliki nie jest prawidłowy. | Usuń klucz sesji repliki i ponownie spróbuj przesłać żądanie. | |
| Request_ThrottledPermanently | Żądanie jest ograniczany trwałe. Skontaktuj się z działem pomocy technicznej, aby rozwiązać problem. | Dzierżawca wielokrotnie i trwale przekroczyła limit szybkości żądania tokenu. Żądania z dzierżawy są odrzucane, dopóki usługa jest ponownie negocjowane. Aby uzyskać pomoc skontaktuj się z Microsoft Support. |