本文档介绍如何关联 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 架构,请密切关注联合的编码规则。如果与主题关联的架构有修订版本,则消息必须与 根据可用范围内的修订版本进行编码和验证。 如果未验证,消息将无法发布。
修订版本按时间逆序进行尝试,时间顺序取决于 创建时间。如需创建架构修订版本,请参阅 提交架构修订版本。
消息架构的验证逻辑
将架构与主题相关联且架构有修订版本时, 您可以指定要使用的修订版本的子集范围如果不指定 范围,则使用整个范围进行验证。
如果您没有将某个修订版本指定为允许的第一个修订版本, 则架构中最早的现有修订版本将用于验证。 如果您未将某个修订版本指定为允许的最后一个修订版本,则: 则使用架构的最新现有修订版本。
我们以附加到主题 T
的架构 S
为例。
架构 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