订阅属性

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

本文档介绍了不同的订阅属性， 您可以为某项订阅设置不同的级别

准备工作

常见订阅属性

创建订阅时，您必须指定一些选项 设置订阅其中一些属性是所有类型的 我们会在后续部分进行讨论。

消息保留时长

消息保留时长选项指定 Pub/Sub 的时长 在消息发布后保留它。消息保留时长过后 Pub/Sub 可能会舍弃该消息，而不考虑 消息的确认状态。要保留已确认的消息，请执行以下操作： 消息保留时长，请参阅重放和舍弃消息。

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

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

未确认的消息可能由空闲订阅、备份需求或 处理速度缓慢如果您 能够在 24 小时内处理邮件，则会产生额外费用。 未发生。为避免产生新的费用，您可以采取以下措施来管理这些情况：

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

  • 备份存储空间。如果您将订阅保留功能作为备份存储空间使用， 您可以改用其他存储选项 主题消息保留 或保留已确认的消息主题消息保留存储消息 而且在所有主题中都仍然可用 供您在需要时使用的订阅。

  • 处理延迟。如果可能，请添加更多订阅者以处理 封邮件。

保留已确认的消息

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

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

有效期

利用有效期选项，您可以延长 您的订阅。

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

如果您指定有效期，则该值的长度必须大于 指定的消息保留时长 消息保留时长选项。

以下是 Expiration period 选项的值：

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

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

确认时限

确认时限选项指定了最初的截止时间，在该截止时间之后 系统会再次发送未确认的消息您可以延长确认 设置每个消息的截止时间， ModifyAckDeadline 请求。

以下是 Acknowledgementdue 选项的值：

  • 默认值 = 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 不再要求提供所有权证明才能推送 订阅网址网域。如果您的网域收到意外的 POST 请求 您可以举报疑似滥用行为。

身份验证

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

身份验证配置 由用户代管式服务账号、 以及用来创建细分受众群的受众群体参数 在 create 方法中指定 patch 或 ModifyPushConfig 调用。您还必须向服务代理授予特定角色，如 下一部分。

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

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

  • 服务代理（必需）。

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

    • 必须为此服务代理授予 iam.serviceAccounts.getOpenIdToken 权限（包含在 roles/iam.serviceAccountTokenCreator 角色）以允许 Pub/Sub 为其创建 JWT 令牌 进行身份验证的推送请求

载荷解封

启用载荷解封 (Enable payload unwrapping) 选项会剥离 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 可以使用 用于写入 JSON 字段的 BigQuery 表 消息发送到相应的列。使用此选项时，请注意 请查看以下额外要求：

  • 已发布的消息必须采用 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 表包含下表中所述的字段。

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

参数
subscription_name

STRING

订阅的名称。
message_id

STRING

消息的 ID
publish_time

TIMESTAMP

发布消息的时间。
data

BYTES、STRING 或 JSON

消息正文。

所有目标平台都必须填写 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.

    • 如果您未指定文件名前缀和后缀，则存储的对象名称 采用以下格式： <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 和 attributes 字段等元数据会写入输出 Avro 对象中的顶级字段，而数据以外的其他所有其他消息属性（例如，order_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 使用 Cloud Pub/Sub 主题的架构 订阅会附加在写入 Avro 文件时。

      使用此选项时，请务必检查以下额外要求：

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

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

后续步骤