本文档介绍了如何为 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
您可以向主账号(例如用户、群组、网域或服务账号)授予角色和权限。您可以在一个项目中创建架构,并将其附加到位于其他项目中的主题。确保您对每个项目拥有所需的权限。
将架构与主题相关联的准则
您可以在创建或修改主题时将架构与主题相关联。以下是将架构与主题相关联的准则:
您可以将架构与一个或多个主题相关联。
架构与主题关联后,该主题从发布者收到的每条消息都必须遵循该架构。
将架构与主题相关联时,您还必须指定要发布的消息的编码(
BINARY
或JSON
)。如果将 JSON 与 Avro 架构搭配使用,请仔细注意联合编码规则。如果与主题关联的架构有修订版本,则消息必须与编码匹配,并根据可用范围内的修订版本进行验证。如果未通过验证,消息将无法发布。
系统会按创建时间的倒序尝试修订版本。如需创建架构修订版本,请参阅提交架构修订版本。
消息架构的验证逻辑
将架构与主题相关联时,如果架构有修订版本,您可以指定要使用的修订版本子集范围。如果您未指定范围,则系统会使用整个范围进行验证。
如果您未指定允许的第一个修订版本,则系统会使用架构最早的现有修订版本进行验证。如果您未将某个修订版本指定为允许的上一个修订版本,则系统会使用架构的最新现有修订版本。
我们以架构 S
为例,该架构附加到主题 T
中。
架构 S
具有按顺序创建的修订 ID A
、B
、C
和 D
,其中 A
是第一个或最早的修订版本。所有架构都不相同,也不是现有架构的回滚。
如果您仅将允许的第一个修订版本字段设置为
B
,则系统会拒绝仅符合架构A
的消息,而接受符合架构B
、C
和D
的消息。如果您仅将允许的最后修订版本字段设置为
C
,则系统会接受符合架构A
、B
和C
的消息,并拒绝仅符合架构D
的消息。如果您将允许的第一个修订版本字段设置为
B
,并将允许的最后一个修订版本字段设置为C
,则系统会接受符合架构B
和C
的消息。您还可以将第一个修订版本和最后一个修订版本设置为相同的修订版本 ID。在这种情况下,系统只接受符合该修订版的消息。
在创建主题时创建并关联架构
您可以使用 Google Cloud 控制台、gcloud CLI、Pub/Sub API 或 Cloud 客户端库创建带架构的主题。
控制台
在 Google Cloud 控制台中,前往 Pub/Sub 主题页面。
点击创建主题。
在主题 ID 字段中,输入主题 ID。
如需为主题命名,请参阅准则。
选中使用架构复选框。
保留其余字段的默认设置。
您可以创建架构,也可以使用现有架构。
如果您要创建架构,请按以下步骤操作: `
- 在选择 Pub/Sub 架构部分,选择创建新架构。
系统会在辅助标签页中显示创建架构页面。
请按照创建架构中的步骤操作。
返回创建主题标签页,然后点击刷新。
在选择 Pub/Sub 架构字段中,搜索您的架构。
选择消息编码为 JSON 或二进制。
您刚刚创建的架构具有修订版本 ID。您可以创建其他架构修订版本,如提交架构修订版本中所述。
如果您要关联已创建的架构,请按以下步骤操作:
在选择 Pub/Sub 架构部分,选择一个现有架构。
选择消息编码为 JSON 或二进制。
可选:如果所选架构有修订版本,请针对修订版本范围使用允许的第一个修订版本和允许的最后一个修订版本下拉菜单。
根据您的要求,您可以同时指定这两个字段、只指定其中一个字段,也可以保留默认设置。
保留其余字段的默认设置。
点击创建以保存主题,并将其分配给所选架构。
gcloud
如需创建分配了先前所创建架构的主题,请运行 gcloud pubsub topics create
命令:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
其中:
- TOPIC_ID 是您要创建的主题的 ID。
- ENCODING_TYPE 是根据架构验证过的消息的编码。此值必须设置为
JSON
或BINARY
。 - SCHEMA_ID 是现有架构的 ID。
- FIRST_REVISION_ID 是用于进行验证的最早修订版本的 ID。
- LAST_REVISION_ID 是用于进行验证的最新修订版本的 ID。
--first-revision-id
和 --last-revision-id
是可选的。
您也可以从其他 Google Cloud 项目分配架构:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --schema-project=SCHEMA_PROJECT \ --project=TOPIC_PROJECT
其中:
- SCHEMA_PROJECT 是架构的 Google Cloud 项目的项目 ID。
- TOPIC_PROJECT 是主题的 Google Cloud 项目的项目 ID。
REST
如需创建主题,请使用 projects.topics.create
方法:
请求:
必须使用 Authorization
标头中的访问令牌对请求进行身份验证。如需获取当前应用默认凭据的访问令牌,请运行以下命令:gcloud auth application-default print-access-token
。
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
请求正文:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
其中:
- PROJECT_ID 是项目 ID。
- TOPIC_ID 是主题 ID。
- SCHEMA_NAME 是应该根据其验证发布消息的架构的名称。格式为:
projects/PROJECT_ID/schemas/SCHEMA_ID
。 - ENCODING_TYPE 是根据架构验证过的消息的编码。其必须设置为
JSON
或BINARY
。 - FIRST_REVISION_ID 是要验证的旧版 ID。
- LAST_REVISION_ID 是用于进行验证的最新修订版本的 ID。
firstRevisionId
和 lastRevisionId
是可选的。
回答:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
如果请求中未提供 firstRevisionId
和 lastRevisionId
,则会同时省略这两个值。
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
C#
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C# 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub C# API 参考文档。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
PHP
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 PHP 设置说明进行操作。如需了解详情,请参阅 Pub/Sub PHP API 参考文档。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Ruby
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
修改与主题关联的架构
您可以修改主题以附加架构、移除架构,或更新用于验证消息的修订版本范围。一般来说,如果您计划对所用架构进行更改,可以提交新修订版本,并更新为主题使用的修订版本范围。
您可以使用 Google Cloud 控制台、gcloud CLI、Pub/Sub API 或 Cloud 客户端库修改与主题关联的架构。
控制台
在 Google Cloud 控制台中,前往 Pub/Sub 主题页面。
点击某个主题的主题 ID。
在主题详情页面中,点击修改。
您可以对架构进行以下更改。
更改可能需要几分钟时间才能生效。
如果您想从主题中移除架构,请在修改主题页面中,取消选中使用架构复选框。
如果您想更改架构,请在架构部分中选择架构的名称。
根据需要更新其他字段。
- 如果您想更新修订版本范围,请使用修订版本范围的允许的第一个修订版本和允许的最后一个修订版本下拉菜单。
根据您的要求,您可以同时指定这两个字段、只指定其中一个字段,也可以保留默认设置。
点击更新以保存更改。
gcloud
gcloud pubsub topics update TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_NAME \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
其中:
- TOPIC_ID 是您要创建的主题的 ID。
- ENCODING_TYPE 是根据架构验证过的消息的编码。此值必须设置为
JSON
或BINARY
。 - SCHEMA_NAME 是现有架构的名称。
- FIRST_REVISION_ID 是用于进行验证的最早修订版本的 ID。
- LAST_REVISION_ID 是用于进行验证的最新修订版本的 ID。
--first-revision-id
和 --last-revision-id
是可选的。
REST
如需更新主题,请使用 projects.topics.patch
方法:
请求:
必须使用 Authorization
标头中的访问令牌对请求进行身份验证。如需获取当前应用默认凭据的访问令牌,请运行以下命令:gcloud auth application-default print-access-token
。
PATCH https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
请求正文:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" "update_mask": } }
其中:
- PROJECT_ID 是项目 ID。
- TOPIC_ID 是主题 ID。
- SCHEMA_NAME 是应该根据其验证发布消息的架构的名称。格式为:
projects/PROJECT_ID/schemas/SCHEMA_ID
。 - ENCODING_TYPE 是根据架构验证过的消息的编码。其必须设置为
JSON
或BINARY
。 - FIRST_REVISION_ID 是要验证的旧版 ID。
- LAST_REVISION_ID 是用于进行验证的最新修订版本的 ID。
firstRevisionId
和 lastRevisionId
是可选的。
回答:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
firstRevisionId
和 lastRevisionId
在更新后均未设置。
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
0