Benutzerdefinierte Methoden

In diesem Kapitel wird erläutert, wie Sie benutzerdefinierte Methoden für API-Designs verwenden.

Benutzerdefinierte Methoden beziehen sich auf die neben den fünf Standardmethoden verfügbaren API-Methoden. Sie sollten nur für Funktionen verwendet werden, die mit den Standardmethoden schwierig zu bewerkstelligen sind. Generell sollten API-Designer Standardmethoden nach Möglichkeit benutzerdefinierten Methoden vorziehen. Die Standardmethoden haben eine einfachere und klar definierte Semantik, die den meisten Entwicklern vertraut ist. Dies macht sie nutzerfreundlicher und weniger fehleranfällig. Außerdem haben Standardmethoden wie die Abrechnung, Fehlerbehebung, Protokollierung und das Monitoring den Vorteil, dass die API-Plattform sie besser versteht und unterstützt.

Eine benutzerdefinierte Methode kann einer Ressource, einer Sammlung oder einem Dienst zugeordnet werden. Sie kann eine beliebige Anfrage ausführen und eine beliebige Antwort zurückgeben. Außerdem unterstützt sie das Streaming von Anfragen und Antworten.

Die Namen benutzerdefinierter Methoden müssen den Konventionen für Methodennamen folgen.

HTTP-Zuordnung

Für benutzerdefinierte Methoden sollte die folgende allgemeine HTTP-Zuordnung verwendet werden:

https://service.name/v1/some/resource/name:customVerb

Sie unterstützten beliebige Pfade, wenn Sie zum Trennen des benutzerdefinierten Verbs vom Ressourcennamen : anstelle von / verwenden. Das Wiederherstellen einer Datei kann beispielsweise POST /files/a/long/file/name:undelete zugeordnet werden.

Bei der Auswahl der HTTP-Zuordnung werden folgende Richtlinien angewendet:

  • Für benutzerdefinierte Methoden sollte das HTTP-Verb POST verwendet werden, da es die flexibelste Semantik hat. Dies gilt nicht für Methoden, die als Alternative für die Methode "get" oder "list" dienen. Diese können GET verwenden, wann immer dies möglich ist. Details finden Sie unter dem dritten Punkt.
  • Benutzerdefinierte Methoden sollten nicht das HTTP-Verb PATCH verwenden, können jedoch andere HTTP-Verben nutzen. Die Methoden müssen in diesen Fällen der HTTP-Standardsemantik für das jeweilige Verb folgen.
  • Insbesondere benutzerdefinierte Methoden, die das HTTP-Verb GET verwenden, müssen idempotent sein und dürfen keine Nebenerscheinungen haben. Beispielsweise sollte das HTTP-Verb GET von benutzerdefinierten Methoden verwendet werden, die spezielle Ressourcenansichten implementieren.
  • Die Anfragenachrichtenfelder, die den Ressourcennamen der Ressource oder Sammlung empfangen, mit der die benutzerdefinierte Methode verknüpft ist, sollten dem URL-Pfad zugeordnet sein.
  • Der URL-Pfad muss mit einem Suffix enden, das aus einem Doppelpunkt gefolgt vom benutzerdefinierten Verb besteht.
  • Wenn das HTTP-Verb, das für die benutzerdefinierte Methode verwendet wird, einen HTTP-Anfragetext ermöglicht, (gilt für POST, PUT, PATCH oder ein benutzerdefiniertes HTTP-Verb), muss die HTTP-Konfiguration dieser benutzerdefinierten Methode die Klausel body: "*" verwenden und alle verbleibenden Anfragenachrichtenfelder werden dem HTTP-Anfragetext zugeordnet.
  • Wenn das für die benutzerdefinierte Methode verwendete HTTP-Verb keinen HTTP-Anfragetext (GET, DELETE) akzeptiert, darf die HTTP-Konfiguration dieser Methode die body-Klausel überhaupt nicht verwenden. Alle verbleibenden Anfragenachrichtenfelder sollten den URL-Abfrageparametern zugeordnet werden.

WARNUNG: Wenn durch einen Dienst mehrere APIs implementiert werden, muss der API-Ersteller die Dienstkonfiguration mit Sorgfalt erstellen, um zwischen APIs Konflikte mit benutzerdefinierten Verben zu vermeiden.

// This is a service level custom method.
rpc Watch(WatchRequest) returns (WatchResponse) {
  // Custom method maps to HTTP POST. All request parameters go into body.
  option (google.api.http) = {
    post: "/v1:watch"
    body: "*"
  };
}

// This is a collection level custom method.
rpc ClearEvents(ClearEventsRequest) returns (ClearEventsResponse) {
  option (google.api.http) = {
    post: "/v3/events:clear"
    body: "*"
  };
}

// This is a resource level custom method.
rpc CancelEvent(CancelEventRequest) returns (CancelEventResponse) {
  option (google.api.http) = {
    post: "/v3/{name=events/*}:cancel"
    body: "*"
  };
}

// This is a batch get custom method.
rpc BatchGetEvents(BatchGetEventsRequest) returns (BatchGetEventsResponse) {
  // The batch get method maps to HTTP GET verb.
  option (google.api.http) = {
    get: "/v3/events:batchGet"
  };
}

Anwendungsfälle

Hier ein paar weitere Szenarien, in denen benutzerdefinierte Methoden von Vorteil sein können:

  • Virtuelle Maschine neu starten: Als Designalternativen könnte "create a reboot resource in collection of reboots" verwendet werden, was jedoch unnötig komplex klingt, oder "virtual machine has a mutable state which the client can update from RUNNING to RESTARTING". Dies würde jedoch die Frage aufwerfen, welche Zustandsübergänge noch möglich sind. Darüber hinaus ist ein Neustart ein bekanntes Konzept, das sich gut in eine benutzerdefinierte Methode übersetzen lässt, die intuitiv die Erwartungen von Entwicklern erfüllt.
  • E-Mail senden: Durch das Erstellen einer E-Mail-Nachricht sollte diese nicht notwendigerweise gesendet werden (Entwurf). Im Vergleich zur Designalternative, bei der eine Nachricht in die Sammlung "Postausgang" verschoben wird, hat die benutzerdefinierte Methode den Vorteil, dass sie für API-Nutzer leichter auffindbar ist. Außerdem wird das Konzept damit direkter modelliert.
  • Mitarbeiter befördern: Bei einer Implementierung als Standard-update müsste der Kunde die Unternehmensrichtlinien für den Beförderungsprozess replizieren, um sicherzustellen, dass die Beförderung auf der richtigen Ebene innerhalb derselben Karriereleiter usw. erfolgt.
  • Batchmethoden: Für leistungskritische Methoden kann es nützlich sein, den Aufwand vor der Anfrage durch benutzerdefinierte Batchmethoden zu reduzieren. Beispiel: accounts.locations.batchGet.

In den folgenden Fällen sind beispielsweise Standardmethoden effektiver als benutzerdefinierte Methoden:

  • Fragen Sie Ressourcen mit verschiedenen Abfrageparametern ab (verwenden Sie die Standardmethode list mit Standardlistenfilterung).
  • Bei einer einfachen Änderung des Ressourcenattributs: Verwenden Sie die Standardmethode update mit einer Feldmaske.
  • Beim Verwerfen einer Benachrichtigung: Verwenden Sie die Standardmethode delete.

Gängige benutzerdefinierte Methoden

Nachfolgend finden Sie eine Auswahl gängiger bzw. nützlicher Namen für benutzerdefinierte Methoden. API-Designer sollten diese nach Möglichkeit eigenen Namen vorziehen, um die Konsistenz innerhalb der APIs zu erhöhen.

Methodenname Benutzerdefiniertes Verb HTTP-Verb Hinweis
Cancel :cancel POST Bricht eine ausstehende Operation ab, z. B. operations.cancel.
BatchGet :batchGet GET Führt einen Batch-Abruf mehrerer Ressourcen durch. (Details finden Sie in der Beschreibung zu "List".)
Move :move POST Verschiebt eine Ressource von einem übergeordneten Element zu einem anderen, z. B. folders.move.
Search :search GET Alternative zu List zum Abrufen von Daten, die nicht der Listensemantik entsprechen, z. B. services.search.
Undelete :undelete POST Stellt eine zuvor gelöschte Ressource wieder her, z. B. services.undelete. Die empfohlene Aufbewahrungsdauer beträgt 30 Tage.
Zurück
Standardmethoden
Weiter
Standardfelder