Api

"Api" ist ein kompakter Deskriptor für API-Schnittstellen.

Schnittstellen werden in einigen Kontexten auch als "Protokollpuffer-Dienste" bezeichnet, z. B. durch das Schlüsselwort "service" in einer .proto-Datei. Sie unterscheiden sich jedoch von API-Diensten, die eine konkrete Implementierung einer Schnittstelle darstellen und nicht einfach Methoden und Bindungen beschreiben. In anderen Kontexten werden sie manchmal auch einfach als "APIs" bezeichnet, wie beispielsweise der Name dieser Nachricht selbst. Ausführliche Informationen zur Terminologie finden Sie unter https://cloud.google.com/apis/design/glossary

JSON-Darstellung

{
  "name": string,
  "methods": [
    {
      object(Method)
    }
  ],
  "options": [
    {
      object(Option)
    }
  ],
  "version": string,
  "sourceContext": {
    object(SourceContext)
  },
  "mixins": [
    {
      object(Mixin)
    }
  ],
  "syntax": enum(Syntax)
}
Felder
name

string

Der voll qualifizierte Name dieser Schnittstelle, einschließlich des Paketnamens, gefolgt vom einfachen Namen der Schnittstelle.

methods[]

object(Method)

Die Methoden dieser Schnittstelle in nicht spezifizierter Reihenfolge.

options[]

object(Option)

Alle Metadaten, die mit der Schnittstelle verknüpft sind.

version

string

Ein Versionsstring für diese Schnittstelle. Wenn er angegeben ist, muss er das Format major-version.minor-version haben, wie in 1.10. Wenn die Nebenversion nicht angegeben wird, wird standardmäßig Null verwendet. Wenn das gesamte Versionsfeld leer ist, wird die Hauptversion vom Paketnamen wie unten beschrieben abgeleitet. Wenn das Feld nicht leer ist, wird die Version im Paketnamen verifiziert und stimmt mit dem überein, was hier angegeben wird.

Das Versionierungsschema verwendet eine semantische Versionierung, bei der die Hauptversionsnummer eine nicht abwärtskompatible Änderung und die Nebenversion eine additive, abwärtskompatible Änderung angibt. Beide Versionsnummern signalisieren dem Nutzer, was er von verschiedenen Versionen erwarten kann. Sie sollten sorgfältig anhand des Produktplans ausgewählt werden.

Die Hauptversion spiegelt sich auch im Paketnamen der Schnittstelle wider, der wie in google.feature.v1 auf v<major-version> enden sollte. Für die Hauptversionen 0 und 1 kann das Suffix weggelassen werden. Null-Hauptversionen dürfen nur für experimentelle Nicht-GA-Schnittstellen verwendet werden.

sourceContext

object(SourceContext)

Quellkontext für den Protokollpuffer-Dienst, der durch diese Nachricht dargestellt wird.

mixins[]

object(Mixin)

Enthaltene Schnittstellen. Siehe Mixin.

syntax

enum(Syntax)

Die Quellsyntax des Dienstes.

Method (Methode)

"Method" stellt eine Methode einer API-Schnittstelle dar.

JSON-Darstellung

{
  "name": string,
  "requestTypeUrl": string,
  "requestStreaming": boolean,
  "responseTypeUrl": string,
  "responseStreaming": boolean,
  "options": [
    {
      object(Option)
    }
  ],
  "syntax": enum(Syntax)
}
Felder
name

string

Der einfache Name dieser Methode.

requestTypeUrl

string

Die URL des Eingabe-Nachrichtentyps.

requestStreaming

boolean

Wenn dies der Fall ist, wird die Anfrage gestreamt.

responseTypeUrl

string

Die URL des Ausgabe-Nachrichtentyps.

responseStreaming

boolean

Wenn dies der Fall ist, wird die Antwort gestreamt.

options[]

object(Option)

Alle Metadaten, die der Methode zugeordnet sind.

syntax

enum(Syntax)

Die Quellsyntax dieser Methode.

Option

Eine Protokollpuffer-Option, die einer Nachricht, einem Feld, einer Aufzählung usw. zugeordnet werden kann.

JSON-Darstellung

{
  "name": string,
  "value": {
    "@type": string,
    field1: ...,
    ...
  }
}
Felder
name

string

Der Name der Option. Dies ist die Kurzform für protobuf-integrierte Optionen (Optionen, die in descriptor.proto definiert sind). Zum Beispiel "mapEntry". Bei benutzerdefinierten Optionen sollte es der vollständig qualifizierte Name sein. Zum Beispiel "google.api.http".

value

object

Der Wert der Option wird in eine beliebige Nachricht gepackt. Wenn der Wert ein einfacher Wrapper ist, sollte der entsprechende Wrappertyp verwendet werden, der in google/protobuf/wrappers.proto definiert ist. Wenn der Wert ein Enum ist, sollte er unter Verwendung von google.protobuf als int32-Wert gespeichert werden.Int32Value-Typ.

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" }.

SourceContext

SourceContext repräsentiert Informationen über die Quelle eines Protobuf-Elements, wie die Datei, in der es definiert ist.

JSON-Darstellung

{
  "fileName": string
}
Felder
fileName

string

Der pfadqualifizierte Name der Datei .proto, die das zugehörige protobuf-Element enthielt. Zum Beispiel: "google/protobuf/sourceContext.proto".

Mixin

Deklariert eine API-Schnittstelle, die in dieser Schnittstelle enthalten sein soll. Die including-Schnittstelle muss alle Methoden der integrierten Schnittstelle neu deklarieren. Dokumentation und Optionen werden jedoch wie folgt übernommen:

  • Wenn nach dem Entfernen eines Kommentars oder Whitespace der Dokumentationsstring der redeclared-Methode leer ist, wird sie von der ursprünglichen Methode übernommen.

  • Jede Annotation, die zur Dienstkonfiguration (http, Sichtbarkeit) gehört und nicht in der redeclared-Methode definiert ist, wird übernommen.

  • Wenn eine http-Annotation übernommen wird, wird das Pfadmuster wie folgt geändert. Jedes Versionspräfix wird durch die Version der including-Schnittstelle sowie den root-Pfad ersetzt, falls angegeben.

Beispiel für ein einfaches Mixin:

package google.acl.v1;
service AccessControl {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v1/{resource=**}:getAcl";
  }
}

package google.storage.v2;
service Storage {
  //       rpc GetAcl(GetAclRequest) returns (Acl);

  // Get a data record.
  rpc GetData(GetDataRequest) returns (Data) {
    option (google.api.http).get = "/v2/{resource=**}";
  }
}

Beispiel für eine Mixin-Konfiguration:

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl

Das Mixin-Konstrukt bedeutet, dass alle Methoden in AccessControl demselben Namen und denselben Anfrage-/Antworttypen in Storage entsprechen. Nach der Übernahme der Dokumentation und der Annotation sieht ein Dokumentationsgenerator oder Annotation Processor die effektive Methode Storage.GetAcl wie folgt:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/{resource=**}:getAcl";
  }
  ...
}

Beachten Sie, wie sich das Pfadmuster von v1 zu v2 geändert hat.

Wenn das Feld root im Mixin angegeben wird, sollte es ein relativer Pfad sein, unter dem übernommene HTTP-Pfade platziert werden. Beispiel:

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl
    root: acls

Dies impliziert die folgende übernommene HTTP-Annotation:

service Storage {
  // Get the underlying ACL object.
  rpc GetAcl(GetAclRequest) returns (Acl) {
    option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";
  }
  ...
}
JSON-Darstellung

{
  "name": string,
  "root": string
}
Felder
name

string

Der vollständig qualifizierte Name der enthaltenen Schnittstelle.

root

string

Wenn nicht leer, wird ein Pfad angegeben, unter dem übernommene HTTP-Pfade gerootet werden.