Protocol Buffers Well-Known Types

索引

• Any (メッセージ)
• Api (メッセージ)
• BoolValue (メッセージ)
• BytesValue (メッセージ)
• DoubleValue (メッセージ)
• Duration (メッセージ)
• Empty (メッセージ)
• Enum (メッセージ)
• EnumValue (メッセージ)
• Field (メッセージ)
• Field.Cardinality (列挙型)
• Field.Kind (列挙型)
• FieldMask (メッセージ)
• FloatValue (メッセージ)
• Int32Value (メッセージ)
• Int64Value (メッセージ)
• ListValue (メッセージ)
• Method (メッセージ)
• Mixin (メッセージ)
• NullValue (列挙型)
• Option (メッセージ)
• SourceContext (メッセージ)
• StringValue (メッセージ)
• Struct (メッセージ)
• Syntax (列挙型)
• Timestamp (メッセージ)
• Type (メッセージ)
• UInt32Value (メッセージ)
• UInt64Value (メッセージ)
• Value (メッセージ)

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

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

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

• 新しいメッセージの場合、通常の明示的な存在フィールド（proto2/proto3 では optional、2023 以降のエディションでは通常のフィールド）を使用する方が良いでしょう。
• Any フィールドよりも拡張機能の方が一般的に優れた選択肢です。

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 は、プロトコルバッファサービスのための軽量なディスクリプタです。

BoolValue

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

BoolValue の JSON 表現は JSON true および false です。

BytesValue

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

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

DoubleValue

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

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

Duration

Duration は、秒数とナノ秒分解能での秒の端数として表される、符号付きの固定長の時間スパンを表します。カレンダーや「日」や「月」のような概念とは独立しています。Timestamp とは、2つの Timestamp 値の差が Duration であり、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

列挙型定義

EnumValue

列挙値の定義。

Field

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

Cardinality

フィールドがオプション、必須、または繰り返しであるかどうか。

Kind

基本フィールド型。

FieldMask

FieldMask は、例えば次のような記号的なフィールドパスのセットを表します。

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

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

フィールドマスクは、get 操作によって返されるべきフィールドのサブセット（*プロジェクション*）や、更新操作によって変更されるフィールドのサブセットを指定するために使用されます。フィールドマスクには、カスタムの 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
  }
}

繰り返しフィールドは、フィールドマスクの最後の位置を除いて許可されません。

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

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

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

更新操作におけるフィールドマスクは、ターゲットリソースのどのフィールドが更新されるかを指定します。API は、マスクで指定されたフィールドの値のみを変更し、他のフィールドは変更しないことが求められます。更新された値を記述するためにリソースが渡された場合、API はマスクでカバーされていないすべてのフィールドの値を無視します。

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

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

取得操作と同様に、リクエストメッセージ内の更新された値を記述するリソースの場所は、操作の種類によって異なります。いずれの場合でも、フィールドマスクの効果は 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 は、値の繰り返しフィールドをラップしたものです。

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 型共用体のヌル値を表すためのシングルトン列挙です。

NullValue の JSON 表現は JSON null です。

Option

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

SourceContext

SourceContext は、定義されているファイルのように、protobuf 要素のソースに関する情報を表します。

StringValue

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

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

Struct

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

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

Syntax

プロトコルバッファ要素が定義されている構文。

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

プロトコルバッファメッセージ型。

UInt32Value

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

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

UInt64Value

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

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

Value

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

Value の JSON 表現は JSON 値です。