Api

Api は、API インターフェースの軽量記述子です。

インターフェースは、.proto ファイル内の "service" キーワードなど、一部のコンテキストでは「プロトコル バッファ サービス」とも呼ばれますが、API サービスとは異なります。API サービスは、インターフェースの具体的な実装を表すものであり、単なるメソッドとバインディングの記述とは対照的です。メッセージ自体の名前など、他のコンテキストでは単に「API」と呼ばれることもあります。詳細な用語については、https://cloud.google.com/apis/design/glossary をご覧ください。

JSON 表現 

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

string

このインターフェースの完全修飾名。パッケージ名の後ろにインターフェースの単純名が続きます。

methods[]

object(Method)

このインターフェースのメソッド。順序の指定はありません。

options[]

object(Option)

インターフェースに添付されたメタデータ。

version

string

このインターフェースのバージョン文字列。指定する場合、major-version.minor-version の形式を取る必要があります（例: 1.10）。マイナー バージョンを省略するとデフォルトでゼロに設定されます。バージョン フィールド全体が空の場合は、以下に説明するようにメジャー バージョンがパッケージ名から取得されます。フィールドが空でない場合は、パッケージ名のバージョンがここで指定されるバージョンと一致しているかどうかの検証が行われます。

バージョン設定スキーマでは意味のあるバージョン設定が使用されます。つまり、メジャー バージョン番号は互換性に対応しない変更、マイナー バージョンは追加となる、互換性に対応する変更を意味します。どちらのバージョン番号も、それぞれのバージョンを使用することで想定される結果をユーザーに示すものとなるため、プロダクト プランに基づいて慎重に選択する必要があります。

メジャー バージョンはインターフェースのパッケージ名にも反映されます。google.feature.v1 のように v<major-version> で終わる必要があります。メジャー バージョン 0 と 1 の場合、サフィックスは省略できます。メジャー バージョン 0 は、試験運用版の一般提供されていないインターフェースでのみ使用してください。
sourceContext

object(SourceContext)

このメッセージによって表されるプロトコル バッファ サービスのソース コンテキスト。

mixins[]

object(Mixin)

含まれるインターフェース。Mixin をご覧ください。

syntax

enum(Syntax)

サービスのソース構文。

メソッド

Method は API インターフェースのメソッドを表します。

JSON 表現 

{
  "name": string,
  "requestTypeUrl": string,
  "requestStreaming": boolean,
  "responseTypeUrl": string,
  "responseStreaming": boolean,
  "options": [
    {
      object(Option)
    }
  ],
  "syntax": enum(Syntax)
}
フィールド
name

string

このメソッドの単純名。

requestTypeUrl

string

入力メッセージ タイプの URL。

requestStreaming

boolean

true の場合、リクエストがストリーミングされます。

responseTypeUrl

string

出力メッセージ タイプの URL。

responseStreaming

boolean

true の場合、レスポンスがストリーミングされます。

options[]

object(Option)

メソッドに関連付けられる任意のメタデータ。

syntax

enum(Syntax)

このメソッドのソース構文。

Option

メッセージ、フィールド、列挙型などに関連付けることのできるプロトコル バッファ オプション。

JSON 表現 

{
  "name": string,
  "value": {
    "@type": string,
    field1: ...,
    ...
  }
}
フィールド
name

string

オプションの名前。protobuf 組み込みオプション（descriptor.proto で定義されたオプション）の場合は、省略名になります。たとえば、"mapEntry" です。カスタム オプションの場合は、完全修飾名にする必要があります。たとえば、"google.api.http" です。

value

object

メッセージにパックされたオプションの値。値がプリミティブの場合は、google/protobuf/wrappers.proto で定義された対応するラッパータイプを使用する必要があります。値が列挙型の場合は、google.protobuf.Int32Value 型を使用して int32 値として格納する必要があります。

任意のデータ型のフィールドを含むオブジェクト。タイプを識別する URI を含む追加フィールド "@type"。例: { "id": 1234, "@type": "types.example.com/standard/id" }。

SourceContext

SourceContext は protobuf 要素のソースに関する情報を表します（その定義元のファイルなど）。

JSON 表現 

{
  "fileName": string
}
フィールド
fileName

string

関連付けのある protobuf 要素が含まれていた .proto ファイルのパス修飾名。たとえば "google/protobuf/sourceContext.proto" です。

Mixin

このインターフェースに含まれる API インターフェースを宣言します。含んでいる方のインターフェースでは、含まれているインターフェースのすべてのメソッドを再宣言する必要がありますが、ドキュメントとオプションは次のように継承されます。

  • コメントと空白文字を取り除いた後、再宣言されたメソッドのドキュメント文字列が空の場合、文字列は元のメソッドから継承されます。

  • 再宣言されたメソッドにないサービス設定（http、公開設定）に属する各アノテーションは継承されます。

  • http のアノテーションが継承される場合、パスパターンは次のように変更されます。バージョンのプレフィックスはすべて、含んでいる方のインターフェースのバージョンと root パス（指定された場合）に置き換えられます。

単純な 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=**}";
  }
}

mixin 設定の例:

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

mixin 構文は、AccessControl のすべてのメソッドが Storage でも同じ名前およびリクエスト タイプ、レスポンス タイプを使用して宣言されることを意味しています。ドキュメント ジェネレータまたはアノテーション プロセッサには、次のとおりにドキュメントとアノテーションを継承した後、有効な Storage.GetAcl メソッドが表示されます。

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

パスパターンのバージョンがどのように v1 から v2 に変わったかに着目してください。

mixin の root フィールドを指定する場合は、継承された HTTP パスが置かれる相対パスである必要があります。次に例を示します。

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

これは、次の継承された HTTP アノテーションを意味します。

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

{
  "name": string,
  "root": string
}
フィールド
name

string

含まれているインターフェースの完全修飾名。

root

string

空でない場合、継承された HTTP パスがルート設定されているパスが指定されます。