Paket google.rpc

Index

Status

Mit dem Typ Status wird ein logisches Fehlermodell definiert, das für verschiedene Programmierumgebungen wie REST APIs und RPC APIs geeignet ist. Dieses Modell wird von gRPC verwendet. Das Fehlermodell besitzt folgende Eigenschaften:

  • Nutzerfreundlich und leicht verständlich
  • Flexibel genug, um sich an unerwartete Anforderungen anzupassen

Übersicht

Die Meldung Status enthält die folgenden drei Datenelemente: Fehlercode, Fehlermeldung und Fehlerdetails. Der Fehlercode sollte ein Aufzählungswert von google.rpc.Code sein, kann jedoch bei Bedarf zusätzliche Fehlercodes akzeptieren. Die Fehlermeldung sollte eine an den Entwickler gerichtete Meldung auf Englisch sein, mit der Entwickler den Fehler verstehen und beheben können. Falls eine an den Nutzer gerichtete übersetzte Fehlermeldung benötigt wird, sollte sie zu den Fehlerdetails hinzugefügt oder clientseitig lokalisiert werden. Die optionalen Fehlerdetails können beliebige Informationen zum Fehler enthalten. Das Paket google.rpc enthält eine Reihe vordefinierter Fehlerdetailtypen, die für gängige Fehlerbedingungen verwendet werden können.

Sprachenzuordnung

Die Status-Meldung ist die logische Darstellung des Fehlermodells, aber dies entspricht nicht zwangsläufig dem tatsächlichen Wire-Format. Wenn die Meldung Status in unterschiedlichen Clientbibliotheken und Wire-Protokollen angezeigt wird, kann sie auch anders zugeordnet werden. Beispielsweise wird sie in Java wahrscheinlich Ausnahmen, aber in C eher Fehlercodes zugeordnet.

Andere Anwendungen

Das Fehlermodell und die Meldung Status können, mit oder ohne APIs, in mehreren Umgebungen verwendet werden, damit Entwickler in verschiedenen Umgebungen einheitlich arbeiten können.

Beispielanwendungen dieses Fehlermodells:

  • Partielle Fehler: Wenn ein Dienst Teilfehler an den Client zurückgeben muss, kann er den Status in die normale Antwort einbinden, um die partiellen Fehler anzuzeigen.

  • Workflowfehler: Ein typischer Workflow umfasst mehrere Schritte. Jeder Schritt kann eine Status-Meldung enthalten, um Fehler zu melden.

  • Batchvorgänge: Wenn ein Client Batchanfragen und Batchantworten nutzt, sollte jeweils eine Status-Meldung pro untergeordneter Fehlerantwort direkt in der Batchantwort verwendet werden.

  • Asynchrone Vorgänge: Wenn ein API-Aufruf Ergebnisse asynchroner Vorgänge in die Antwort einbindet, sollte der Status dieser Vorgänge direkt mithilfe der Status-Meldung dargestellt werden.

  • Logging: Wenn einige API-Fehler in Logs gespeichert sind, kann die Meldung Status direkt nach Entfernungen verwendet werden, die aus Sicherheits-/Vertraulichkeitsgründen erforderlich sind.

Felder
code

int32

Der Statuscode, der idealerweise ein ENUM-Wert von google.rpc.Code ist.
message

string

Eine an Entwickler gerichtete Fehlermeldung, die englischsprachig sein sollte. Jede Fehlermeldung an den Nutzer sollte lokalisiert und im Feld google.rpc.Status.details gesendet werden. Sie kann auch clientseitig lokalisiert werden.

details[]

Any

Eine Auflistung aller Meldungen, die die Fehlerdetails enthalten. Es gibt einen allgemeinen Satz von Nachrichtentypen, die von APIs verwendet werden können.