Standardmethoden

In diesem Kapitel wird das Konzept der Standardmethoden List, Get, Create, Update und Delete definiert. Standardmethoden vereinfachen Aufrufe und erhöhen die Konsistenz. Die API-Methoden im Repository der Google APIs sind zu über 70 % Standardmethoden. Dies vereinfacht das Erlernen und Verwenden der Methoden.

In der folgenden Tabelle wird beschrieben, wie Sie den HTTP-Methoden Standardmethoden zuordnen:

Standardmethode	HTTP-Zuordnung	HTTP-Request-Text	HTTP-Antworttext
List	GET <collection URL>	–	Ressourcenliste*
Get	GET <resource URL>	–	Ressource*
Create	POST <collection URL>	Ressource	Ressource*
Update	PUT or PATCH <resource URL>	Ressource	Ressource*
Delete	DELETE <resource URL>	–	google.protobuf.Empty**

*Die von den Methoden List, Get, Create und Update zurückgegebene Ressource kann Teildaten enthalten, wenn die Methoden Antwortfeldmasken unterstützen, mit denen Teilmengen von Feldern zurückgegeben werden. Manche API-Plattformen unterstützen Feldmasken nativ für alle Methoden.

**Die Antwort, die von einer Delete-Methode zurückgegeben wird, die die Ressource nicht sofort entfernt (z. B. beim Aktualisieren eines Flags oder beim Erstellen eines Löschvorgangs mit langer Ausführungszeit), sollte entweder den Vorgang mit langer Ausführungszeit enthalten oder die geänderte Ressource.

Eine Standardmethode kann auch einen Vorgang mit langer Ausführungszeit für Anfragen zurückgeben, die nicht innerhalb der Zeitspanne eines einzelnen API-Aufrufs abgeschlossen werden.

In den folgenden Abschnitten wird im Detail auf die einzelnen Standardmethoden eingegangen. Die Beispiele demonstrieren die in .proto-Dateien definierten Methoden mit entsprechenden Anmerkungen für die HTTP-Zuordnungen. Sie finden im Repository der Google APIs zahlreiche Beispiele für die Anwendung von Standardmethoden.

Hinweis: Die in den folgenden Beispielen gezeigte Annotation google.api.http verwendet die Syntax der gRPC-Transcodierung, um URIs zu definieren.

List

Die Methode List verwendet einen Sammlungsnamen und null oder mehr Parameter als Eingabe und gibt eine Liste der Ressourcen zurück, die mit der Eingabe übereinstimmen.

List wird in der Regel für die Ressourcensuche verwendet. Die Methode List eignet sich für Daten aus einer einzelnen Sammlung, deren Größe begrenzt und die nicht zwischengespeichert ist. Für umfassendere Anwendungsfälle sollte die benutzerdefinierte Methode Search verwendet werden.

Ein Batchabruf wie z. B. mit einer Methode, bei der für mehrere eingegebene Ressourcen-IDs je ein Objekt zurückgegeben wird, sollte mit der benutzerdefinierten Methode BatchGet statt mit der Methode List implementiert werden. Wenn Sie jedoch eine bereits vorhandene List-Methode mit dieser Funktionalität nutzen, können Sie stattdessen die Methode List für diesen Zweck wiederverwenden. Bei Verwendung der benutzerdefinierten Methode BatchGet sollte diese HTTP GET zugeordnet sein.

Gängige anwendbare Muster sind Paginierung und Ergebnissortierung.

Anwendbare Namenskonventionen sind Filterfeld und Ergebnisfeld.

HTTP-Zuordnung:

• Die List-Methode muss ein HTTP-GET-Verb verwenden.
• Die Anfragenachrichtenfelder, die den Namen der Sammlung empfangen, deren Ressourcen aufgelistet werden, sollten dem URL-Pfad zugeordnet sein. Wenn der Sammlungsname dem URL-Pfad zugeordnet ist, muss das letzte Segment der URL-Vorlage, also die Sammlungs-ID, ein Literal sein.
• Alle verbleibenden Anfragenachrichtenfelder werden den URL-Suchparametern zugeordnet.
• Es gibt keinen Anfragetext. Die API-Konfiguration darf nicht die Klausel body deklarieren.
• Der Antworttext sollte eine Liste mit Ressourcen sowie optionale Metadaten enthalten.

Beispiel:

// Lists books in a shelf.
rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
  // List method maps to HTTP GET.
  option (google.api.http) = {
    // The `parent` captures the parent resource name, such as "shelves/shelf1".
    get: "/v1/{parent=shelves/*}/books"
  };
}

message ListBooksRequest {
  // The parent resource name, for example, "shelves/shelf1".
  string parent = 1;

  // The maximum number of items to return.
  int32 page_size = 2;

  // The next_page_token value returned from a previous List request, if any.
  string page_token = 3;
}

message ListBooksResponse {
  // The field name should match the noun "books" in the method name.  There
  // will be a maximum number of items returned based on the page_size field
  // in the request.
  repeated Book books = 1;

  // Token to retrieve the next page of results, or empty if there are no
  // more results in the list.
  string next_page_token = 2;
}

Get

Für die Methode Get werden als Eingabe ein Ressourcenname und null oder mehr Parameter verwendet, um die angegebene Ressource zurückzugeben.

HTTP-Zuordnung:

• Die Get-Methode muss ein HTTP-GET-Verb verwenden.
• Die Anfragenachrichtenfelder, die den Ressourcennamen empfangen, sollten dem URL-Pfad zugeordnet sein.
• Alle verbleibenden Anfragenachrichtenfelder werden den URL-Suchparametern zugeordnet.
• Es gibt keinen Anfragetext. Die API-Konfiguration darf nicht die Klausel body deklarieren.
• Die zurückgegebene Ressource wird dem gesamten Antworttext zugeordnet.

Beispiel:

// Gets a book.
rpc GetBook(GetBookRequest) returns (Book) {
  // Get maps to HTTP GET. Resource name is mapped to the URL. No body.
  option (google.api.http) = {
    // Note the URL template variable which captures the multi-segment resource
    // name of the requested book, such as "shelves/shelf1/books/book2"
    get: "/v1/{name=shelves/*/books/*}"
  };
}

message GetBookRequest {
  // The field will contain name of the resource requested, for example:
  // "shelves/shelf1/books/book2"
  string name = 1;
}

Create

Für die Methode Create werden als Eingabe der Name einer übergeordneten Ressource, eine Ressource und null oder mehr Parameter verwendet. Damit wird unter der angegebenen übergeordneten Ressource eine neue Ressource erstellt und zurückgegeben.

Wenn eine API das Erstellen von Ressourcen unterstützt, sollte sie für jeden erstellbaren Ressourcentyp die Methode Create enthalten.

HTTP-Zuordnung:

• Die Create-Methode muss ein HTTP-POST-Verb verwenden.
• Die Anfragenachricht sollte das Feld parent für den Namen der übergeordneten Ressource enthalten, unter der die Ressource erstellt werden soll.
• Das Anfragenachrichtenfeld mit der Ressource muss dem Text der HTTP-Anfrage zugeordnet sein. Wenn Sie für die Methode Create die Annotation google.api.http nutzen, muss das Format body: "<resource_field>" verwendet werden.
• Die Anfrage kann ein Feld <resource>_id enthalten, damit sich bei Aufrufen eine vom Client zugewiesene ID auswählen lässt. Dieses Feld kann in der Ressource enthalten sein.
• Alle verbleibenden Anfragenachrichtenfelder sollten den URL-Suchparametern zugeordnet werden.
• Die zurückgegebene Ressource sollte dem gesamten Antworttext zugeordnet werden.

Wenn die Methode Create den vom Client zugewiesenen Ressourcennamen unterstützt und die Ressource bereits vorhanden ist, sollte die Anfrage entweder den Fehlercode ALREADY_EXISTS ausgeben oder einen anderen vom Server zugewiesenen Ressourcennamen verwenden. In der Dokumentation sollte in diesem Fall angegeben werden, dass der erstellte Ressourcenname von dem übergebenen Ressourcennamen abweichen kann.

Die Methode Create muss eine Eingaberessource verwenden, damit bei einer Änderung des Ressourcenschemas nicht das Anfrageschema und das Ressourcenschema aktualisiert werden müssen. Ressourcenfelder, die von den Clients nicht festgelegt werden können, müssen als reine Ausgabefelder dokumentiert werden.

Beispiel:

// Creates a book in a shelf.
rpc CreateBook(CreateBookRequest) returns (Book) {
  // Create maps to HTTP POST. URL path as the collection name.
  // HTTP request body contains the resource.
  option (google.api.http) = {
    // The `parent` captures the parent resource name, such as "shelves/1".
    post: "/v1/{parent=shelves/*}/books"
    body: "book"
  };
}

message CreateBookRequest {
  // The parent resource name where the book is to be created.
  string parent = 1;

  // The book id to use for this book.
  string book_id = 3;

  // The book resource to create.
  // The field name should match the Noun in the method name.
  Book book = 2;
}

rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
  option (google.api.http) = {
    post: "/v1/shelves"
    body: "shelf"
  };
}

message CreateShelfRequest {
  Shelf shelf = 1;
}

Update

Für die Methode Update wird als Eingabe eine Anfragenachricht mit einer Ressource und mit null oder mehr Parametern verwendet. Damit werden die angegebene Ressource und deren Eigenschaften aktualisiert und die aktualisierte Ressource anschließend zurückgegeben.

Veränderliche Ressourcenattribute sollten mit Ausnahme der Attribute, die den Namen oder das übergeordnete Element der Ressource enthalten, durch die Methode Update verändert werden können. Funktionen zum Umbenennen oder Verschieben einer Ressource dürfen nicht durch die Methode Update ausgeführt werden, sondern müssen stattdessen mit einer benutzerdefinierten Methode verarbeitet werden.

HTTP-Zuordnung:

• Die Standardmethode Update sollte Teilaktualisierungen von Ressourcen unterstützen und das HTTP-Verb PATCH mit einem FieldMask-Feld namens update_mask verwenden. Ausgabefelder, die der Client als Eingabe nutzt, sollten ignoriert werden.
• Die Methode Update, die eine erweiterte Patching-Semantik erfordert, etwa zum Anfügen an ein wiederkehrendes Feld, muss durch eine benutzerdefinierte Methode verfügbar gemacht werden.
• Wenn die Methode Update nur die vollständige Ressourcenaktualisierung unterstützt, muss sie das HTTP-Verb PUT verwenden. Von einem vollständigen Update wird jedoch dringend abgeraten, da es beim Hinzufügen neuer Ressourcenfelder zu Problemen mit der Abwärtskompatibilität kommt.
• Das Nachrichtenfeld, das den Ressourcenamen empfängt, muss dem URL-Pfad zugeordnet sein. Das Feld kann in der Ressourcennachricht selbst enthalten sein.
• Das Anfragenachrichtenfeld mit der Ressource muss dem Anfragetext zugeordnet sein.
• Alle verbleibenden Anfragenachrichtenfelder müssen den URL-Suchparametern zugeordnet sein.
• Die Antwortnachricht muss die aktualisierte Ressource an sich zurückgeben.

Wenn die API vom Client zugewiesene Ressourcennamen akzeptiert, kann der Server dem Client erlauben, einen nicht vorhandenen Ressourcennamen anzugeben und eine neue Ressource zu erstellen. Andernfalls sollte die Methode Update bei Angabe eines nicht vorhandenen Ressourcennamens fehlschlagen. Wenn dies die einzige Fehlerbedingung ist, sollte der Fehlercode NOT_FOUND verwendet werden.

Eine API mit der Methode Update, die das Erstellen von Ressourcen unterstützt, sollte außerdem die Methode Create bereitstellen. Dies ist erforderlich, da nicht klar ist, wie Ressourcen erstellt werden sollen, wenn die Update-Methode der einzige Weg dafür ist.

Beispiel:

// Updates a book.
rpc UpdateBook(UpdateBookRequest) returns (Book) {
  // Update maps to HTTP PATCH. Resource name is mapped to a URL path.
  // Resource is contained in the HTTP request body.
  option (google.api.http) = {
    // Note the URL template variable which captures the resource name of the
    // book to update.
    patch: "/v1/{book.name=shelves/*/books/*}"
    body: "book"
  };
}

message UpdateBookRequest {
  // The book resource which replaces the resource on the server.
  Book book = 1;

  // The update mask applies to the resource. For the `FieldMask` definition,
  // see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask
  FieldMask update_mask = 2;
}

Löschen

Für die Methode Delete werden als Eingabe ein Ressourcenname und null oder mehr Parameter verwendet, um die angegebene Ressource zu löschen oder um den Löschvorgang dafür zu planen. Die Delete-Methode sollte google.protobuf.Empty zurückgeben.

Eine API sollte nicht von den Informationen abhängig sein, die von der Methode Delete zurückgegeben werden, da diese nicht wiederholt aufgerufen werden kann.

HTTP-Zuordnung:

• Die Delete-Methode muss ein HTTP-DELETE-Verb verwenden.
• Die Anfragenachrichtenfelder, die den Ressourcennamen empfangen, sollten dem URL-Pfad zugeordnet sein.
• Alle verbleibenden Anfragenachrichtenfelder werden den URL-Suchparametern zugeordnet.
• Es gibt keinen Anfragetext. Die API-Konfiguration darf nicht die Klausel body deklarieren.
• Wenn die Methode Delete die Ressource sofort entfernt, sollte eine leere Antwort zurückgegeben werden.
• Wenn durch die Methode Delete ein Vorgang mit langer Ausführungszeit initiiert wird, sollte dieser Vorgang zurückgegeben werden.
• Wenn die Methode Delete die Ressource lediglich als gelöscht markiert, sollte die aktualisierte Ressource zurückgegeben werden.

Aufrufe der Methode Delete sollten idempotent sein, müssen aber nicht die gleiche Antwort liefern. Jede beliebige Anzahl an Delete-Anfragen sollte letztlich dazu führen, dass eine Ressource gelöscht wird. Es sollte aber nur die erste Anfrage einen Erfolgscode zurückgeben. Nachfolgende Anfragen sollten google.rpc.Code.NOT_FOUND ergeben.

Beispiel:

// Deletes a book.
rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
  // Delete maps to HTTP DELETE. Resource name maps to the URL path.
  // There is no request body.
  option (google.api.http) = {
    // Note the URL template variable capturing the multi-segment name of the
    // book resource to be deleted, such as "shelves/shelf1/books/book2"
    delete: "/v1/{name=shelves/*/books/*}"
  };
}

message DeleteBookRequest {
  // The resource name of the book to be deleted, for example:
  // "shelves/shelf1/books/book2"
  string name = 1;
}