Status

Der Status definiert ein logisches Fehlermodell, das für verschiedene Programmierumgebungen geeignet ist, einschließlich REST-APIs und RPC-APIs. Es wird von gRPC verwendet. Das Fehlermodell ist wie folgt konzipiert:

  • Für die meisten Benutzer einfach zu verwenden und zu verstehen
  • Flexibel genug, um unerwartete Anforderungen zu erfüllen

Überblick

Die Status enthält drei Datenelemente: Fehlercode, Fehlermeldung und Fehlerdetails. Der Fehlercode sollte ein Enum-Wert von google.rpc.Code sein, kann aber bei Bedarf weitere Fehlercodes akzeptieren. Bei der Fehlermeldung sollte es sich um eine entwicklerorientierte englische Nachricht handeln, die den Entwicklern hilft, den Fehler zu verstehen und zu beheben . Wenn eine lokalisierte, für den Benutzer sichtbare Fehlermeldung erforderlich ist, fügen Sie die lokalisierte Nachricht in die Fehlerdetails ein oder lokalisieren Sie sie im Client. Die optionalen Fehlerdetails können beliebige Informationen zum Fehler enthalten. Im Paket google.rpc gibt es einen vordefinierten Satz von Fehlerdetailtypen, die für häufige Fehlerbedingungen verwendet werden können.

Sprachzuordnung

Die Status ist die logische Darstellung des Fehlermodells, entspricht jedoch nicht unbedingt dem tatsächlichen Leitungsformat. Wenn die Status in verschiedenen Client-Bibliotheken und verschiedenen Übertragungsprotokollen verfügbar gemacht wird, kann sie unterschiedlich zugeordnet werden. Beispielsweise wird es wahrscheinlich einigen Ausnahmen in Java zugeordnet, wahrscheinlicher jedoch einigen Fehlercodes in C.

Andere Verwendungszwecke

Das Fehlermodell und die Status können in verschiedenen Umgebungen verwendet werden, entweder mit oder ohne APIs, um eine konsistente Entwicklererfahrung in verschiedenen Umgebungen bereitzustellen.

Beispiele für die Verwendung dieses Fehlermodells sind:

  • Teilfehler. Wenn ein Dienst Teilfehler an den Client zurückgeben muss, kann er den Status in die normale Antwort einbetten, um die Teilfehler anzuzeigen.

  • Workflow-Fehler. Ein typischer Arbeitsablauf besteht aus mehreren Schritten. Für jeden Schritt kann eine Status zur Fehlerberichterstattung vorhanden sein.

  • Batch-Operationen. Wenn ein Client eine Batch-Anfrage und eine Batch-Antwort verwendet, sollte die Status direkt in der Batch-Antwort verwendet werden, eine für jede Fehler-Unterantwort.

  • Asynchrone Operationen. Wenn ein API-Aufruf asynchrone Vorgangsergebnisse in seine Antwort einbettet, sollte der Status dieser Vorgänge direkt mithilfe der Status dargestellt werden.

  • Protokollierung. Wenn einige API-Fehler in Protokollen gespeichert werden, kann der Status direkt nach der aus Sicherheits-/Datenschutzgründen erforderlichen Entfernung verwendet werden.

JSON-Darstellung
{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Felder
code

number

Der Statuscode, der ein Enumerationswert von google.rpc.Code sein sollte.

message

string

Eine entwicklerseitige Fehlermeldung, die auf Englisch sein sollte. Jede benutzerseitige Fehlermeldung sollte lokalisiert und im Feld google.rpc.Status.details gesendet oder vom Client lokalisiert werden.

details[]

object

Eine Liste von Nachrichten, die die Fehlerdetails enthalten. Es gibt einen gemeinsamen Satz von Nachrichtentypen, die von APIs verwendet werden können.

Ein Objekt, das Felder eines beliebigen Typs enthält. Ein zusätzliches Feld "@type" enthält einen URI, der den Typ identifiziert. Beispiel: { "id": 1234, "@type": "types.example.com/standard/id" } .