使用适用于 Cloud Storage 的 Pub/Sub 通知

转到概念

本页面介绍如何设置和使用适用于 Cloud Storage 的 Pub/Sub 通知。Pub/Sub 通知功能可让您跟踪 Cloud Storage 对象的更改。

注意：Pub/Sub 通知功能是一项不同于对象更改通知的功能。Pub/Sub 通知功能向 Pub/Sub 发送通知，而对象更改通知向您设置的客户端应用发送 HTTPS 通知。

注意：您目前无法使用 Cloud Console、XML API 或 Java 客户端库管理 Pub/Sub 通知。

前提条件

在使用此功能之前，您应执行以下操作：

1. 为将接收通知的项目启用 Pub/Sub API。

   启用该 API

2. 对您要监控的存储分区拥有足够的权限：

   • 如果您拥有存储分区所属的项目，那么您很可能已具备所需的权限。

   • 如果您使用 IAM，则应该具有 storage.buckets.update 权限。如需了解如何执行此操作，请参阅使用 IAM 权限。

   • 如果您使用 ACL，则应该具有 OWNER 权限。如需了解如何执行此操作，请参阅设置 ACL。

3. 对接收通知的项目拥有足够的权限：

   • 如果您拥有接收通知的项目，则您很可能具备所需的权限。

   • 如果您打算创建主题来接收通知，应具备 pubsub.topics.create 权限。

   • 无论您是打算使用新主题还是现有主题，都应具备 pubsub.topics.setIamPolicy 权限。如果您创建了一个主题，则通常具备该主题的 pubsub.topics.setIamPolicy 权限。

     如需了解如何获得这些 Pub/Sub 权限，请参阅 Pub/Sub 访问权限控制。

4. 注意：如果您使用的是 gsutil 工具，则无需执行其余步骤。

   存在要向其发送通知的 Pub/Sub 主题。

5. 获取与包含 Cloud Storage 存储分区的项目关联的服务代理的电子邮件地址。

6. 使用您在上一步中获得的电子邮件地址为服务代理授予所需 Pub/Sub 主题的 IAM 角色 pubsub.publisher。

   注意：在分配角色之后，可能会经历几秒钟的延迟，然后角色才会应用到您的服务代理上。如果您以编程方式授予此权限，请等待 30 秒再配置 Cloud Storage。

应用通知配置

以下步骤将向您的存储分区添加通知配置，用于为所有支持的事件发送通知。

gsutil

使用 gsutil notification create 命令，注意要将 PLACEHOLDERS 替换为适当的值：

gsutil notification create -t TOPIC_NAME -f json gs://BUCKET_NAME

如果您使用项目中不存在的 TOPIC_NAME，gsutil 会为您创建一个主题名称。

如需为一部分事件发送通知，请添加 -e 标志。

代码示例

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

在 GitHub 上查看 反馈

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& topic_name) {
  StatusOr<gcs::NotificationMetadata> notification =
      client.CreateNotification(bucket_name, topic_name,
                                gcs::payload_format::JsonApiV1(),
                                gcs::NotificationMetadata());

  if (!notification) {
    throw std::runtime_error(notification.status().message());
  }

  std::cout << "Successfully created notification " << notification->id()
            << " for bucket " << bucket_name << "\n";
  std::cout << "Full details for the notification:\n"
            << *notification << "\n";
}

C#

如需了解详情，请参阅 Cloud Storage C# API 参考文档。

如需使用 C# 为存储分区创建通知配置，请参阅 CreateTopic 参考文档。

Go

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需使用 Go 为存储分区创建通知配置，请参阅 BucketHandle 参考文档。

Java

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

您目前无法使用 Java 客户端库管理 Pub/Sub 通知。

Node.js

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需使用 NodeJS 为存储分区创建通知配置，请参阅存储分区参考文档。

PHP

如需了解详情，请参阅 Cloud Storage PHP API 参考文档。

如需使用 PHP 为存储分区创建通知配置，请参阅 Google Cloud 客户端库参考文档。

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需使用 Python 为存储分区创建通知配置，请参阅存储分区参考文档。

Ruby

如需了解详情，请参阅 Cloud Storage Ruby API 参考文档。

如需使用 Ruby 为存储分区创建通知配置，请参阅 Google::Cloud::Storage::Bucket 类参考文档。

JSON API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。

2. 创建一个包含以下信息的 .json 文件，并将 PLACEHOLDERS 替换为适当的值：

   {
     "topic": "projects/PROJECT_ID/topics/TOPIC_NAME",
     "payload_format": "JSON_API_V1"
   }

   如需为一部分事件发送通知，请在 JSON 请求的正文中添加 event_types 字段。

3. 使用 cURL，通过 POST notificationConfigs 请求调用 JSON API，注意要将 PLACEHOLDERS 替换为适当的值：

   curl -X POST --data-binary @JSON_FILE_NAME.json \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs"

列出存储分区的通知配置

如需列出与特定存储分区关联的通知配置，请执行以下操作：

gsutil

使用 gsutil notification list 命令，注意要将 PLACEHOLDERS 替换为适当的值：

gsutil notification list gs://BUCKET_NAME

代码示例

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

在 GitHub 上查看 反馈

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& notification_id) {
  StatusOr<gcs::NotificationMetadata> notification =
      client.GetNotification(bucket_name, notification_id);
  if (!notification) {
    throw std::runtime_error(notification.status().message());
  }

  std::cout << "Notification " << notification->id() << " for bucket "
            << bucket_name << "\n";
  if (notification->object_name_prefix().empty()) {
    std::cout << "This notification is sent for all objects in the bucket\n";
  } else {
    std::cout << "This notification is sent only for objects starting with"
              << " the prefix " << notification->object_name_prefix() << "\n";
  }
  std::cout << "Full details for the notification:\n"
            << *notification << "\n";
}

C#

如需了解详情，请参阅 Cloud Storage C# API 参考文档。

如需使用 C# 列出与存储分区关联的通知配置，请参阅 StorageClient 参考文档。

Go

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需使用 Go 列出与存储分区关联的通知配置，请参阅 BucketHandle 参考文档。

Java

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

您目前无法使用 Java 客户端库管理 Pub/Sub 通知。

Node.js

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需使用 NodeJS 列出与存储分区关联的通知配置，请参阅存储分区参考文档。

PHP

如需了解详情，请参阅 Cloud Storage PHP API 参考文档。

如需使用 PHP 列出与存储分区关联的通知配置，请参阅 Google Cloud 客户端库参考文档。

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需使用 Python 列出与存储分区关联的通知配置，请参阅存储分区参考文档。

Ruby

如需了解详情，请参阅 Cloud Storage Ruby API 参考文档。

如需使用 Ruby 列出与存储分区关联的通知配置，请参阅 Google::Cloud::Storage::Bucket 类参考文档。

JSON API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。

2. 使用 cURL，通过 GET notificationConfigs 请求调用 JSON API，注意要将 PLACEHOLDERS 替换为适当的值：

   curl -X GET \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs"

移除通知配置

如需从存储分区中移除现有通知配置，请执行以下操作：

gsutil

使用 gsutil notification delete 命令，注意要将 PLACEHOLDERS 替换为适当的值：

gsutil notification delete projects/_/buckets/BUCKET_NAME/notificationConfigs/CONFIGURATION_NAME

发送通知后，通知配置触发的所有通知最多可能需要 30 秒才能停止。

代码示例

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

在 GitHub 上查看 反馈

namespace gcs = google::cloud::storage;
[](gcs::Client client, std::string const& bucket_name,
   std::string const& notification_id) {
  google::cloud::Status status =
      client.DeleteNotification(bucket_name, notification_id);
  if (!status.ok()) throw std::runtime_error(status.message());

  std::cout << "Successfully deleted notification " << notification_id
            << " on bucket " << bucket_name << "\n";
}

C#

如需了解详情，请参阅 Cloud Storage C# API 参考文档。

如需使用 C# 删除存储分区的通知配置，请参阅 StorageClient 参考文档。

Go

如需了解详情，请参阅 Cloud Storage Go API 参考文档。

如需使用 Go 删除存储分区的通知配置，请参阅 BucketHandle 参考文档。

Java

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

您目前无法使用 Java 客户端库管理 Pub/Sub 通知。

Node.js

如需了解详情，请参阅 Cloud Storage Node.js API 参考文档。

如需使用 NodeJS 删除存储分区的通知配置，请参阅通知参考文档。

PHP

如需了解详情，请参阅 Cloud Storage PHP API 参考文档。

如需使用 PHP 删除存储分区的通知配置，请参阅 Google Cloud 客户端库参考文档。

Python

如需了解详情，请参阅 Cloud Storage Python API 参考文档。

如需使用 Python 删除存储分区的通知配置，请参阅通知参考文档。

Ruby

如需了解详情，请参阅 Cloud Storage Ruby API 参考文档。

如需使用 Ruby 删除存储分区的通知配置，请参阅 Google::Cloud::Storage::Notification 类参考文档。

JSON API

1. 从 OAuth 2.0 Playground 获取授权访问令牌。将 Playground 配置为使用您自己的 OAuth 凭据。

2. 使用 cURL，通过 DELETE notificationConfigs 请求调用 JSON API，注意要将 PLACEHOLDERS 替换为适当的值：

   curl -X DELETE \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/notificationConfigs/CONFIGURATION_NAME"

发送通知后，通知配置触发的所有通知最多可能需要 30 秒才能停止。

后续步骤

• 详细了解适用于 Cloud Storage 的 Pub/Sub 通知。
• 在 Pub/Sub 中创建订阅以查看 Cloud Storage 发送的通知。
• 参阅 GitHub 上用于轮询通知的 Python 示例应用。
• 创建一个使用适用于 Cloud Storage 的 Pub/Sub 通知的相册。
• 了解如何使用 Pub/Sub 执行长时间运行的任务。