订阅属性

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

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

准备工作

通用订阅属性

创建订阅时，您必须指定多个选项来设置订阅。其中一些属性在所有类型的订阅中是通用的，我们将在下一部分进行讨论。

消息保留时长

消息保留时长选项指定 Pub/Sub 消息发布后保留多长时间。超过消息保留时长后，Pub/Sub 可能会舍弃消息，而不受消息的确认状态的影响。如需在消息保留时长内保留已确认的消息，请参阅重放和舍弃消息。

以下是邮件保留时长选项的值：

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

未确认的消息可能是空闲订阅、备份需求或处理缓慢所致。如果您能够在 24 小时内处理消息，则不会产生额外费用。您可以按以下方式管理这些场景，以避免产生新的费用：

  • 空闲订阅。删除空闲订阅以避免产生订阅消息保留费用。

  • 备份存储空间。如果您要将订阅保留用作备份存储空间，则可以切换到其他存储选项（例如主题消息保留或保留已确认的消息）。主题消息保留功能仅在主题级别存储一次消息，并且在需要时可供所有订阅使用。

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

保留已确认的消息

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

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

有效期

到期时间选项可让您延长订阅的到期时间。

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

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

以下是到期时间选项的值：

  • 默认值 = 31 天
  • 最小值 = 1 天
  • 最大值 = 365 天。

要阻止订阅过期，请将有效期设置为 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 请求，您可以举报疑似滥用行为。

Authentication

启用身份验证。启用后，Pub/Sub 传送到推送端点的消息将包含授权标头，以允许端点对请求进行身份验证。自动身份验证和授权机制适用于与订阅位于同一项目中的 App Engine 标准环境和 Cloud Functions 端点。

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

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

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

  • Google 代管式服务帐号（必需）。

    • 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。

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

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

  • 在 JSON 消息中，DATE、DATETIME、TIME 和 TIMESTAMP 值必须是符合支持的表示法的整数。

  • 在 JSON 消息中，NUMERIC 和 BIGNUMERIC 值必须使用 BigDecimalByteStringEncoder 进行字节编码。

  • 您只能选择以下订阅属性之一：使用主题架构或使用表架构。

如果您未选择使用主题架构或使用表架构选项，请确保 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 表包含下表中介绍的字段。

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

参数
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 订阅会写入新的输出文件。以下是适用的最大字节数值：

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

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

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

在某些情况下，Pub/Sub 可能比文件批处理条件配置的时间更早开始写入新文件。如果订阅接收的消息大于最大字节数值，则文件可能也会超过最大字节数值。

文件格式

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

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

  • Avro：消息以 Apache Avro 二进制文件格式存储。

    如果选择 Avro，您还可以启用写入元数据选项。通过此选项，您可以存储邮件的元数据。

    subscription_name、message_id、publish_time 和属性字段等元数据会写入输出 Avro 对象中的顶级字段，而数据以外的所有其他消息属性（例如 order_key，如果存在）将作为条目添加到属性映射中。

    如果停用写入元数据，则只有消息载荷会写入输出 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" }
  ]
}

后续步骤