Status

Typ Status definiuje model błędów logicznych odpowiedni dla różnych środowisk programistycznych, w tym interfejsów API REST i interfejsów API RPC. Jest używany przez gRPC . Model błędu ma postać:

  • Prosty w obsłudze i zrozumiały dla większości użytkowników
  • Wystarczająco elastyczny, aby sprostać nieoczekiwanym potrzebom

Przegląd

Komunikat Status zawiera trzy elementy danych: kod błędu, komunikat o błędzie i szczegóły błędu. Kod błędu powinien być wartością wyliczeniową google.rpc.Code , ale w razie potrzeby może akceptować dodatkowe kody błędów. Komunikat o błędzie powinien być skierowany do programistów w języku angielskim, co pomoże programistom zrozumieć i rozwiązać błąd. Jeśli potrzebny jest zlokalizowany komunikat o błędzie skierowany do użytkownika, umieść zlokalizowany komunikat w szczegółach błędu lub zlokalizuj go w kliencie. Opcjonalne szczegóły błędu mogą zawierać dowolne informacje o błędzie. W pakiecie google.rpc znajduje się predefiniowany zestaw typów szczegółów błędów, których można używać w przypadku typowych błędów.

Mapowanie języka

Komunikat Status jest logiczną reprezentacją modelu błędu, ale niekoniecznie jest to rzeczywisty format przewodu. Gdy komunikat Status jest udostępniany w różnych bibliotekach klienckich i różnych protokołach sieciowych, można go różnie mapować. Na przykład prawdopodobnie zostanie zamapowany na pewne wyjątki w Javie, ale bardziej prawdopodobne jest, że zostanie zamapowany na niektóre kody błędów w C.

Inne zastosowania

Modelu błędów i komunikatu Status można używać w różnych środowiskach, z interfejsami API lub bez, aby zapewnić spójne środowisko programistyczne w różnych środowiskach.

Przykładowe zastosowania tego modelu błędu obejmują:

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

  • Błędy przepływu pracy. Typowy przepływ pracy składa się z wielu etapów. Każdy krok może zawierać komunikat Status umożliwiający raportowanie błędów.

  • Operacje wsadowe. Jeśli klient korzysta z żądania wsadowego i odpowiedzi wsadowej, komunikat Status powinien zostać użyty bezpośrednio w odpowiedzi wsadowej, po jednym dla każdej pododpowiedzi na błąd.

  • Operacje asynchroniczne. Jeśli wywołanie API osadza w odpowiedzi wyniki operacji asynchronicznej, status tych operacji powinien być reprezentowany bezpośrednio za pomocą komunikatu Status .

  • Logowanie. Jeśli w logach zapisane są jakieś błędy API, komunikat Status może zostać użyty bezpośrednio po usunięciu danych ze względów bezpieczeństwa/prywatności.

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

number

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

message

string

Komunikat o błędzie skierowany do programisty, który powinien być w języku angielskim. Każdy komunikat o błędzie wyświetlany użytkownikowi powinien zostać zlokalizowany i przesłany w polu google.rpc.Status.details lub zlokalizowany przez klienta.

details[]

object

Lista komunikatów zawierających szczegóły błędu. Istnieje wspólny zestaw typów komunikatów, z których mogą korzystać 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" } .