Protocol Buffers 既知の型

インデックス

• 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 で終わる既知の型は、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 表現を持つ場合、その表現は @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 つのタイムスタンプから 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: 疑似コードでタイムスタンプ + Duration からタイムスタンプを計算します。

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 のリスト操作の場合、マスクは代わりに返されるリソースリスト内の各個別メッセージに適用されます。REST のカスタムメソッドの場合、他の定義が使用されることがあります。マスクがどこに適用されるかは、API 内での宣言とともに明確に文書化されます。いずれの場合でも、返されるリソースへの影響は、API の必須動作です。

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

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

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

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

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

HTTP REST の考慮事項

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

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

JSON では、フィールドマスクはパスがコンマで区切られた単一の文字列としてエンコードされます。各パス内のフィールド名は、lower-camel 命名規則に変換されます。

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

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 型共用体の 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 の JSON 表現は JSON 値です。