Protobufのwell-known型（Timestamp, Duration, Any）

Googleのwell-known型

Protocol Buffersにはgoogle.protobufパッケージに一般的に必要なメッセージ型のセットが同梱されています。これらの型は特別なJSONエンコーディングと言語レベルのサポートを持っています。

syntax = "proto3";

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/any.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";
import "google/protobuf/field_mask.proto";

message Event {
  string id = 1;
  string name = 2;

  // Timestamp: 時点を表す
  google.protobuf.Timestamp created_at = 3;
  google.protobuf.Timestamp updated_at = 4;

  // Duration: 期間を表す
  google.protobuf.Duration ttl = 5;

  // ラッパー: nullable スカラー型
  google.protobuf.StringValue description = 6;
  google.protobuf.Int32Value priority = 7;
  google.protobuf.BoolValue is_public = 8;

  // Any: 任意のシリアライズされたメッセージを保持
  google.protobuf.Any payload = 9;

  // Struct: 動的なJSON風構造
  google.protobuf.Struct metadata = 10;

  // FieldMask: 更新するフィールドを指定
  google.protobuf.FieldMask update_mask = 11;
}

型リファレンス

型	JSONマッピング	目的
Timestamp	RFC 3339文字列（"2024-01-15T10:30:00Z"）	時点
Duration	秒文字列（"3.5s"）	期間
Any	@typeフィールド付きオブジェクト	任意のメッセージ型
Struct	JSONオブジェクト	動的/スキーマレスデータ
Value	任意のJSON値	動的な単一値
FieldMask	カンマ区切りパス（"name,email"）	部分更新
StringValue	文字列またはnull	Nullable文字列
Int32Value	数値またはnull	Nullable int32
BoolValue	ブーリアンまたはnull	Nullable boolean

ラッパー型

proto3では、スカラーフィールドは「未設定」と「デフォルト値に設定」を区別できません。ラッパー型はスカラーをメッセージでラップすることでこの問題を解決し、明確なnull状態を持ちます。空文字列と値の不在を区別する必要がある場合はstringの代わりにgoogle.protobuf.StringValueを使用します。

部分更新用のFieldMask

FieldMask型はPATCHスタイルの操作で更新するフィールドを指定します。クライアントは更新データと共にフィールドマスクを送信し、サーバーはリストされたフィールドのみを変更し、他は変更しません。