tq1086的博客

原创 AIP-216 状态

许多API资源都带有“状态”概念：通常指资源在其生命周期中的位置。例如，虚拟机可能处于配置中、可用、关闭中，或者其他几种可能的情况之一。作业或查询可能处于准备运行、运行中、已完成等。

原创 AIP-215 API特定proto

API通常使用API特定proto定义，偶尔依赖通用组件。保持API相互隔离可以避免版本问题和客户端库打包问题。

原创 AIP-214 资源过期

客户经常希望设置某个资源或资源属性不再可用或生效的时间（例如轮转安全密钥）。目前，我们建议客户设定一个具体的“过期时间”，保存在域。然而，如果客户希望设定相对时间偏移量，而非具体的过期时间时，这会增加额外负担。此外，现实中存在“生存时间”（通常缩写为TTL）概念，在使用自动生成的客户端库时，这个域的典型格式（以秒为单位的整数）可能导致较差的用户体验。

原创 AIP-213 通用组件

根据规定，除使用“通用组件”包之外，API必须是独立的。通用组件包是给多个API使用的。如果可以安全在多个API之间共享同一个消息，通用组件可以让客户端更容易API交互。例如关于特定概念的客户端代码只需要编写一次，一个API的应答中的消息可以直接用于另一个API的请求，无需低效的复制。当让这种优势也存在重要的限制和局限性，不应轻易尝试。请注意，即使组件所属领域是通用的，组件也可能是组织特定的。

原创 常见设计系统清单

原创 AIP-211 授权检查

大多数操作，无论读或写，都需要授权：获得执行用户请求的操作的权限。此外，向未授权用户提供了多少信息也非常重要，因为信息泄露也是安全问题。

原创 AIP-210 Unicode

省流在我们的API中，“字符”指的是“Unicode码点”。在API文档（例如API参考文档、博客文章、营销文档、计费说明等）中，“字符”必须定义为Unicode码点。

原创 AIP-203 域行为文档

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

原创 AIP-202 域

类型通过扩展，在基本的名字、类型信息之外，提供了更丰富的域的模式。

原创 AIP-194 自动重发配置

远程过程调用可能失败。此时，调用远程过程的客户端需要知道能否安全的重新执行操作。如果多个API使用统一的错误码，客户端可以妥善处理失败。

原创 AIP-193 错误

有效的错误沟通是设计简单直观API的重要组成部分。返回标准错误应答的服务，让API客户端可以构建集中式通用错误处理逻辑。通用逻辑简化了API客户端应用程序，消除了繁琐的零散错误处理代码的需求。

原创 AIP-192 文档

文档是API设计中最关键的方面之一。API用户无法深入到实现细节去更好地理解API。通常，API界面定义和相关文档是用户仅有的东西。因此文档必须尽量清晰、完整、明确。

原创 AIP-191 文件和目录结构

统一的文件和目录结构，虽然在技术上差别不大，但可以让用户和审查者更容易阅读API界面定义。

原创 AIP-185 API版本管理

本主题描述了Google API使用的版本管理策略。通常这些策略适用于所有由Google管理的服务。

原创 AIP-180 向后兼容

API本质上是同用户的契约，用户经常按照API编写代码，部署到生产服务，期望代码正常工作（除非API另有要求）。因此，了解什么样的变更是向后兼容的，什么样是不向后兼容的，非常重要。

原创 AIP-182 外部软件依赖

某些服务对外部软件有特定类型的依赖：它们允许用户创建的资源，以某种方式运行于或发布了外部软件。以这种方式向用户提供外部软件的服务，最终需要解决这样一个事实：所有这些类型的软件都有发布生命周期，它们当前发布的版本最终都会到达生命周期终点。

原创 AIP-181 稳定级别

虽然不同组织（谷歌或其他组织）拥有不同的产品生命周期，AIP使用以下术语指代API组件稳定性。这些稳定级别大致对应于Google Cloud中的产品发布阶段（alpha、beta、GA），但并不完全相同。谷歌云计算平台在此基础上存在额外的期望和承诺。

原创 AIP-165 按条件删除

有时API需要提供一种机制，按照一些过滤参数删除大量资源，而非提供待删除的各资源名字。这是一个稀有的场景，用于用户一次性删除数千或更多资源的情况。此时，普通的批量删除模式（）笨重低效。

原创 AIP-164 软删除

客户端需要使用软删除和恢复删除功能的原因有很多，一个非常突出的重要原因是：从错误中恢复。支持恢复删除的服务，让用户能够恢复意外删除的资源。

原创 AIP-163 变更验证

有时，用户希望在实际进行更改之前验证预期的更改，以查看结果会是什么。例如，请求在服务器群中配置新服务器将对整个服务器群的规模和成本产生影响，并可能产生意想不到的下游影响。

原创 AIP-162 资源修订

一些API需要保留资源修订历史，用户可以推断资源在历史上的状态。我们使用“修订”（revision）指代特定资源的历史参考，并有意避免使用“版本”（version）一词，后者指的是API整体的版本。

原创 AIP-161 域掩码

在（使用的Update或类似方法）更新资源时，通常需要明确指定哪些域需要更新。服务可以忽略另外的域，即使用户发送了值。定义一种掩码格式，为每个API处理更具体需求的方案虽然吸引人。但考虑到掩码需求不断变化，明智的做法是使用一种结构化语法，可以透明地进行更新，无需等待界面或客户端升级。

原创 AIP-160 过滤

通常在列出资源（使用中定义的List方法或类似方法）时，需要能够过滤集合，只返回用户需要的结果。虽然可以定义独立的结构为每个API处理更精确的过滤需求，但是过滤需求经常变化，明智的做法是使用一个字符串字段，采用非技术人员也能理解的结构化语法。这样可以透明地进行更新，无需等待界面或客户端升级。应为列表过滤器面对的是非技术人员，所以通常会借鉴口语形式，而非代码常用的模式。

原创 AIP-159 跨集合读

有时，用户需要跨集合检索资源，或者在不知道资源所在集合的情况下检索单个资源。

原创 AIP-158 分页

API通常需要提供数据集，最常见的是标准方法。但集合大小往往是不受控制的，会随着时间增长，提高了查找时间和通过网络传输的应答大小。因此对集合进行分页是非常重要的。

原创 AIP-157 部分应答

有时，资源可能很大，或者计算成本很高，API需要让用户选择返回哪些域。

原创 AIP-156 单例资源

虽然单例资源在定义上是单数，但在某些情况下，也可能以复数形式出现。例如，服务支持标准List方法（如本文所描述）。因此最好提前声明单例资源类型的复数形式，以免需要时找不到。

原创 AIP-155 请求标识

有时，由用户提供的唯一请求标识对API是有用的。在很多场景下，例如并行处理时排除重复请求、提供安全的重试、或进行审计时都很有用。请求标识的最重要的目标是提供幂等性保证：允许多次发出同一个请求，而后续调用不会产生任何实际影响。在网络故障时，客户端可以重发请求，服务器可以检测重复的请求，保证请求只被处理一次。

原创 AIP-154 资源时效性验证

在资源上执行某类操作之前，API往往需要确认客户端和服务器一致认定资源当前状态。例如，两个进程并行更新同一个资源可能产生竞态条件，后一个进程可能会“覆盖”前面进程的工作。ETag给出了解决之道。服务器根据资源当前内容发送校验和，当客户端把校验和送回来时，服务器可以确保校验和匹配后处理请求。

原创 AIP-153 导入和导出

许多用户希望能将数据导入API中，或者从API中导出现有数据。这对于企业用户尤为重要，他们时常担心出现供应商锁定。

原创 AWS SDK for Java 1.x 403问题解决方法和原因

使用AWS SDK for Java 1.x访问S3，已经确认文件存在，且具有权限，仍然出现403 Forbidden应答。AWS SDK for Java 1.x版本中，当资源路径。生成的URI变为转义后的路径，而计算签名时使用的路径是未经转义的原始路径。AWS签名机制严格依赖请求的精确路径格式，任何URI的差异（如。在AWS SDK for Java 1.x版本中，当调用。，导致实际请求路径与签名计算的路径不一致，触发。升级到AWS SDK for Java 2.x。，SDK会将双斜杠转义为。

原创 AIP-152 作业

偶尔API会发布需要很长时间才能完成的任务，但一次性的并不适用。例如，一个任务可能需要反复运行，或者配置任务和运行任务需要不同的权限。

原创 AIP-151 耗时操作

有时，API可能需要提供一个消耗大量时间才能完成的方法。如果简单的阻塞客户端，等待任务运行，往往会给用户带来不好的体验；相反，最好给用户提供某种承诺，允许用户稍后检查进度。耗时操作模式大致类似于或：用户获得一个令牌，用来跟踪进度和获取结果。

原创 AIP-149 未设定域的值

在许多消息中，很多域是可选的：用户不需要设定这些域；或者对于输出域，服务可能没有设定这些域。在大多数情况下，将域设定成默认值（例如0）与完全不设定值之间，没有实际区别。但是有时这种区别是有意义的。

原创 AIP-148 标准域

一些概念在任何API集合中都很常用。对于这些概念，使用统一的标准域名字和行为来表达它们，是非常有用的。

原创 AIP-147 敏感域

有时API需要收集敏感信息，例如用于存储的私钥，出于数据敏感性，这些信息在写入后不应被读取。对于这类敏感数据，需要特别考虑在API请求和应答中的表示方法。

原创 AIP-146 泛化域

API中的大多数域，无论是在请求、资源还是自定义应答中，都有具体的类型或模式。这个模式是约定的一部分，开发者依此约定进行编码。然而，偶尔会有一些泛化或多态域，可以符合多种模式，甚至是完全可以是任意形式的。

原创 AIP-145 范围

服务通常需要表示具体值或连续值的范围。这些范围的含义存在诸多差异，也存在许多数据类型：整数、浮点数、时间戳等（在此仅举几例）。根据所讨论范围的类型，范围的预期含义可能存在细微差异。

原创 AIP-144 重复域

在API中表示数据列表比看起来要复杂。用户常常需要原地修改列表，如果单个资源中存在较长数据序列，将对分页带来困难。

原创 AIP-143 标准代号

许多常见的概念，如语言、国家、货币等，都有用于数据通信和处理的通用代号（通常由正式定义）。这些代号解决了在书面语言中，同一概念往往存在多种表达方式的问题（如“United States”和“USA”、“Español”和“Spanish”）。