Configurare le notifiche Pub/Sub per Cloud Storage

Panoramica

Questa pagina descrive come configurare il bucket per l'invio di notifiche relative alle modifiche degli oggetti a un argomento Pub/Sub. Per informazioni su come abbonarsi a un argomento Pub/Sub che riceve notifiche, consulta Scegliere un tipo di sottoscrizione.

Prima di iniziare

Prima di utilizzare questa funzionalità, completa le seguenti istruzioni.

Abilita l'API Pub/Sub

Abilita l'API Pub/Sub per il progetto che riceverà le notifiche.

Abilitare l'API

Assicurati di avere un argomento Pub/Sub esistente

Se non l'hai ancora fatto, crea un argomento Pub/Sub a cui vuoi inviare le notifiche. Questo passaggio non è necessario se prevedi di utilizzare Google Cloud CLI o Terraform per eseguire le istruzioni riportate in questa pagina.

Ottenere i ruoli richiesti

I requisiti del ruolo IAM variano a seconda che tu stia configurando la notifica o fornendo i dati degli eventi:

  • Se utilizzi Google Cloud CLI o Terraform per configurare una notifica, la tua identità ha bisogno solo delle autorizzazioni per aggiornare i metadati del bucket e visualizzare il topic Pub/Sub. Per ottenere tutte le autorizzazioni richieste, segui le istruzioni riportate in Ottenere i ruoli per visualizzare i metadati del bucket e l'argomento Pub/Sub.

  • Se il service agent Cloud Storage invia notifiche, deve disporre del ruolo Publisher Pub/Sub (roles/pubsub.publisher) nell'argomento Pub/Sub. Una volta configurato questo ruolo per l'agente di servizio, quest'ultimo funge da "worker" in background per inviare eventi all'argomento.

    Per concedere al service agent le autorizzazioni necessarie per inviare notifiche di eventi all'argomento, segui le istruzioni riportate in Concedere ruoli al service agent del progetto.

Ottenere i ruoli per visualizzare i metadati del bucket e l'argomento Pub/Sub

Per ottenere le autorizzazioni necessarie per configurare e visualizzare le notifiche Pub/Sub per un bucket, chiedi all'amministratore di concederti i seguenti ruoli. Questi ruoli predefiniti contengono le autorizzazioni necessarie per configurare e visualizzare le notifiche Pub/Sub.

  • Ruolo Storage Admin (roles/storage.admin) nel bucket per il quale vuoi configurare le notifiche Pub/Sub

  • Ruolo Pub/Sub Admin (roles/pubsub.admin) nel progetto in cui vuoi ricevere le notifiche Pub/Sub

Potresti riuscire a ottenere queste autorizzazioni con altri ruoli predefiniti o ruoli personalizzati.

Per istruzioni su come concedere ruoli sui bucket, consulta Impostare e gestire le policy IAM sui bucket. Per istruzioni sulla concessione dei ruoli nei progetti e sull'impostazione dei controlli dell'accesso per argomenti e abbonamenti, consulta Controllo dell'accesso.

Concedi il ruolo richiesto al service agent del tuo progetto

Questa sezione mostra come concedere le autorizzazioni richieste all'agente di servizio per inviare le notifiche.

  1. Recupera l'indirizzo email del service agent associato al progetto che contiene il bucket Cloud Storage. L'indirizzo email dell'agente di servizio segue il formato:

    service-PROJECT_NUMBER@gs-project-accounts.iam.gserviceaccount.com

  2. Concedi all'agente di servizio il ruolo Publisher Pub/Sub (roles/pubsub.publisher) per l'argomento Pub/Sub pertinente. Consulta Controllo dell'accesso per istruzioni sulla concessione dei ruoli per gli argomenti.

Applicare una configurazione delle notifiche

I seguenti passaggi aggiungono una configurazione delle notifiche al bucket che invia notifiche per tutti gli eventi supportati.

Console

Non puoi gestire le notifiche Pub/Sub con la consoleGoogle Cloud . Utilizza gcloud CLI o una delle librerie client disponibili.

Riga di comando

Utilizza il comando gcloud storage buckets notifications create:

gcloud storage buckets notifications create gs://BUCKET_NAME --topic=TOPIC_NAME

Dove:

  • BUCKET_NAME è il nome del bucket pertinente. Ad esempio, my-bucket.

  • TOPIC_NAME è l'argomento Pub/Sub a cui inviare le notifiche. Se specifichi un argomento che non esiste nel tuo progetto, il comando ne crea uno per te.

Per inviare notifiche per un sottoinsieme di eventi, includi il flag --event-types.

Librerie client

C++

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage C++.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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::NotificationMetadata());
  if (!notification) throw std::move(notification).status();

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

C#

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage C#.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 


using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class CreatePubSubNotificationSample
{
    public Notification CreatePubSubNotification(
        string bucketName = "your-unique-bucket-name",
        string topic = "my-topic")
    {
        StorageClient storage = StorageClient.Create();
        Notification notification = new Notification
        {
            Topic = topic,
            PayloadFormat = "JSON_API_V1"
        };

        Notification createdNotification = storage.CreateNotification(bucketName, notification);
        Console.WriteLine("Notification subscription created with ID: " + createdNotification.Id + " for bucket name " + bucketName);
        return createdNotification;
    }
}

Go

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Go.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
)

// createBucketNotification creates a notification configuration for a bucket.
func createBucketNotification(w io.Writer, projectID, bucketName, topic string) error {
	// projectID := "my-project-id"
	// bucketName := "bucket-name"
	// topic := "topic-name"

	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	notification := storage.Notification{
		TopicID:        topic,
		TopicProjectID: projectID,
		PayloadFormat:  storage.JSONPayload,
	}

	createdNotification, err := client.Bucket(bucketName).AddNotification(ctx, &notification)
	if err != nil {
		return fmt.Errorf("Bucket.AddNotification: %w", err)
	}
	fmt.Fprintf(w, "Successfully created notification with ID %s for bucket %s.\n", createdNotification.ID, bucketName)
	return nil
}

Java

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Java.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

import com.google.cloud.storage.Notification;
import com.google.cloud.storage.NotificationInfo;
import com.google.cloud.storage.NotificationInfo.EventType;
import com.google.cloud.storage.NotificationInfo.PayloadFormat;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.util.Map;

public class CreateBucketPubSubNotification {

  public static void createBucketPubSubNotification(
      String bucketName,
      String topicName,
      Map<String, String> customAttributes,
      EventType[] eventTypes,
      String objectNamePrefix,
      PayloadFormat payloadFormat) {
    // The ID to give your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    // The name of the topic you would like to create a notification for
    // String topicName = "projects/{your-project}/topics/{your-topic}";

    // Any custom attributes
    // Map<String, String> customAttributes = Map.of("label", "value");

    // The object name prefix for which this notification configuration applies
    // String objectNamePrefix = "blob-";

    // Desired content of the Payload
    // PayloadFormat payloadFormat = PayloadFormat.JSON_API_V1.JSON_API_V1;

    Storage storage = StorageOptions.newBuilder().build().getService();
    NotificationInfo notificationInfo =
        NotificationInfo.newBuilder(topicName)
            .setCustomAttributes(customAttributes)
            .setEventTypes(eventTypes)
            .setObjectNamePrefix(objectNamePrefix)
            .setPayloadFormat(payloadFormat)
            .build();
    Notification notification = storage.createNotification(bucketName, notificationInfo);
    String topic = notification.getTopic();
    System.out.println("Successfully created notification for topic " + topic);
  }
}

Node.js

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Node.js.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The name of a topic
// const topic = 'my-topic';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function createNotification() {
  // Creates a notification
  await storage.bucket(bucketName).createNotification(topic);

  console.log('Notification subscription created.');
}

createNotification().catch(console.error);

PHP

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage PHP.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

Per creare una configurazione di notifica per un bucket utilizzando PHP, consulta la documentazione di riferimento della libreria client Google Cloud.

Python

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Python.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

from google.cloud import storage


def create_bucket_notifications(bucket_name, topic_name):
    """Creates a notification configuration for a bucket."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"
    # The name of a topic
    # topic_name = "your-topic-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    notification = bucket.notification(topic_name=topic_name)
    notification.create()

    print(f"Successfully created notification with ID {notification.notification_id} for bucket {bucket_name}")

Ruby

Per saperne di più, consulta la documentazione di riferimento dell'API Cloud Storage Ruby.

Per eseguire l'autenticazione in Cloud Storage, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

require "google/cloud/storage"

def create_bucket_notifications bucket_name:, topic_name:
  # The ID of your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  # The ID of the pubsub topic
  # topic_name = "your-unique-topic-name"

  storage = Google::Cloud::Storage.new
  bucket  = storage.bucket bucket_name
  notification = bucket.create_notification topic_name

  puts "Successfully created notification with ID #{notification.id} for bucket #{bucket_name}"
end

Terraform

Puoi utilizzare una risorsa Terraform per aggiungere una configurazione di notifica a un bucket.

// Create a Pub/Sub notification.
resource "google_storage_notification" "notification" {
  provider       = google-beta
  bucket         = google_storage_bucket.bucket.name
  payload_format = "JSON_API_V1"
  topic          = google_pubsub_topic.topic.id
  depends_on     = [google_pubsub_topic_iam_binding.binding]
}

// Enable notifications by giving the correct IAM permission to the unique service account.
data "google_storage_project_service_account" "gcs_account" {
  provider = google-beta
}

// Create a Pub/Sub topic.
resource "google_pubsub_topic_iam_binding" "binding" {
  provider = google-beta
  topic    = google_pubsub_topic.topic.id
  role     = "roles/pubsub.publisher"
  members  = ["serviceAccount:${data.google_storage_project_service_account.gcs_account.email_address}"]
}

resource "random_id" "bucket_prefix" {
  byte_length = 8
}

// Create a new storage bucket.
resource "google_storage_bucket" "bucket" {
  name                        = "${random_id.bucket_prefix.hex}-example-bucket-name"
  provider                    = google-beta
  location                    = "US"
  uniform_bucket_level_access = true
}

resource "google_pubsub_topic" "topic" {
  name     = "your_topic_name"
  provider = google-beta
}

API REST