Protocol Buffers の Well-Known Types

インデックス

• Any (message)
• Api (message)
• BoolValue (message)
• BytesValue (message)
• DoubleValue (message)
• Duration (message)
• Empty (message)
• Enum (message)
• EnumValue (message)
• Field (message)
• Field.Cardinality (enum)
• Field.Kind (enum)
• FieldMask (message)
• FloatValue (message)
• Int32Value (message)
• Int64Value (message)
• ListValue (message)
• Method (message)
• Mixin (message)
• NullValue (enum)
• Option (message)
• SourceContext (message)
• StringValue (message)
• Struct (message)
• Syntax (enum)
• Timestamp (message)
• Type (message)
• UInt32Value (message)
• UInt64Value (message)
• Value (message)

「Value」で終わる Well-Known Types は、BoolValue や EnumValue のような他の型のラッパーメッセージです。これらは現在、廃止されています。今日、ラッパーを使用する唯一の理由は、

• すでにそれらを使用しているメッセージとのワイヤー互換性。
• Any メッセージにスカラー値を入れたい場合。

ほとんどの場合、より良い選択肢があります。

• 新しいメッセージでは、通常の明示的な存在を示すフィールド（proto2/proto3 の optional、edition >= 2023 の通常フィールド）を使用する方が良いです。
• Any フィールドよりも、一般的に拡張（Extensions）の方が良い選択肢です。

Any

Any には、シリアライズされたメッセージの型を記述する URL とともに、任意のシリアライズされたメッセージが含まれています。

JSON

Any 値の JSON 表現は、デシリアライズされた埋め込みメッセージの通常の表現を使用し、型 URL を含む追加フィールド @type を持ちます。例：

package google.profile;
message Person {
  string first_name = 1;
  string last_name = 2;
}

{
  "@type": "type.googleapis.com/google.profile.Person",
  "firstName": <string>,
  "lastName": <string>
}

埋め込みメッセージの型が well-known で、カスタムの JSON 表現を持つ場合、その表現は @type フィールドに加えて、カスタム JSON を保持する value フィールドを追加して埋め込まれます。例（メッセージ google.protobuf.Duration の場合）：

{
  "@type": "type.googleapis.com/google.protobuf.Duration",
  "value": "1.212s"
}

Api

Api は、protocol buffer サービスのための軽量な記述子です。

BoolValue

bool のラッパーメッセージ。

BoolValue の JSON 表現は、JSON の true と false です。

BytesValue

bytes のラッパーメッセージ。

BytesValue の JSON 表現は JSON 文字列です。

DoubleValue

double のラッパーメッセージ。

DoubleValue の JSON 表現は JSON 数値です。

Duration

Duration は、秒とナノ秒解像度の秒の小数部として表される、符号付きの固定長の期間を表します。これは、いかなるカレンダーや「日」「月」のような概念からも独立しています。2 つの Timestamp 値の差が Duration であり、Timestamp に加算または減算できるという点で、Timestamp と関連しています。範囲は約±10,000年です。

例1：疑似コードで2つの Timestamp から Duration を計算します。

Timestamp start = ...;
Timestamp end = ...;
Duration duration = ...;

duration.seconds = end.seconds - start.seconds;
duration.nanos = end.nanos - start.nanos;

if (duration.seconds < 0 && duration.nanos > 0) {
  duration.seconds += 1;
  duration.nanos -= 1000000000;
} else if (duration.seconds > 0 && duration.nanos < 0) {
  duration.seconds -= 1;
  duration.nanos += 1000000000;
}

例2：疑似コードで Timestamp + Duration から Timestamp を計算します。

Timestamp start = ...;
Duration duration = ...;
Timestamp end = ...;

end.seconds = start.seconds + duration.seconds;
end.nanos = start.nanos + duration.nanos;

if (end.nanos < 0) {
  end.seconds -= 1;
  end.nanos += 1000000000;
} else if (end.nanos >= 1000000000) {
  end.seconds += 1;
  end.nanos -= 1000000000;
}

Duration の JSON 表現は、秒を示すために s で終わる String であり、その前に秒数が続き、ナノ秒は秒の小数部として表現されます。

Empty

API で重複した空のメッセージを定義するのを避けるために再利用できる、汎用の空のメッセージです。典型的な例は、API メソッドのリクエストまたはレスポンスタイプとして使用することです。例えば：

service Foo {
  rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
}

Empty の JSON 表現は、空の JSON オブジェクト {} です。

Enum

Enum 型定義

EnumValue

Enum 値定義。

Field

メッセージ型の単一のフィールド。

Cardinality

フィールドが optional、required、または repeated かどうか。

Kind

基本的なフィールド型。

FieldMask

FieldMask は、シンボリックなフィールドパスのセットを表します。例：

paths: "f.a"
paths: "f.b.d"

ここで、f はあるルートメッセージ内のフィールドを、a と b は f 内で見つかるメッセージのフィールドを、d は f.b 内のメッセージで見つかるフィールドを表します。

フィールドマスクは、get 操作によって返されるべきフィールドのサブセット（*プロジェクション*）や、update 操作によって変更されるべきフィールドを指定するために使用されます。フィールドマスクには、カスタムの JSON エンコーディングもあります（下記参照）。

プロジェクションにおけるフィールドマスク

FieldMask が*プロジェクション*を指定する場合、API はレスポンスメッセージ（またはサブメッセージ）をフィルタリングし、マスクで指定されたフィールドのみを含むようにします。例えば、次の「マスキング前」のレスポンスメッセージを考えてみましょう。

f {
  a : 22
  b {
    d : 1
    x : 2
  }
  y : 13
}
z: 8

前の例のマスクを適用した後、API レスポンスにはフィールド x、y、z の特定の値は含まれなくなります（それらの値はデフォルトに設定され、proto テキスト出力では省略されます）。

f {
  a : 22
  b {
    d : 1
  }
}

repeated フィールドは、フィールドマスクの最後の位置以外では許可されません。

get 操作に FieldMask オブジェクトが存在しない場合、操作はすべてのフィールドに適用されます（すべてのフィールドの FieldMask が指定されたかのように）。

フィールドマスクは必ずしもトップレベルのレスポンスメッセージに適用されるわけではないことに注意してください。REST get 操作の場合、フィールドマスクは直接レスポンスに適用されますが、REST list 操作の場合、マスクは返されたリソースリスト内の個々の各メッセージに適用されます。REST カスタムメソッドの場合、他の定義が使用されることがあります。マスクがどこに適用されるかは、API での宣言とともに明確に文書化されます。いずれの場合でも、返されるリソース/リソースへの影響は、API にとって必須の動作です。

更新操作におけるフィールドマスク

更新操作におけるフィールドマスクは、対象リソースのどのフィールドが更新されるかを指定します。API は、マスクで指定されたフィールドの値のみを変更し、他はそのままにしておく必要があります。更新された値を記述するためにリソースが渡された場合、API はマスクでカバーされていないすべてのフィールドの値を無視します。

フィールドの値をデフォルトにリセットするためには、そのフィールドがマスクに含まれ、提供されたリソースでデフォルト値に設定されている必要があります。したがって、リソースのすべてのフィールドをリセットするには、リソースのデフォルトインスタンスを提供し、マスクですべてのフィールドを設定するか、以下に説明するようにマスクを提供しないようにします。

更新時にフィールドマスクが存在しない場合、操作はすべてのフィールドに適用されます（すべてのフィールドのフィールドマスクが指定されたかのように）。スキーマの進化がある場合、これはクライアントが知らず、したがってリクエストに記入していないフィールドがデフォルトにリセットされる可能性があることを意味することに注意してください。これが望ましくない動作である場合、特定のサービスはクライアントに常にフィールドマスクの指定を要求し、指定がない場合はエラーを生成することがあります。

get 操作と同様に、リクエストメッセージ内の更新された値を記述するリソースの場所は、操作の種類によって異なります。いずれの場合でも、フィールドマスクの効果は API によって尊重される必要があります。

HTTP REST に関する考慮事項

フィールドマスクを使用する更新操作の HTTP 種別は、HTTP セマンティクスを満たすために PUT ではなく PATCH に設定する必要があります（PUT は完全な更新にのみ使用されるべきです）。

フィールドマスクの JSON エンコーディング

JSON では、フィールドマスクはパスがカンマで区切られた単一の文字列としてエンコードされます。各パスのフィールド名は、ローワーキャメル命名規則との間で変換されます。

例として、以下のメッセージ宣言を考えます。

message Profile {
  User user = 1;
  Photo photo = 2;
}
message User {
  string display_name = 1;
  string address = 2;
}

proto では、Profile のフィールドマスクは次のようになります。

mask {
  paths: "user.display_name"
  paths: "photo"
}

JSON では、同じマスクは以下のように表現されます。

{
  mask: "user.displayName,photo"
}

FloatValue

float のラッパーメッセージ。

FloatValue の JSON 表現は JSON 数値です。

Int32Value

int32 のラッパーメッセージ。

Int32Value の JSON 表現は JSON 数値です。

Int64Value

int64 のラッパーメッセージ。

Int64Value の JSON 表現は JSON 文字列です。

ListValue

ListValue は、値の repeated フィールドのラッパーです。

ListValue の JSON 表現は JSON 配列です。

Method

Method は API のメソッドを表します。

Mixin

この API に含める API を宣言します。インクルードする API は、インクルードされた API のすべてのメソッドを再宣言する必要がありますが、ドキュメントとオプションは次のように継承されます。

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

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

• http アノテーションが継承される場合、パスパターンは次のように変更されます。任意のバージョンプレフィックスは、インクルードする API のバージョンと、指定されていれば 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";
  }
  ...
}

NullValue

NullValue は、Value 型ユニオンの null 値を表すためのシングルトン列挙です。

NullValue の JSON 表現は JSON の null です。

Option

メッセージ、フィールド、列挙などに添付できる protocol buffer オプション。

SourceContext

SourceContext は、protobuf 要素のソースに関する情報、例えばそれが定義されているファイルなどを表します。

StringValue

string のラッパーメッセージ。

StringValue の JSON 表現は JSON 文字列です。

Struct

Struct は、動的に型付けされた値にマッピングされるフィールドで構成される、構造化されたデータ値を表します。一部の言語では、Struct はネイティブ表現でサポートされる場合があります。例えば、JS のようなスクリプト言語では、struct はオブジェクトとして表されます。その表現の詳細は、その言語の proto サポートとともに記述されます。

Struct の JSON 表現は JSON オブジェクトです。

Syntax

protocol buffer 要素が定義されている構文。

Timestamp

Timestamp は、タイムゾーンやカレンダーに依存しない時点を表し、UTC エポック時間における秒とナノ秒解像度の秒の小数部として表現されます。グレゴリオ暦を西暦1年まで遡って拡張した先発グレゴリオ暦を使用してエンコードされます。すべての分が60秒であると仮定してエンコードされるため、解釈にうるう秒のテーブルは必要ありません（うるう秒は「ならされ」ます）。範囲は 0001-01-01T00:00:00Z から 9999-12-31T23:59:59.999999999Z までです。この範囲に制限することで、RFC 3339 の日付文字列との相互変換を保証します。https://www.ietf.org/rfc/rfc3339.txt を参照してください。

Timestamp 型は、RFC 3339 形式の文字列「{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z」としてエンコードされます。ここで、{year} は常に4桁で表現され、{month}、{day}、{hour}、{min}、{sec} はそれぞれ2桁にゼロパディングされます。小数秒は最大9桁（つまり、最大1ナノ秒の解像度）まで可能で、オプションです。「Z」サフィックスはタイムゾーン（「UTC」）を示します。タイムゾーンは必須です。proto3 JSON シリアライザは、Timestamp 型を出力する際に常に UTC（「Z」で示される）を使用すべきであり、proto3 JSON パーサーは UTC と他のタイムゾーン（オフセットで示される）の両方を受け入れることができるべきです。

例1：POSIX time() から Timestamp を計算します。

Timestamp timestamp;
timestamp.set_seconds(time(NULL));
timestamp.set_nanos(0);

例2：POSIX gettimeofday() から Timestamp を計算します。

struct timeval tv;
gettimeofday(&tv, NULL);

Timestamp timestamp;
timestamp.set_seconds(tv.tv_sec);
timestamp.set_nanos(tv.tv_usec * 1000);

例3：Win32 GetSystemTimeAsFileTime() から Timestamp を計算します。

FILETIME ft;
GetSystemTimeAsFileTime(&ft);
UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;

// A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z
// is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.
Timestamp timestamp;
timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));
timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

例4：Java System.currentTimeMillis() から Timestamp を計算します。

long millis = System.currentTimeMillis();

Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)
    .setNanos((int) ((millis % 1000) * 1000000)).build();

例5：Python の現在時刻から Timestamp を計算します。

now = time.time()
seconds = int(now)
nanos = int((now - seconds) * 10**9)
timestamp = Timestamp(seconds=seconds, nanos=nanos)

Type

protocol buffer メッセージ型。

UInt32Value

uint32 のラッパーメッセージ。

UInt32Value の JSON 表現は JSON 数値です。

UInt64Value

uint64 のラッパーメッセージ。

UInt64Value の JSON 表現は JSON 文字列です。

Value

Value は、null、数値、文字列、ブール値、再帰的な構造体値、または値のリストのいずれかであることができる、動的に型付けされた値を表します。Value の生成者は、そのバリアントのいずれか一つを設定することが期待され、どのバリアントも存在しない場合はエラーを示します。

Value の JSON 表現は JSON 値です。