Vorgang

Diese Ressource stellt einen lange laufenden Vorgang dar, der das Ergebnis eines Network-API-Aufrufs ist.

JSON-Darstellung

{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object(Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  },
  // End of list of possible types for union field result.
}
Felder:
name

string

Der vom Server zugewiesene Name, der nur innerhalb des Dienstes eindeutig ist, der ihn ursprünglich zurückgibt. Falls Sie die Standard-HTTP-Zuordnung nutzen, sollte der name folgendes Format haben: operations/some/unique/name.

metadata

object

Dienstspezifische Metadaten, die mit dem Vorgang verknüpft sind. Typischerweise enthalten sie Informationen zum Verlauf und gemeinsame Metadaten wie den Erstellungszeitpunkt. Solche Metadaten werden nicht von allen Diensten bereitgestellt. Jede Methode, die einen lange laufenden Vorgang zurückgibt, sollte gegebenenfalls den Metadatentyp dokumentieren.

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

done

boolean

Ist der Wert false, heißt das, dass der Vorgang noch läuft. Ist er "true", ist der Vorgang abgeschlossen und es stehen die Optionen error oder response zur Verfügung.

Union-Feld result. Das Ergebnis des Vorgangs kann entweder ein error oder eine gültige response sein. Wenn done == false, ist weder error noch response festgelegt. Wenn done == true, ist einer von error oder response festgelegt. result kann nur einer der Folgenden sein:
error

object(Status)

Das Fehlerergebnis des Vorgangs, falls ein Fehler auftritt oder er abgebrochen wird.

response

object

Die normale Antwort des Vorgangs im Erfolgsfall. Falls die ursprüngliche Methode im Erfolgsfall keine Daten zurückgibt, wie z. B. Delete, ist die Antwort google.protobuf.Empty. Ist die ursprüngliche Methode Standard-Get/Create/Update, sollte die Antwort die Ressource sein. Bei anderen Methoden sollte die Antwort vom Typ XxxResponse sein, wobei Xxx der Name der ursprünglichen Methode ist. Wenn zum Beispiel der Name der ursprünglichen Methode TakeSnapshot() ist, ist der gefolgerte Antworttyp TakeSnapshotResponse.

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

Status

Der Typ Status definiert ein logisches Fehlermodell, das für verschiedene Programmierumgebungen geeignet ist, unter anderem REST APIs und RPC APIs. Es wird von gRPC verwendet. Das Fehlermodell sollte folgende Eigenschaften haben:

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

Überblick

Die Status-Meldung enthält die folgenden drei Datenelemente: Fehlercode, Fehlermeldung und Fehlerdetails. Der Fehlercode ist idealerweise ein ENUM-Wert von google.rpc.Code, kann aber gegebenenfalls weitere 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 vom Kunden 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 normale 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 Status-Meldung in unterschiedlichen Client-Bibliotheken 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 Status-Meldung können, mit oder ohne APIs, in mehreren Umgebungen verwendet werden, um in verschiedenen Umgebungen für eine einheitliche Entwicklungserfahrung zu sorgen.

Beispielanwendungen dieses Fehlermodells:

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

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

  • Batch-Vorgänge Wenn ein Client Batch-Anfragen und Batch-Antworten nutzt, sollte jeweils eine Status-Meldung pro untergeordneter Fehlerantwort direkt in der Batch-Antwort verwendet werden.

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

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

JSON-Darstellung

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

number

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

message

string

Eine an den Entwickler gerichtete Fehlermeldung, die englischsprachig sein sollte. Jede an den Nutzer gerichtete Fehlermeldung wird lokalisiert und im google.rpc.Status.details-Feld gesendet, oder vom Kunden übersetzt.

details[]

object

Eine Auflistung aller Meldungen, die die Fehlerdetails enthalten. Es wird einen gemeinsamen Meldungstyp-Satz geben, den APIs verwendet können. .

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

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Cloud Deployment Manager