Status

Typ Status określa logiczny model błędów odpowiedni dla różnych środowisk programowania, w tym interfejsów API typu REST i RPC. Jest używany przez gRPC. Model błędu:

  • Proste w obsłudze i zrozumiałe dla większości użytkowników
  • Wystarczająca elastyczność, aby sprostać nieoczekiwanym potrzebom

Omówienie

Komunikat Status zawiera 3 części danych: kod błędu, komunikat o błędzie i szczegóły błędu. Kod błędu powinien mieć postać wyliczeniową google.rpc.Code, ale w razie potrzeby może przyjmować dodatkowe kody błędów. Komunikat o błędzie powinien być przeznaczony dla programistów w języku angielskim, aby ułatwić deweloperom zrozumienie i rozwiązanie błędu. Jeśli potrzebny jest zlokalizowany komunikat o błędzie widoczny dla użytkownika, umieść go w szczegółach błędu lub zlokalizuj go w kliencie. Opcjonalne szczegóły błędu mogą zawierać dowolne informacje o błędzie. Pakiet google.rpc zawiera wstępnie zdefiniowany zestaw typów szczegółów błędu, których można używać w przypadku typowych błędów.

Mapowanie języka

Komunikat Status to logiczna reprezentacja modelu błędu, ale niekoniecznie musi to być rzeczywisty format przewodu. Gdy komunikat Status jest ujawniany w różnych bibliotekach klienta i różnych protokołach przewodów, może być inaczej mapowany. Na przykład zostanie ona prawdopodobnie zmapowana na pewne wyjątki w języku Java, ale bardziej prawdopodobne jest zmapowane na niektóre kody błędów w języku C.

Inne zastosowania

Model błędu i komunikat Status można używać w różnych środowiskach (z interfejsami API lub bez nich), aby zapewnić spójne środowisko programistyczne w różnych środowiskach.

Przykładowe zastosowania tego modelu błędu:

  • Błędy częściowe. Jeśli usługa musi zwrócić klientowi częściowe błędy, może umieścić w normalnej odpowiedzi element Status, aby wskazać te błędy.

  • Błędy przepływu pracy. Typowy przepływ pracy składa się z kilku etapów. Każdy krok może zawierać komunikat Status do zgłaszania błędów.

  • Operacje wsadowe. Jeśli klient używa żądania zbiorczego i odpowiedzi zbiorczej, komunikat Status należy używać bezpośrednio w odpowiedzi zbiorczej, po jednym na każdą odpowiedź podrzędną dotyczącą błędu.

  • Operacje asynchroniczne. Jeśli wywołanie interfejsu API zawiera operację asynchroniczną, która powoduje wyświetlenie odpowiedzi, stan tych operacji powinien być bezpośrednio reprezentowany za pomocą komunikatu Status.

  • Logowanie. Jeśli niektóre błędy interfejsu API są przechowywane w dziennikach, komunikat Status może zostać użyty bezpośrednio po usunięciu wymaganego ze względów bezpieczeństwa lub prywatności.

Zapis JSON 
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Pola
code

number

Kod stanu, który powinien być wartością wyliczeniową równą google.rpc.Code.

message

string

komunikat o błędzie widoczny dla dewelopera. Powinien być w języku angielskim; Każdy komunikat o błędzie widoczny dla użytkowników powinien zostać zlokalizowany i wysłany w polu google.rpc.Status.details lub zlokalizowany przez klienta.

details[]

object

Lista komunikatów ze szczegółami błędu. Istnieje typowy zestaw typów wiadomości, których mogą używać interfejsy API.

Obiekt zawierający pola dowolnego typu. Dodatkowe pole "@type" zawiera identyfikator URI identyfikujący typ. Przykład: { "id": 1234, "@type": "types.example.com/standard/id" }.