Share via

Obsługa błędów i kody błędów | Pojęcia dotyczące interfejsu API programu Graph

  • Artykuł

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.

Dodatkowe zasoby