tommwq.work/aip

AIP-2510

· [tommwq@126.com]

```org

项目标识符

历史上，Google有两种类型的项目：API项目和应用引擎项目。API项目使用项目编号（例如`12345`）作为标识符，而应用引擎项目使用项目ID（例如`happy-armadillo-789`）作为标识符。后来，Google将API项目和应用引擎项目合并，因此现在每个项目都有_两个_唯一且不可变的标识符。

这两种标识符在不同的上下文中使用方式不同，给应用程序开发带来了很多复杂性。一个关键问题是，应用程序无法可靠地连接来自不同服务的数据，因为不同的服务使用不同的项目标识符。

指导原则

TL;DR: 项目编号是规范标识符，项目ID是[别名][]；然而，与普通别名不同，如果用户发送的是项目ID，则**应该**返回项目ID。此外，第三方服务无法_接受_项目ID。

这样做的理由是：

  • 每个资源应该始终有一个规范标识符。
  • 由于Google的隐私政策限制项目ID的使用，无论是在内部还是与合作伙伴之间，只有项目编号才能作为规范标识符。
  • 然而，即使项目编号是规范标识符，如果用户发送的是项目ID，返回项目编号的策略已被证明对人和声明式工具都不友好。

Google API

面向外部的Google API **应该**接受项目ID和项目编号作为传入API请求。

然而，即使项目编号是AIP-122中描述的规范标识符，服务**应该**返回用户发送的ID。这样做的原因是，自动在用户友好的项目ID和用户不友好的项目编号之间进行转换已被证明给用户和声明式工具带来了实际困难（有关声明式友好性的更多信息，请参见AIP-128）。

另外两点：

  • 错误响应**必须**返回原始提供的值，不做任何修改。错误响应**不得**在项目ID和项目编号之间进行任何转换。
  • 如果服务接收到不属于它的资源的资源名称，它**不应该**对这些资源名称进行项目ID和项目编号之间的任何转换。

内部Google服务

内部Google服务**必须**使用项目编号进行内部数据存储和输出。项目标识符广泛用作存储键，通常出现在日志和指标中。项目ID是用户可设置的，因此被视为PII和用户数据，但项目编号不是。

因此，当内部服务调用外部Google API时，它**应该**使用项目编号进行API请求。

资源引用

项目标识符也出现在[资源名称][]中。这些资源名称既用于标识资源本身，也可以引用其他资源（[示例][]）。

当提供项目标识符时，响应**应该**包括请求中出现的标识符：如果提供了项目ID，则应返回项目ID；如果提供了项目编号，则应在响应中包含项目编号。

例如，考虑一个`Book`资源，

```proto message Book { option (google.api.resource) = { type: “pubsub.googleapis.com/Book” pattern: “projects/{project}/books/{book}” };

// 书的资源名称。 string name = 1 [(google.api.field_behavior) = IDENTIFIER];

// 对另一个资源的引用，一个书架。 string shelf = 2 [(google.api.resource_reference) = { type: “library.googleapis.com/Shelf” }];

// 其他字段… } ```

以及从之前的创建请求中提交的以下书籍（在此示例中以JSON表示），

```json { “name”: “projects/my-project/books/les-miserables”, “shelf”: “projects/12345/shelves/top-shelf” } ```

和一个`GetBookRequest`，

```proto message GetBookRequest { / 要检索的书的名称。 / 格式：projects/{project}/books/{book} string name = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { type: “library.googleapis.com/Book” }]; } ```

如果此类请求的`name`值为，

``` projects/my-project/books/les-miserables ```

那么返回的`Book`的`name`字段的值**应该**匹配：应返回项目ID而不是项目编号。但是，`shelf`字段的值应使用项目编号，因为创建请求提交的书架在资源名称中使用了项目编号。

换句话说，应返回以下值：

``` book: projects/my-project/books/les-miserables shelf: projects/12345/shelves/top-shelf ```

此指导原则是为了确保用户输入和输出之间的差异最小。

第三方服务

与Google Cloud Platform集成的第三方服务 **必须**仅存储或提供项目编号。Google的隐私政策禁止与第三方服务共享项目ID，或提供在运行时在项目ID和项目编号之间进行转换的服务。

项目标识符格式

服务**必须**使用[资源管理器API][]定义的项目资源名称来引用项目，例如`projects/123456`。这使得相同的API可以与其他类似项目的资源（如组织和文件夹）一起工作。

变更日志

  • 2022-10-19: 澄清了资源引用中项目标识符的指导原则。
  • 2021-07-29: 反转了之前关于返回项目ID的指导原则；此AIP现在主张返回用户发送的内容。
  • 2019-08-11: 添加了服务不拥有的资源的例外情况。
  • 2019-06-19: 澄清了如何处理错误消息
  • 2019-06-10: 轻微的语言和组织调整

```