Protocol Buffers Well-Known Types

インデックス

• Any (メッセージ)
• Api (メッセージ)
• BoolValue (メッセージ)
• BytesValue (メッセージ)
• DoubleValue (メッセージ)
• Duration (メッセージ)
• Empty (メッセージ)
• Enum (メッセージ)
• EnumValue (メッセージ)
• Field (メッセージ)
• Field.Cardinality (enum)
• Field.Kind (enum)
• FieldMask (メッセージ)
• FloatValue (メッセージ)
• Int32Value (メッセージ)
• Int64Value (メッセージ)
• ListValue (メッセージ)
• Method (メッセージ)
• Mixin (メッセージ)
• NullValue (enum)
• Option (メッセージ)
• SourceContext (メッセージ)
• StringValue (メッセージ)
• Struct (メッセージ)
• Syntax (enum)
• 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>
}

埋め込みメッセージタイプが既知であり、カスタム JSON 表現を持つ場合、その表現はフィールド value を追加して埋め込まれ、@type フィールドに加えてカスタム JSON を保持します。例 (メッセージ 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 は、秒数とナノ秒分解能での秒の小数部として表される、符号付きの固定長の期間を表します。これは、カレンダーや「日」や「月」のような概念とは独立しています。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 操作 (projection) によって返されるフィールドのサブセット、または update 操作によって変更されるフィールドを指定するために使用されます。フィールドマスクには、カスタム JSON エンコーディングもあります (下記参照)。

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

FieldMask が projection を指定する場合、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 の必須動作です。

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

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

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

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

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

HTTP REST の考慮事項

フィールドマスクを使用する update 操作の 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

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

SourceContext

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

StringValue

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

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

Struct

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

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

Syntax

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

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

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

UInt32Value

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

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

UInt64Value

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

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

Value

Value は、null、数値、文字列、ブール値、再帰的な struct 値、または値のリストのいずれかである動的に型付けされた値を表します。値のプロデューサーは、それらのバリアントの 1 つを設定することが期待されており、バリアントがない場合はエラーを示します。

Value の JSON 表現は JSON 値です。