本文档介绍如何提交 Pub/Sub 主题的架构修订版本。
准备工作
- 了解 Pub/Sub 架构的工作原理。
- 创建架构。
所需的角色和权限
如需获取提交架构修订版本和管理架构所需的权限,请让管理员授予您项目的 Pub/Sub Editor (roles/pubsub.editor
) IAM 角色。如需详细了解如何授予角色,请参阅管理访问权限。
此预定义角色包含提交架构修订版本和管理架构所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
如需提交架构修订版本和管理架构,您需要拥有以下权限:
-
创建架构:
pubsub.schemas.create
-
将架构附加到主题:
pubsub.schemas.attach
-
提交架构修订版本:
pubsub.schemas.commit
-
删除架构或架构修订版本:
pubsub.schemas.delete
-
获取架构或架构修订版本:
pubsub.schemas.get
-
列出架构:
pubsub.schemas.list
-
列出架构修订版本:
pubsub.schemas.listRevisions
-
回滚架构:
pubsub.schemas.rollback
-
验证消息:
pubsub.schemas.validate
-
获取架构的 IAM 政策:
pubsub.schemas.getIamPolicy
-
为架构配置 IAM 政策:
pubsub.schemas.setIamPolicy
您可以向主账号(例如用户、群组、网域或服务帐号)授予角色和权限。您可以在一个项目中创建架构,并将其挂接到位于其他项目中的主题。确保您拥有每个项目所需的权限。
修改架构
您可以使用 Google Cloud 控制台、gcloud CLI CLI、Pub/Sub API 或 Cloud 客户端库提交架构修订版本。
以下是提交架构修订版本的一些准则:
您可以在特定限制条件下修改架构:
对于协议缓冲区架构,您可以添加或移除可选字段。您无法添加或删除其他字段。您也不能修改任何现有字段。
对于 Avro 架构,请参阅 Avro 文档,了解架构解析的相关规则。新修订版本必须遵循相应规则,因为它既是读取器架构,又是写入器架构。
一个架构一次最多可以有 20 个修订版本。如果超出限制,请先删除一个架构修订版本,然后再创建另一个架构修订版本。
每个修订版本都有一个与其关联的唯一修订版本 ID。修订版本 ID 是一个自动生成的 8 个字符的 UUID。
更新用于主题验证的架构的修订版本范围或修订版本时,更改可能需要几分钟才能生效。
控制台
如需创建架构修订版本,请按以下步骤操作:
在 Google Cloud 控制台中,前往 Pub/Sub 架构页面。
点击现有架构的架构 ID。
系统会打开该架构的架构详情页面。
点击创建修订版本。
系统随即会打开创建架构修订版本页面。
根据需要进行更改。
例如,对于您在创建架构中创建的 Avro 示例架构,您可以额外添加一个名为
Price
的可选字段,如下所示:{ "type": "record", "name": "Avro", "fields": [ { "name": "ProductName", "type": "string", "default": "" }, { "name": "SKU", "type": "int", "default": 0 }, { "name": "InStock", "type": "boolean", "default": false }, { "name": "Price", "type": "double", "default": "0.0" } ] }
点击验证定义,检查架构定义是否正确。
您还可以验证架构的消息。
点击测试消息以测试示例消息。
在测试消息窗口中,选择一种消息编码。
在消息正文中,输入测试消息。
例如,以下是测试架构的消息示例。 在本例中,选择
JSON
作为消息编码。{"ProductName":"GreenOnions", "SKU":34543, "Price":12, "InStock":true}
点击 Test(测试)。
点击提交以保存架构。
gcloud
gcloud pubsub schemas commit SCHEMA_ID \ --type=SCHEMA_TYPE \ --definition=SCHEMA_DEFINITION
其中:
- SCHEMA_TYPE 是
avro
或protocol-buffer
。 - SCHEMA_DEFINITION 是包含架构定义的
string
,系统会根据所选架构类型设置其格式。
您还可以在 文件中指定架构定义:
gcloud pubsub schemas commit SCHEMA_ID \ --type=SCHEMA_TYPE \ --definition-file=SCHEMA_DEFINITION_FILE
其中:
- SCHEMA_TYPE 是
avro
或protocol-buffer
。 - SCHEMA_DEFINITION_FILE 是包含架构定义的文件的路径
string
,格式根据所选的架构类型设置。
REST
如需提交架构修订版本,请发送如下所示的 POST 请求:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/SCHEMA_ID:commit Authorization: Bearer $(gcloud auth application-default print-access-token) Content-Type: application/json --data @response-body.json
在请求正文中指定以下字段:
{ "definition": SCHEMA_DEFINITION "type": SCHEMA_TYPE "name": SCHEMA_NAME }
其中:
- SCHEMA_TYPE 是
AVRO
或PROTOCOL_BUFFER
。 - SCHEMA_DEFINITION 是包含架构定义的字符串,系统会根据所选架构类型设置其格式。
- SCHEMA_NAME 是现有架构的名称。
响应正文应包含架构资源的 JSON 表示法。例如:
{ "name": SCHEMA_NAME, "type": SCHEMA_TYPE, "definition": SCHEMA_DEFINITION "revisionId": REVISION_ID "revisionCreateTime": REVISION_CREATE_TIME }
其中:
- REVISION_ID 是服务器为修订版本生成的 ID。
- REVISION_CREATE_TIME 是创建修订版本的 ISO 8601 时间戳。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Avro
Proto
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
Avro
Proto
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Avro
Proto
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Avro
Proto
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Avro
Proto
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Avro
Proto
提交架构修订版本后,您可以在架构页面中查看新修订版本的详细信息。