当前位置：首页 > wzjs >正文

wordpress仿百度文库湖南企业竞价优化服务

wzjs 2025/7/31 5:10:16

wordpress仿百度文库,湖南企业竞价优化服务,一个公司可以做几个网站吗,archlinux+wordpress编号203原文链接AIP-203: Field behavior documentation状态批准创建日期2018-07-17更新日期2018-07-17 在定义protocol buffer中的域时，按惯例要向用户解释域行为的某些方面（例如域是必需的还是可选的）。此外，让其他工具理解域行…

编号	203
原文链接	AIP-203: Field behavior documentation
状态	批准
创建日期	2018-07-17
更新日期	2018-07-17

在定义protocol buffer中的域时，按惯例要向用户解释域行为的某些方面（例如域是必需的还是可选的）。此外，让其他工具理解域行为也很有用（例如优化客户端库签名）。

指南

API使用 google.api.field_behavior 注解来描述已知的域行为，例如域是必需或不可变的。

// 待识别语音数据。
RecognitionAudio audio = 2 [(google.api.field_behavior) = REQUIRED];

API 必须在请求使用的消息或子消息的每个域上添加 google.api.field_behavior 注解。
注解必须包含准确描述域行为的所有 google.api.FieldBehavior 值。
- 不得使用 FIELD_BEHAVIOR_UNSPECIFIED 。
API 必须至少使用 REQUIRED 、 OPTIONAL 或 OUTPUT_ONLY 之一。

警告尽管 field_behavior 不会影响协议级别的行为，但许多客户端（例如CLI和SDK）依赖它们生成代码。在添加新域时，请仔细审查并考虑哪些值是相关联的。

为了向后兼容，没有注解的域被认为是 OPTIONAL 。尽管如此，不得省略此注解。

注意本文档中给出的词汇仅用于描述，本身不产生任何校验。目的是为客户端统一记录域行为。

嵌套消息的域行为

嵌套消息上的 google.api.field_behavior 注解与上级消息注解无关。

例如，嵌套消息可以具有 REQUIRED 域行为，而上级域可以是 OPTIONAL ：

message Title {string text = 1 [(google.api.field_behavior) = REQUIRED];
}message Slide {Title title = 1 [(google.api.field_behavior) = OPTIONAL];
}

在上述情况下，如果设定了 title ，则 text 域是必需的。

词汇表

标识符

IDENTIFIER 表示资源消息中的域用于标识资源，必须添加到 name 域，不得添加到任何其他域（参考表示资源名字的域）。

IDENTIFIER 值表示在创建方法的上下文中，域不作为输入域（即 OUTPUT_ONLY ），同时也表示在接受资源作为主要输入的修改方法（如标准更新）中，域作为 IMMUTABLE 不可变输入。

此注解不得用于消息对其他资源的引用。

不可变的

IMMUTABLE 表示域在资源创建后不可改变。这可以应用于输入或输出、必需或可选的域。

如果服务在更新请求（或类似请求）中收到不可变域，如果域包含在更新掩码中，并且新值与现值一致，服务应当忽略域值。但如果请求尝试修改值，服务应当返回 INVALID_ARGUMENT 错误。

不可变域的潜在用例（这不是一个详细列表）包括：

应用程序生命周期内，不可修改的资源属性（例如磁盘类型）。

注意 “某些条件下不可变”的域不得使用不可变注解。

只输入域

INPUT_ONLY 表示域只在请求中出现，不会包含在输出中。

此外，应当只将资源消息或其包含消息中的域注解为只输入域。请注意，请求消息（通常以 Request 结尾、仅作为远程过程调用参数）中的域不应注解为只输入域，它们原本就是。

只输入域的潜在用例（这不是一个详细列表）包括：

AIP-214中描述的 ttl 域。

警告只输入域很少见，应谨慎使用。

可选域

使用 OPTIONAL 表示域不是必需的。

如果域是请求消息（作为远程过程调用参数的消息，通常以 Request 结尾）或其子消息中的域，可以注解为可选的。

只输出域

OUTPUT_ONLY 表示域在应答中提供，而在请求中包含域不会产生任何效果（服务器必须清除输入中此域的任何值，并且不得由于输入中存在此域的值抛出错误）。同样的，服务必须忽略更新域掩码中的只输出域（参考AIP-161）。

此外，应当只将资源消息或其树形结构更下方消息中的域注解为只输出域。请注意，应答消息中的域（通常以 Response 结尾的消息，仅作为远程过程调用的返回值）不应注解为只输出域，它们本来就是。

只输出域可以设置为空值，如果合适。

只输出域的潜在用例（这不是一个详细列表）包括：

创建或更新时间戳。
基于原始用户输入的派生或结构化信息。
由服务分配的无法修改的资源属性。

必需

REQUIRED 表示域必须存在于请求或资源之中（设置为非空值）。

域应当只在以下情况被注解为必需域：

它是用户作为输入提供的某个资源上的域。只有当“真值”被存储后，资源才生效。
- 在创建资源时，*必须* 在创建请求中提供域值。
- 在更新资源时，如果域不在掩码中，用户可以省略域，表示不会修改域（否则必须提供）。
它是请求消息上的域（作为远程过程调用参数的消息，通常以 Request 结尾）。此时必须在请求中提供值，否则服务必须返回错误（通常是 INVALID_ARGUMENT ）。

我们定义上述术语“真值”如下：

对于原始类型，值不为 0 、 0.0 、空字符串/字节和 false 。
对于重复域映射，至少有一个条目。
对于消息，至少包含一个“真值”域。

在表示下列域时，域不应注解为必需域：

始终存在于应答中的域。
在某些条件下必需的域。
从未作为用户输入的消息（包括资源消息）上的域。

注意在大多数情况下，空值（如布尔值 false 、整数 0 或枚举的未指定值）无法与未设定值进行区分，因此将必需域设置为空值会产生错误。由此推论，必需的布尔域必须设置为 true 。

无序列表

在资源的重复域上使用 UNORDERED_LIST 表示服务不保证列表中条目的顺序。

如果服务不保证列表中元素的顺序与用户发送的顺序一致，包括服务将代替用户对列表进行排序的情况，域应当注解为无序列表。

包含无序列表的资源可以按稳定顺序返回列表，也可以按随机的、不稳定的顺序返回列表。

向后兼容性

添加或更改 google.api.field_behavior 值可以表示API中的语义变更，现有客户端可能认为这是不兼容的。以下是 google.api.field_behavior 的不向后兼容变更的示例：

将 REQUIRED 添加到之前被认为是 OPTIONAL （隐式或其他方式）的域
将注解为 REQUIRED 的新域添加到现有请求消息中
将 OUTPUT_ONLY 添加到之前作为输入的域
将 INPUT_ONLY 添加到之前作为输出的域
将 IMMUTABLE 添加到之前被认为是可变的域
从之前作为输入的域中删除 OUTPUT_ONLY
从现有域中删除 IDENTIFIER

一些更改是向后兼容的，如下所示：

将 OPTIONAL 添加到现有域
将 IDENTIFIER 添加到现有的 name 域
将现有域从 REQUIRED 改为 OPTIONAL
将现有域从 OUTPUT_ONLY 或 IMMUTABLE 改为 IDENTIFIER
从现有域中删除 REQUIRED
从之前在应答中排除的域中删除 INPUT_ONLY
从之前被认为是不可变的域中删除 IMMUTABLE

理由

标识符域行为

资源名字是每个合规资源的主要标识符，从未由用户在创建时完整构造。这些域通常被指定为 OUTPUT_ONLY 域行为。然而，在资源本身是主要请求内容的情况下，它们也经常作为主要标识符被消费。因此不能作为 OUTPUT_ONLY 。此外，在变更请求（如标准更新）中，资源名字作为主要标识符，不能就地更改。这些域通常被指定为 IMMUTABLE 域行为。这些冲突，以及上下文相关的域行为，意味着需要一个新值来单独表达资源名域的行为。