此页面由 Cloud Translation API 翻译。

订阅属性

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

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

准备工作

了解订阅。
了解您要完成的订阅对应的工作流程 create：Pull、Push 或 BigQuery。

常见的订阅属性

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

消息保留时长

消息保留时长选项指定 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 声明。下面列出了服务账号的要求：
- 此服务账号必须与推送订阅位于同一项目中。
- 创建或修改推送订阅的主账号必须拥有服务账号的 iam.serviceAccounts.actAs 权限。您可以向项目、文件夹或组织授予具有此权限的角色，以允许调用方模拟多个服务账号；也可以向服务账号授予具有此权限的角色，以允许调用方仅模拟此服务账号。
观众。一个不区分大小写的字符串用于验证此特定令牌的目标受众群体。
服务代理（必需）。
- 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 可以使用用于写入 JSON 字段的 BigQuery 表消息发送到相应的列。使用此选项时，请务必查看以下其他要求：

已发布的消息必须采用 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。
- 如果您未指定文件名前缀和后缀，则存储的对象名称采用以下格式： <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
批量存储消息数上限。这是一个可选设置。通过如果存在以下情况，则 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 对象中的顶级字段，同时将除数据以外的所有其他消息属性（例如，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 在写入 Avro 文件时使用订阅附加到的 Pub/Sub 主题的架构。
  
  使用此选项时，请务必检查以下额外要求：
  - 主题架构必须采用 Apache Avro 格式。
  - 如果使用主题架构和写入元数据都已启用，则主题架构的根目录中必须有一个 Record 对象。Pub/Sub 将展开记录的字段列表以包含元数据字段。因此，记录不得包含与元数据字段（subscription_name、message_id、publish_time 或 attributes）同名的任何字段。

后续步骤

创建拉取订阅。
创建推送订阅。
创建 BigQuery 订阅。
创建 Cloud Storage 订阅。