カスタム メソッド

この章では、API 設計でカスタム メソッドを使用する方法について説明します。

カスタム メソッドは、5 つの標準メソッド以外の API メソッドを指します。カスタム メソッドは、標準メソッドでは簡単に表現できない機能にのみ使用することが推奨されます。一般的に、API 設計者には、可能な限り、カスタム メソッドではなく標準メソッドを選択することが推奨されます。標準メソッドにはほとんどのデベロッパーによく知られた単純で明確なセマンティクスがあるため、使いやすく、エラーの発生が少なくなります。標準メソッドのもう 1 つのメリットは、API プラットフォームでは、請求、エラー処理、ロギング、モニタリングなどの標準メソッドが、より深く理解され、サポートされていることです。

カスタム メソッドは、リソース、コレクション、サービスに関連付けることができます。 任意のリクエストを受け取り、任意のレスポンスを返すことが可能で、ストリーミング リクエストとレスポンスもサポートしています。

カスタム メソッド名はメソッドの命名規則に従っていることが必須です。

HTTP マッピング

カスタム メソッドでは、次の汎用 HTTP マッピングを使用することが推奨されます。

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

カスタム動詞とリソース名を区切るために / ではなく : を使用する理由は、任意のパスに対応するためです。たとえば、ファイルの削除の取り消しは POST /files/a/long/file/name:undelete にマッピングされます。

HTTP マッピングを選択する場合は、次のガイドラインが適用されます。

• 可能な場合は GET を使用できる、get または list の代わりとして機能するメソッドを除き、カスタム メソッドでは、セマンティクスの柔軟性が高い HTTP POST 動詞を使用することが推奨されます。詳細については、3 番目の項目をご覧ください。
• カスタム メソッドでは HTTP PATCH を使用しないことが推奨されますが、その他の HTTP 動詞は使用できます。この場合、メソッドはその動詞について標準 HTTP セマンティクスに従うことが必須です。
• 特に、HTTP GET を使用するカスタム メソッドは、べき等であること、副次的影響を及ぼさないことが必須です。たとえば、リソース上で特別なビューを実装するカスタム メソッドは、HTTP GET を使用することが推奨されます。
• カスタム メソッドが関連付けられているリソースまたはコレクションのリソース名を受け取るリクエスト メッセージ フィールドは、URL パスに対応させることが推奨されます。
• URL パスの末尾には、コロンとそれに続くカスタム動詞で構成される接尾辞を指定することが必須です。
• カスタム メソッドで使用される HTTP 動詞で HTTP リクエスト本文（これは POST、PUT、PATCH、またはカスタム HTTP 動詞に適用されます）を使用できる場合、そのカスタム メソッドの HTTP 構成では body: "*" 句を使用することが必須です。残りのリクエスト メッセージ フィールドはすべて HTTP リクエスト本文にマッピングする必要があります。
• カスタム メソッドに使用される HTTP 動詞で HTTP リクエスト本文（GET、DELETE）が受け入れられない場合、そのようなメソッドの HTTP 構成では、body 句を使用することはできません。残りのすべてのリクエスト メッセージ フィールドは、すべてURL クエリ パラメータにマッピングする必要があります。

警告: サービスで複数の API を実装する場合、API 間のカスタム動詞の競合を避けるには、API プロデューサーがサービス構成を慎重に作成することが必須となります。

// 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"
  };
}

ユースケース

カスタム メソッドが適切な選択肢となるその他のシナリオをいくつか示します。

• 仮想マシンの再起動。 代替となる設計が、「再起動のコレクションで再起動リソースを作成する」となり、過度に複雑と思われる場合や、「仮想マシンの状態が変更可能で、それをクライアントが実行中から再起動中に更新できる」となり、他のどの状態への移行が可能であるかという疑問が発生する場合があります。 また、再起動は、よく知られ、デベロッパーの期待を直感的に満たす、カスタム メソッドに反映しやすいコンセプトです。
• メールの送信。 メール メッセージを作成しても必ずしも送信するとは限りません（下書き）。設計の選択肢（メッセージを「送信トレイ」コレクションに移動する）と比較して、カスタム メソッドには、API ユーザーがより発見しやすい、およびコンセプトがより直接的にモデル化されるというメリットがあります。
• 従業員の昇進。 標準の update として実装されてた場合、クライアントは昇進プロセスを管理する企業ポリシーを複製して、昇進が同じ昇進階段内などで適切なレベルにで行われるようにする必要があります。
• バッチメソッド。 パフォーマンスが重要なメソッドの場合は、リクエストごとのオーバーヘッドを減らすためにカスタム バッチメソッドを提供することが役立つ可能性があります。例: accounts.locations.batchGet

カスタム メソッドよりも標準メソッドの方が適している例をいくつか示します。

• クエリ パラメータが異なるクエリ リソース（標準リスト フィルタリングで標準 list メソッドを使用）。
• 単純なリソース プロパティの変更（フィールド マスクで標準 update を使用）。
• お知らせを非表示にする（標準 delete メソッドを使用）。

一般的なカスタム メソッド

一般的に使用される、または役立つカスタム メソッド名のリストを以下に示します。API 全体の整合性を促進するために、API 設計者は、独自のメソッドを導入する前に、これらの名前を検討することが推奨されます。

メソッド名	カスタム動詞	HTTP 動詞	メモ
Cancel	:cancel	POST	未処理のオペレーション（operations.cancel など）をキャンセルします。
BatchGet	:batchGet	GET	複数のリソースをバッチで取得します。（詳しくは、リストの説明をご覧ください）。
Move	:move	POST	folders.move など、リソースを別の親に移動します。
Search	:search	GET	services.search など、List セマンティクスに準拠していないデータを取得するための List の代替。
Undelete	:undelete	POST	以前に削除したリソース（services.undelete など）を復元します。推奨保持期間は 30 日です。