订阅属性

Pub/Sub 订阅属性是订阅的特征。您可以在创建或更新订阅时设置订阅属性。

本文档介绍了您可以为订阅设置的不同订阅属性。

准备工作

常见的订阅属性

创建订阅时，您必须指定多个选项才能设置订阅。其中一些属性适用于所有类型的订阅，并在后续部分中加以介绍。

消息保留时长

消息保留时长选项指定 Pub/Sub 在发布后保留消息的时间。超过消息保留时长后，Pub/Sub 可以随意舍弃消息，无论其确认状态为何。如需保留已确认的消息，请参阅重放和舍弃消息。

消息保留时长选项的值如下：

  • 默认值 = 7 天
  • 最小值 = 10 分钟
  • 最大值 = 31 天

未确认的消息可能是由闲置订阅、备份需求或处理速度缓慢所致。如果您能够在 24 小时内处理这些邮件，则不会产生额外费用。您可以通过以下方式管理这些情况，避免产生新的扣款：

  • 闲置订阅。删除闲置的订阅，以免产生订阅消息保留费用。

  • 备份存储空间。如果您将订阅保留功能用作备用存储空间，则可以改用其他存储选项，例如主题消息保留或保留已确认的消息。主题消息保留功能只会在主题级别存储一次消息，这些消息会保留在那里，以便所有订阅在需要时使用。

  • 处理延迟。添加更多订阅者（如果可能），以便在一天内处理消息。

保留已确认的消息

如果您指定了消息保留时长，还可以指定是否要保留已确认的消息。

借助保留已确认的消息选项，您可以将已确认的消息保留指定的消息保留时长。此选项会增加消息存储费用。如需了解详情，请参阅存储费用。

有效期

借助到期期限选项，您可以延长订阅的到期期限。

如果没有任何订阅者活动或对订阅属性所做的更改，订阅会过期。如果 Pub/Sub 检测到订阅者活动，或者您更新了任何订阅属性，则订阅删除时钟会重启。订阅者活动的示例包括打开连接、主动拉取或成功推送。

如果您指定了到期时长，则该值必须长于消息保留时长选项中指定的消息保留时长。

以下是失效期限选项的值：

  • 默认值 = 31 天
  • 最小值 = 1 天

要阻止订阅过期，请将有效期设置为 never expire。

确认截止期限

确认截止期限选项用于指定初始截止期限，系统会在该期限过后重新发送未确认的消息。您可以通过发送后续 ModifyAckDeadline 请求，按消息延长确认期限。

以下是确认截止期限选项的值：

  • 默认值 = 10 秒
  • 最小值 = 10 秒
  • 最大值 = 600 秒

在某些情况下，Pub/Sub 客户端库可以控制传送速率并动态修改确认期限。这样一来，系统可能会在您设置的确认期限之前重新传送消息。如需替换此行为，请使用 minDurationPerAckExtension 和 maxDurationPerAckExtension。如需详细了解如何使用这些值，请参阅客户端库中的恰当一次提交支持。

订阅过滤条件

使用订阅过滤条件选项指定包含过滤表达式的字符串。如果某个订阅具有过滤条件，则该订阅将仅传递与过滤条件匹配的消息。Pub/Sub 服务会自动确认与过滤条件不匹配的消息。

  • 您可以按消息的属性过滤消息，但不能按消息中的数据过滤消息。

  • 如果未指定，则订阅不会过滤消息，并且订阅者会收到所有消息。

  • 过滤条件一经应用便无法更改或移除。

当您收到包含过滤条件的订阅的消息时，您无需为 Pub/Sub 自动确认的消息支付出站流量费用。您需要支付消息传送费用以及跳转相关存储费用。

如需了解详情，请参阅过滤订阅中的消息。

消息排序

当订阅启用了消息排序时，订阅者客户端会按服务收到消息的顺序接收在同一区域发布且具有相同排序键的消息。

使用有序传送时，系统会先处理早期消息的确认，然后再处理后续消息的确认。

发布者必须发送带有排序键的消息，以便 Pub/Sub 按顺序传送消息。

如果未设置，Pub/Sub 可能不会按顺序传送消息，即使消息具有排序键也是如此。

死信主题

如果某条消息在尝试传送指定次数后仍无法传送，或者订阅者无法确认消息，您可以配置一个死信主题，将这些消息重新发布到该主题。

如果设置了死信主题，还可以指定传送尝试次数上限。以下是死信主题的传送尝试次数上限值：

  • 默认值 = 5 次传送尝试
  • 最小值 = 5 次传送尝试
  • 最大值 = 100 次传送尝试

如果死信主题与订阅位于不同项目中，则您还必须指定含有死信主题的项目 ID。

如需了解详情，请参阅转发到死信主题。

重试政策

如果确认截止时间到期或订阅者返回否定确认，则 Pub/Sub 可以重新发送消息。此重新提交尝试称为订阅重试政策。

默认情况下，订阅的重试政策设置为使用立即重试。选择此选项后，Pub/Sub 会在确认截止时间到期或订阅者做出否定确认响应时重新发送消息。

您还可以将该值设置为在按照指数退避算法确定的延迟时间后重试。在这种情况下，您必须指定最大和最小退避值。

以下是设置最大和最小回退值的一些准则：

  • 如果您为退避时长设置了最大值，则最小退避时长的默认值为 10 秒。

  • 如果您为退避时长设置了最小值，则最大退避时长的默认值为 600 秒。

  • 可指定的最长退避时长为 600 秒。

重试政策和批量消息

如果消息采用批处理，则在发生以下任一情况时，Pub/Sub 会启动指数退避算法：

  • 订阅者为批次中的每条消息发送否定确认。

  • 确认截止时间到期。

重试政策和推送订阅

如果收到推送订阅消息，Pub/Sub 可能会在推送退避时限（而非指数退避时限）后传送消息。当推送退避时间超过指数退避时限时，Pub/Sub 会在推送退避后重新提交未确认的消息。

拉取订阅属性

配置拉取订阅时，您可以指定以下属性。

仅传送一次

仅传送一次。如果设置了此属性，Pub/Sub 会实现正好一次传送保证。如果未指定，则订阅支持每条消息的至少一次传送。

推送订阅属性

配置推送订阅时，您可以指定以下属性。

端点

端点网址（必需）。可公开访问的 HTTPS 地址。推送端点的服务器必须具有由证书授权机构签署的有效 SSL 证书。Pub/Sub 服务会将同一 Google Cloud 地区中的消息传送至 Pub/Sub 服务存储消息所在的推送端点。Pub/Sub 服务会尽最大努力传送来自同一 Google Cloud 地区的消息。

Pub/Sub 不再要求证明对推送订阅网址网域的所有权。如果您的网域收到来自 Pub/Sub 的意外 POST 请求，您可以举报疑似滥用行为。

身份验证

启用身份验证。启用后，Pub/Sub 传送到推送端点的消息会包含授权标头，以允许端点对请求进行身份验证。如果 App Engine 标准应用和 Cloud Run 函数端点托管在订阅所属的项目中，则可以使用自动身份验证和授权机制。

经过身份验证的推送订阅的身份验证配置包括一个用户代管式服务账号，以及在 create、patch 或 ModifyPushConfig 调用中指定的受众群体参数。您还必须向服务代理授予特定角色，如下一部分所述。

  • 代管式服务账号（必需）。与推送订阅关联的服务账号。此账号将用作生成的 JSON Web 令牌 (JWT) 的 email 声明。以下是服务账号的要求列表：

  • 观众。一个不区分大小写的字符串，供 Webhook 用于验证此特定令牌的目标受众群体。

  • 服务代理（必需）。

    • Pub/Sub 会自动为您创建一个格式为 service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com 的服务账号。

    • 必须向此服务代理授予 iam.serviceAccounts.getOpenIdToken 权限（包含在 roles/iam.serviceAccountTokenCreator 角色中），才能允许 Pub/Sub 为经过身份验证的推送请求创建 JWT 令牌。

载荷解封

启用载荷解封选项会剥离 Pub/Sub 消息中的所有消息元数据（消息数据除外）。通过载荷展开，消息数据会直接作为 HTTP 正文传送。

  • 写入元数据。将之前移除的消息元数据重新添加到请求标头中。

BigQuery 属性

选择写入 BigQuery 作为订阅提交类型时，您可以指定以下其他属性。

使用主题架构

此选项可让 Pub/Sub 使用订阅附加到的 Pub/Sub 主题的架构。此外，Pub/Sub 会将消息中的字段写入 BigQuery 表中的相应列。

使用此选项时，请务必查看以下其他要求：

  • 主题架构和 BigQuery 架构中的字段必须具有相同的名称，并且它们的类型必须彼此兼容。

  • 主题架构中的任何可选字段在 BigQuery 架构中也必须是可选字段。

  • 主题架构中的必需字段在 BigQuery 架构中不必是必需字段。

  • 如果主题架构中不存在某些 BigQuery 字段，则这些 BigQuery 字段必须采用模式 NULLABLE。

  • 如果主题架构中包含 BigQuery 架构中不存在的其他字段，并且这些字段可以被舍弃，请选择舍弃未知字段选项。

  • 您只能选择其中一个订阅属性，即使用主题架构或使用表架构。

如果您未选择使用主题架构或使用表架构选项，请确保 BigQuery 表中有一个名为 data 且类型为 BYTES、STRING 或 JSON 的列。Pub/Sub 会将消息写入此 BigQuery 列。

您可能不会立即看到对 Pub/Sub 主题架构或 BigQuery 表架构所做的更改生效，因为消息会写入 BigQuery 表。例如，如果舍弃未知字段选项处于启用状态，并且 Pub/Sub 架构中存在某个字段，但 BigQuery 架构中不存在该字段，那么将消息写入 BigQuery 表后，该字段可能仍不会包含在 BigQuery 架构中。最终，架构会同步，后续消息会包含该字段。

为 BigQuery 订阅使用使用主题架构选项时，您还可以利用 BigQuery 变更数据捕获 (CDC)。CDC 通过处理更改并将其应用于现有行来更新 BigQuery 表。

如需详细了解此功能，请参阅使用变更数据捕获来流式插入表更新。

如需了解如何将此功能与 BigQuery 订阅搭配使用，请参阅 BigQuery 变更数据捕获。

使用表架构

通过此选项，Pub/Sub 可以使用 BigQuery 表的架构将 JSON 消息的字段写入相应的列。使用此选项时，请务必查看以下其他要求：

  • 发布的消息必须采用 JSON 格式。

  • 支持以下 JSON 转换：

    JSON 类型 BigQuery 数据类型
    string NUMERIC、BIGNUMERIC、DATE、TIME、DATETIME 或 TIMESTAMP
    number NUMERIC、BIGNUMERIC、DATE、TIME、DATETIME 或 TIMESTAMP
    • 将 number 用于 DATE、DATETIME、TIME 或 TIMESTAMP 转化时，该数字必须遵循受支持的表示法。
    • 使用 number 转换为 NUMERIC 或 BIGNUMERIC 时，值的精度和范围仅限于 IEEE 754 浮点算术标准接受的值。如果您需要高精度或更大的值范围，请改用 string 到 NUMERIC 或 BIGNUMERIC 转换。
    • 使用 string 到 NUMERIC 或 BIGNUMERIC 转换时，Pub/Sub 会假定字符串是人类可读的数字（例如 "123.124"）。如果将字符串作为人类可读的数字进行处理失败，Pub/Sub 会将字符串视为使用 BigDecimalByteStringEncoder 编码的字节。

  • 如果订阅的主题与架构相关联，则消息编码属性必须设置为 JSON。

  • 如果消息中不存在某些 BigQuery 字段，则这些 BigQuery 字段必须采用模式 NULLABLE。

  • 如果消息包含 BigQuery 架构中不存在的其他字段，并且可以丢弃这些字段，请选择丢弃未知字段选项。

  • 您只能选择其中一个订阅属性，即使用主题架构或使用表架构。

如果您未选择使用主题架构或使用表架构选项，请确保 BigQuery 表中有一个名为 data 且类型为 BYTES、STRING 或 JSON 的列。Pub/Sub 会将消息写入此 BigQuery 列。

您可能不会立即看到对 BigQuery 表架构所做的更改生效，因为消息会写入 BigQuery 表。例如，如果舍弃未知字段选项处于启用状态，并且消息中存在某个字段，但该字段不存在于 BigQuery 架构中，那么将该字段添加到 BigQuery 架构后，写入 BigQuery 表的消息可能仍不包含该字段。最终，架构会同步，后续消息会包含该字段。

为 BigQuery 订阅使用使用表架构选项时，您还可以利用 BigQuery 变更数据捕获 (CDC)。CDC 通过处理更改并将其应用于现有行来更新 BigQuery 表。

如需详细了解此功能，请参阅使用变更数据捕获来流式插入表更新。

如需了解如何将此功能与 BigQuery 订阅搭配使用，请参阅 BigQuery 变更数据捕获。

删除未知字段

此选项与使用主题架构或使用表架构选项搭配使用。通过此选项，Pub/Sub 会删除主题架构或消息中存在但 BigQuery 架构中不存在的字段。如果未设置丢弃未知字段，包含额外字段的消息不会写入 BigQuery，而是会保留在订阅积压消息中。订阅最终会处于错误状态。

写入元数据

通过此选项，Pub/Sub 可以将每条消息的元数据写入 BigQuery 表中的其他列。否则，元数据不会写入 BigQuery 表。

如果您选择写入元数据选项，请确保 BigQuery 表包含下表中所述的字段。

如果您未选择写入元数据选项，则目标 BigQuery 表只需要 data 字段，除非 use_topic_schema 为 true。如果您同时选择了写入元数据和使用主题架构选项，则主题的架构不得包含任何名称与元数据参数名称匹配的字段。此限制包括这些蛇形命名参数的驼峰命名版本。

参数
subscription_name

STRING

订阅的名称。
message_id

STRING

消息 ID
publish_time

TIMESTAMP

消息的发布时间。
data

BYTES、STRING 或 JSON

消息正文。

对于未选择使用主题架构或使用表架构的所有目标 BigQuery 表，data 字段都是必需的。如果该字段的类型为 JSON，则消息正文必须为有效的 JSON。
attributes

STRING 或 JSON

一个包含所有消息属性的 JSON 对象。它还包含 Pub/Sub 消息中的其他字段，包括排序键（如果有）。

Cloud Storage 属性

选择写入 Cloud Storage 作为订阅传送类型时，您可以指定以下其他属性。

存储桶名称

您必须先创建 Cloud Storage 存储桶，然后才能创建 Cloud Storage 订阅。

系统会以批量方式发送消息，并将其存储在 Cloud Storage 存储桶中。单个批处理作业或文件会以对象的形式存储在存储桶中。

Cloud Storage 存储桶必须停用请求者付费。

如需创建 Cloud Storage 存储桶，请参阅创建存储分区。

文件名前缀、后缀和日期时间

Cloud Storage 订阅生成的输出 Cloud Storage 文件会作为对象存储在 Cloud Storage 存储桶中。存储在 Cloud Storage 存储桶中的对象的名称采用以下格式：<file-prefix><UTC-date-time>_<uuid><file-suffix>。

以下列表详细介绍了文件格式和可自定义的字段：

  • <file-prefix> 是自定义文件名前缀。这是一个可选字段。

  • <UTC-date-time> 是根据对象创建时间自动生成的可自定义字符串。

  • <uuid> 是系统为对象自动生成的随机字符串。

  • <file-suffix> 是自定义文件名后缀。这是一个可选字段。文件名后缀不能以“/”结尾。

  • 您可以更改文件名前缀和后缀：

    • 例如，如果文件名前缀的值为 prod_，文件名后缀的值为 _archive，则示例对象名称为 prod_2023-09-25T04:10:00+00:00_uN1QuE_archive。

    • 如果您未指定文件名前缀和后缀，则存储在 Cloud Storage 存储桶中的对象名称的格式为：<UTC-date-time>_<uuid>。

    • Cloud Storage 对象命名要求也适用于文件名前缀和后缀。如需了解详情，请参阅 Cloud Storage 对象简介。

  • 您可以更改文件名中日期和时间的显示方式：

    • 必需的日期时间匹配器（只能使用一次）：年份 (YYYY 或 YY)、月份 (MM)、天 (DD)、小时 (hh)、分钟 (mm)、秒 (ss)。例如，YY-YYYY 或 MMM 无效。

    • 可选匹配器（只能使用一次）：日期时间分隔符 (T) 和时区偏移量 (Z 或 +00:00)。

    • 可多次使用的可选元素：连字符 (-)、下划线 (_)、英文冒号 (:) 和正斜杠 (/)。

    • 例如，如果文件名日期时间格式的值为 YYYY-MM-DD/hh_mm_ssZ，则示例对象名称为 prod_2023-09-25/04_10_00Z_uNiQuE_archive。

    • 如果文件名日期时间格式以非匹配字符结尾，则该字符将替换 <UTC-date-time> 和 <uuid> 之间的分隔符。例如，如果文件名日期时间格式的值为 YYYY-MM-DDThh_mm_ss-，则示例对象名称为 prod_2023-09-25T04_10_00-uNiQuE_archive。

文件批处理

借助 Cloud Storage 订阅，您可以决定何时创建要作为对象存储在 Cloud Storage 存储桶中的新输出文件。当满足指定的批处理条件之一时，Pub/Sub 会写入输出文件。以下是 Cloud Storage 批处理条件：

  • 批量存储时长上限。这是必需设置。如果超出指定的时长上限，Cloud Storage 订阅会写入新的输出文件。如果您未指定此值，系统会应用默认值 5 分钟。以下是适用于时长上限的值：

    • 最小值 = 1 分钟
    • 默认值 = 5 分钟
    • 最大值 = 10 分钟

  • 批量存储字节数上限。这是可选设置。如果超出指定的字节数上限，Cloud Storage 订阅会写入新的输出文件。以下是“max_bytes”的适用值：

    • 最小值 = 1 KB
    • 最大值 = 10 GiB

  • 批量存储消息数上限。这是可选设置。如果超出指定的最大消息数，Cloud Storage 订阅会写入新的输出文件。以下是适用于“最大消息数”的值：

    • 最小值 = 1000

例如，您可以将时长上限配置为 6 分钟，并将字节数上限配置为 2 GB。如果在第 4 分钟时，输出文件的大小达到 2 GB，Pub/Sub 会完成上一个文件，并开始写入新文件。

Cloud Storage 订阅可能会同时向 Cloud Storage 存储桶中的多个文件写入数据。如果您已将订阅配置为每 6 分钟创建一个新文件，则可能会发现系统每 6 分钟就会创建多个 Cloud Storage 文件。

在某些情况下，Pub/Sub 可能会在文件批处理条件配置的时间之前开始写入新文件。如果订阅收到的邮件大小超过“Max bytes”值，文件也可能会超出“Max bytes”值。

文件格式

创建 Cloud Storage 订阅时，您可以将要存储在 Cloud Storage 存储桶中的输出文件的格式指定为文本或 Avro。

  • 文本：消息会以纯文本形式存储。换行符用于将消息与文件中的前一则消息分隔开来。系统只会存储消息载荷，而不会存储属性或其他元数据。

  • Avro：消息以 Apache Avro 二进制格式存储。选择 Avro 后，您可以启用以下其他属性：

    • 写入元数据：通过此选项，您可以将消息元数据与消息一起存储。subscription_name、message_id、publish_time 和 attributes 字段等元数据会写入输出 Avro 对象中的顶级字段，而除数据之外的所有其他消息属性（例如 ordering_key，如果有）都会添加为 attributes 映射中的条目。

      如果停用了写入元数据，则系统只会将消息载荷写入输出 Avro 对象。以下是停用写入元数据的输出消息的 Avro 架构：

      {
  "type": "record",
  "namespace": "com.google.pubsub",
  "name": "PubsubMessage",
  "fields": [
    { "name": "data", "type": "bytes" }
  ]
}

      以下是启用了写入元数据的输出消息的 Avro 架构：

      {
  "type": "record",
  "namespace": "com.google.pubsub",
  "name": "PubsubMessageWithMetadata",
  "fields": [
    { "name": "subscription_name", "type": "string" },
    { "name": "message_id", "type": "string"  },
    { "name": "publish_time", "type": {
        "type": "long",
        "logicalType": "timestamp-micros"
      }
    },
    { "name": "attributes", "type": { "type": "map", "values": "string" } },
    { "name": "data", "type": "bytes" }
  ]
}

    • 使用主题架构：此选项可让 Pub/Sub 在写入 Avro 文件时使用订阅附加到的 Pub/Sub 主题的架构。

      使用此选项时，请务必查看以下其他要求：

      • 主题架构必须采用 Apache Avro 格式。

      • 如果同时启用了使用主题架构和写入元数据，则主题架构的根目录下必须有一个 Record 对象。Pub/Sub 会扩展记录的字段列表，以包含元数据字段。因此，记录不得包含与元数据字段（subscription_name、message_id、publish_time 或 attributes）同名的任何字段。

后续步骤