索引
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 |
网址/资源名称,其内容描述序列化消息的类型。 对于使用架构
除 |
value |
bytes |
必须是上述指定类型的有效序列化数据。 |
API
API 是协议缓冲区服务的轻量级描述符。
字段名称 | 类型 | 说明 |
---|---|---|
name |
string |
此 API 的完全限定名称,包括软件包名称后跟此 API 的简单名称。 |
methods |
|
此 API 的方法(未指定顺序)。 |
options |
|
任何附加到 API 的元数据。 |
version |
string |
此 API 的版本字符串。如果指定,则必须采用 版本控制架构使用语义版本控制,其中主要版本号表示重大更改,次要版本则表示新增非重大更改。这两个版本号都是信号,可以让用户了解不同版本的预期,应根据产品计划谨慎选择。 主要版本还会体现在 API 的软件包名称中,该名称必须以 |
source_context |
|
此消息表示的协议缓冲区服务的来源上下文。 |
mixins |
|
包含的 API。请参阅Mixin 。 |
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(含)和 +999999999(含)之间。 |
空
您可以重复使用的通用空消息,以避免在 API 中定义重复的空消息。一个典型的示例是将其用作 API 方法的请求或响应类型。例如:
service Foo {
rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
}
Empty
的 JSON 表示法为空 JSON 对象 {}
。
枚举
枚举类型定义。
字段名称 | 类型 | 说明 |
---|---|---|
name |
string |
枚举类型名称。 |
enumvalue |
|
枚举值定义。 |
options |
|
协议缓冲区选项。 |
source_context |
|
来源上下文。 |
syntax |
|
源语法。 |
EnumValue
枚举值定义。
字段名称 | 类型 | 说明 |
---|---|---|
name |
string |
枚举值名称。 |
number |
int32 |
枚举值编号。 |
options |
|
协议缓冲区选项。 |
字段
消息类型的单个字段。
字段名称 | 类型 | 说明 |
---|---|---|
kind |
|
字段类型。 |
cardinality |
|
字段基数。 |
number |
int32 |
字段编号。 |
name |
string |
字段名称。 |
type_url |
string |
消息或枚举类型的字段类型网址(不含架构)。示例:"type.googleapis.com/google.protobuf.Timestamp" 。 |
oneof_index |
int32 |
Type.oneofs 中用于消息或枚举的字段类型的索引。第一种类型的索引为 1,零表示该类型不在列表中。 |
packed |
bool |
是否使用替代打包的导线表示法。 |
options |
|
协议缓冲区选项。 |
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 |
|
动态类型值的重复字段。 |
方法
method 表示 API 的方法。
字段名称 | 类型 | 说明 |
---|---|---|
name |
string |
此方法的简单名称。 |
request_type_url |
string |
输入消息类型的网址。 |
request_streaming |
bool |
如果为 true,则会流式传输请求。 |
response_type_url |
string |
输出消息类型的网址。 |
response_streaming |
bool |
如果为 true,则会流式传输响应。 |
options |
|
附加到方法的任何元数据。 |
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 |
|
选项的值。例如,"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, |
动态类型值的映射。 |
语法
协议缓冲区元素的定义语法。
枚举值 | 说明 |
---|---|
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 |
|
字段列表。 |
oneofs |
string |
此类型的 oneof 定义中显示的类型列表。 |
options |
|
协议缓冲区选项。 |
source_context |
|
来源上下文。 |
syntax |
|
源语法。 |
UInt32Value
uint32
的封装容器消息。
UInt32Value
的 JSON 表示法为 JSON 数字。
字段名称 | 类型 | 说明 |
---|---|---|
value |
uint32 |
uint32 值。 |
UInt64Value
uint64
的封装容器消息。
UInt64Value
的 JSON 表示法为 JSON 字符串。
字段名称 | 类型 | 说明 |
---|---|---|
value |
uint64 |
uint64 值。 |
值
Value
表示动态类型的值,可以是 null、数字、字符串、布尔值、递归结构值或值列表。值的提供方应设置一个变体,如果缺少任何变体,则表示存在错误。
Value
的 JSON 表示法为 JSON 值。
字段名称 | 类型 | 说明 |
---|---|---|
联合字段,只能是下列其中一项: | ||
null_value |
|
表示 null 值。 |
number_value |
double |
表示双精度值。请注意,尝试序列化 NaN 或 Infinity 会导致错误。(我们无法像对常规字段那样将这些值序列化为字符串“NaN”或“Infinity”值,因为它们将解析为 string_value 而不是 number_value)。 |
string_value |
string |
表示字符串值。 |
bool_value |
bool |
表示布尔值。 |
struct_value |
|
表示结构化值。 |
list_value |
|
表示重复的 Value 。 |