Package google.protobuf

索引

• 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（消息）

不限

Any 包含任意序列化消息，以及描述序列化消息类型的网址。

JSON

Any 值的 JSON 表示法使用反序列化的嵌入消息的常规表示法，并带有包含类型网址的额外字段 @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"
}

字段名称	类型	说明
type_url	string	网址/资源名称，其内容描述序列化消息的类型。 对于使用架构 http、https 或不使用架构的网址，需遵守以下限制和解释： 如果未提供架构，则假定为 https。 网址路径的最后一部分必须表示类型的完全限定名称（如 path/google.protobuf.Duration 中所示）。 网址上的 HTTP GET 必须生成二进制格式的 google.protobuf.Type 值，或产生错误。 应用可以根据网址缓存查询结果，也可以将它们预编译为二进制文件，以避免查询。因此，更改类型时需要保留二进制文件的兼容性。（使用版本化名称管理破坏性更改。） 除 http、https（或空架构）以外的架构可用于实现专用语义。
value	bytes	必须是上述指定类型的有效序列化数据。

API

API 是协议缓冲区服务的轻量级描述符。

字段名称	类型	说明
name	string	此 API 的完全限定名称，包括软件包名称后跟此 API 的简单名称。
methods	Method	此 API 的方法（未指定顺序）。
options	Option	任何附加到 API 的元数据。
version	string	此 API 的版本字符串。如果指定，则必须采用 major-version.minor-version 格式，例如 1.10。如果省略次要版本，则默认为零。如果整个版本字段为空，则主要版本衍生自软件包名称，如下所述。如果该字段不为空，系统会验证软件包名称中的版本，以便与此处提供的版本保持一致。 版本控制架构使用语义版本控制，其中主要版本号表示重大更改，次要版本则表示新增非重大更改。这两个版本号都是信号，可以让用户了解不同版本的预期，应根据产品计划谨慎选择。 主要版本还会体现在 API 的软件包名称中，该名称必须以 v<major-version> 结尾（例如 google.feature.v1）。对于主要版本 0 和 1，可以省略后缀。零主要版本只能用于实验性非 GA API。
source_context	SourceContext	此消息表示的协议缓冲区服务的来源上下文。
mixins	Mixin	包含的 API。请参阅Mixin。
syntax	Syntax	服务的来源语法。

BoolValue

bool 的封装容器消息。

BoolValue 的 JSON 表示法为 JSON true 和 false。

字段名称	类型	说明
value	bool	布尔值。

BytesValue

bytes 的封装容器消息。

BytesValue 的 JSON 表示法为 JSON 字符串。

字段名称	类型	说明
value	bytes	字节值。

DoubleValue

double 的封装容器消息。

DoubleValue 的 JSON 表示法为 JSON 数字。

字段名称	类型	说明
value	double	双精度值。

时长

Duration 表示一个有符号的固定时间跨度，以纳秒精度表示的秒数和秒数部分表示。独立于任何日历和概念，例如“天”或“月”。这与时间戳有关，因为两个时间戳值之间的差异是一个时长，可以在时间戳上加减。范围大约为 +-10,000 年。

示例 1：计算时间基于伪代码中的两个时间戳。

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 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，表示秒数，前面是秒数，以纳秒表示。

字段名称	类型	说明
seconds	int64	相应时间跨度的秒数。必须介于 -315,576,000,000 到 +315,576,000,000（含）之间。
nanos	int32	秒的有符号小数部分（以纳秒为单位）。时长不到 1 秒表示为 0 seconds 字段，以及正或负 nanos 字段。时长不少于 1 秒时，nanos 字段的非零值必须与 seconds 字段的符号相同。必须介于 -999999999（含）和 [phone]（含）之间。

空

您可以重复使用的通用空消息，以避免在 API 中定义重复的空消息。一个典型的示例是将其用作 API 方法的请求或响应类型。例如：

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

Empty 的 JSON 表示法为空 JSON 对象 {}。

枚举

枚举类型定义。

字段名称	类型	说明
name	string	枚举类型名称。
enumvalue	EnumValue	枚举值定义。
options	Option	协议缓冲区选项。
source_context	SourceContext	来源上下文。
syntax	Syntax	源语法。

EnumValue

枚举值定义。

字段名称	类型	说明
name	string	枚举值名称。
number	int32	枚举值编号。
options	Option	协议缓冲区选项。

字段

消息类型的单个字段。

字段名称	类型	说明
kind	Kind	字段类型。
cardinality	Cardinality	字段基数。
number	int32	字段编号。
name	string	字段名称。
type_url	string	消息或枚举类型的字段类型网址（不含架构）。示例："type.googleapis.com/google.protobuf.Timestamp"。
oneof_index	int32	Type.oneofs 中用于消息或枚举的字段类型的索引。第一种类型的索引为 1，零表示该类型不在列表中。
packed	bool	是否使用替代打包的导线表示法。
options	Option	协议缓冲区选项。
json_name	string	字段 JSON 名称。
default_value	string	此字段默认值的字符串值。仅适用于 Proto2 语法。

基数

字段是否可选、必需或重复。

枚举值	说明
CARDINALITY_UNKNOWN	适用于基数未知的字段。
CARDINALITY_OPTIONAL	对于选填字段。
CARDINALITY_REQUIRED	对于必填字段。仅适用于 Proto2 语法。
CARDINALITY_REPEATED	适用于重复字段。

种类

基本字段类型。

枚举值	说明
TYPE_UNKNOWN	字段类型未知。
TYPE_DOUBLE	字段类型双精度。
TYPE_FLOAT	字段类型浮点数。
TYPE_INT64	字段类型：int64。
TYPE_UINT64	字段类型：uint64。
TYPE_INT32	字段类型：int32。
TYPE_FIXED64	修复了字段类型 64。
TYPE_FIXED32	修复了字段类型 32。
TYPE_BOOL	字段类型布尔值。
TYPE_STRING	字段类型字符串。
TYPE_GROUP	字段类型组。仅限 Proto2 语法，现已弃用。
TYPE_MESSAGE	字段类型消息。
TYPE_BYTES	字段类型字节数。
TYPE_UINT32	字段类型：uint32。
TYPE_ENUM	字段类型枚举。
TYPE_SFIXED32	字段类型 sFix32。
TYPE_SFIXED64	字段类型 sFix64。
TYPE_SINT32	字段类型 sint32.
TYPE_SINT64	字段类型 sint64。

FieldMask

FieldMask 表示一组符号字段路径，例如：

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

此处 f 表示某些根消息中的字段，f 中的消息中的 a 和 b 字段，以及 f.b 中的消息中的 d 字段。

字段掩码用于指定应由 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 类型的更新操作必须设置为 PATCH 而不是 PUT，以满足 HTTP 语义（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"
}

字段名称	类型	说明
paths	string	字段掩码路径集。

FloatValue

float 的封装容器消息。

FloatValue 的 JSON 表示法为 JSON 数字。

字段名称	类型	说明
value	float	浮点值。

Int32Value

int32 的封装容器消息。

Int32Value 的 JSON 表示法为 JSON 数字。

字段名称	类型	说明
value	int32	int32 值。

Int64Value

int64 的封装容器消息。

Int64Value 的 JSON 表示法为 JSON 字符串。

字段名称	类型	说明
value	int64	int64 值。

ListValue

ListValue 是重复值字段的封装容器。

ListValue 的 JSON 表示法为 JSON 数组。

字段名称	类型	说明
values	Value	动态类型值的重复字段。

方法

method 表示 API 的方法。

字段名称	类型	说明
name	string	此方法的简单名称。
request_type_url	string	输入消息类型的网址。
request_streaming	bool	如果为 true，则会流式传输请求。
response_type_url	string	输出消息类型的网址。
response_streaming	bool	如果为 true，则会流式传输响应。
options	Option	附加到方法的任何元数据。
syntax	Syntax	此方法的源语法。

Mixin

声明要添加到此 API 中的 API。包含的 API 必须重新声明包含的 API 中的所有方法，但是文档和选项的继承方式如下：

• 如果注释和空格去除后，重新声明的方法的文档字符串为空，它将从原始方法继承。

• 属于服务配置（http、可见性）但未在重新声明的方法中设置的每个注解都将继承。

• 如果继承了 http 注释，则路径模式将修改如下。任何版本前缀都将替换为包含 API 的版本加上 root 路径（如果已指定）。

简单混音的示例：

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=**}";
  }
}

混合配置示例：

apis:
- name: google.storage.v2.Storage
  mixins:
  - name: google.acl.v1.AccessControl

混合混用结构意味着，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";
  }
  ...
}

字段名称	类型	说明
name	string	包含的 API 的完全限定名称。
root	string	如果为非空，则指定所继承的 HTTP 路径的 root 路径。

NullValue

NullValue 是表示 Value 类型联合的 null 值的单例枚举。

NullValue 的 JSON 表示法为 JSON null。

枚举值	说明
NULL_VALUE	Null 值。

选项

协议缓冲区选项，可以附加到消息、字段、枚举等。

字段名称	类型	说明
name	string	选项的名称。例如，"java_package"。
value	Any	选项的值。例如，"com.google.protobuf"。

SourceContext

SourceContext 表示 protobuf 元素来源的相关信息，例如定义该元素的文件。

字段名称	类型	说明
file_name	string	包含相关 protobuf 元素的 .proto 文件的路径限定名称。例如："google/protobuf/source.proto"。

StringValue

string 的封装容器消息。

StringValue 的 JSON 表示法为 JSON 字符串。

字段名称	类型	说明
value	string	字符串值。

结构体

Struct 表示结构化数据值，其中包含映射到动态类型值的字段。对于某些语言，原生表示法可能支持 Struct。例如，在 JS 等脚本语言中，结构体表示为一个对象。该表示形式的详细信息与针对语言的 proto 支持一起描述。

Struct 的 JSON 表示法是 JSON 对象。

字段名称	类型	说明
fields	map<string, Value>	动态类型值的映射。

语法

协议缓冲区元素的定义语法。

枚举值	说明
SYNTAX_PROTO2	语法 proto2。
SYNTAX_PROTO3	语法 proto3。

时间戳

时间戳表示与任何时区或日历无关的时间点，以世界协调时间 (UTC) 的秒数和秒数的小数部分（以纳秒为单位）表示。它使用前公历进行编码，该历法将公历向前延伸到第一年。其编码假设每分钟的时长均为 60 秒，即闰秒经过均匀分布处理，因此不需要使用闰秒表进行解释。其范围从 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59.999999999Z。通过限制到该范围，我们可以确保时间戳能够与 RFC 3339 日期字符串进行转换。请参阅 https://www.ietf.org/rfc/rfc3339.txt。

示例 1：计算 POSIX time() 中的时间戳。

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

示例 2：计算 POSIX gettimeofday() 中的时间戳。

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

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

示例 3：计算 Win32 GetSystemTimeAsFileTime() 中的时间戳。

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() 中的时间戳。

long millis = System.currentTimeMillis();

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

示例 5：计算 Python 中当前时间的时间戳。

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

字段名称	类型	说明
seconds	int64	表示世界协调时间 (UTC) 的秒数（从 Unix 时间 1970-01-01T00:00:00Z 开始算起）。必须介于 0001-01-01T00:00:00Z 和 9999-12-31T23:59:59Z（含）之间。
nanos	int32	秒的非负分数（纳秒精度）。对于含小数部分的负秒数，仍必须包含按时间递升的非负纳秒值。必须介于 0 到 999999999 之间（含边界值）。

类型

协议缓冲区消息类型。

字段名称	类型	说明
name	string	完全限定的消息名称。
fields	Field	字段列表。
oneofs	string	此类型的 oneof 定义中显示的类型列表。
options	Option	协议缓冲区选项。
source_context	SourceContext	来源上下文。
syntax	Syntax	源语法。

UInt32Value

uint32 的封装容器消息。

UInt32Value 的 JSON 表示法为 JSON 数字。

字段名称	类型	说明
value	uint32	uint32 值。

UInt64Value

uint64 的封装容器消息。

UInt64Value 的 JSON 表示法为 JSON 字符串。

字段名称	类型	说明
value	uint64	uint64 值。

值

Value 表示动态类型的值，可以是 null、数字、字符串、布尔值、递归结构值或值列表。值的提供方应设置一个变体，如果缺少任何变体，则表示存在错误。

Value 的 JSON 表示法为 JSON 值。

字段名称	类型	说明
联合字段，只能是下列其中一项：
null_value	NullValue	表示 null 值。
number_value	double	表示双精度值。请注意，尝试序列化 NaN 或 Infinity 会导致错误。（我们无法像对常规字段那样将这些值序列化为字符串“NaN”或“Infinity”值，因为它们将解析为 string_value 而不是 number_value）。
string_value	string	表示字符串值。
bool_value	bool	表示布尔值。
struct_value	Struct	表示结构化值。
list_value	ListValue	表示重复的 Value。