Questo documento descrive come creare un abbonamento a Cloud Storage. Puoi utilizzare la console Google Cloud, Google Cloud CLI, la libreria client oppure l'API Pub/Sub per creare un abbonamento a Cloud Storage.
Prima di iniziare
Prima di leggere questo documento, assicurati di acquisire familiarità con quanto segue:
- Come funziona un abbonamento a Cloud Storage.
- Come funziona Cloud Storage e come creare e gestire i bucket Cloud Storage.
- Come configurare un argomento messaggi non recapitabili per gestire gli errori dei messaggi.
Ruoli e autorizzazioni richiesti
Di seguito è riportato un elenco di linee guida relative a ruoli e autorizzazioni:
Per creare un abbonamento, devi configurare il controllo dell'accesso a livello di progetto.
Hai bisogno anche di autorizzazioni a livello di risorsa se le tue sottoscrizioni e gli argomenti in progetti diversi, come discusso più avanti in questa sezione.
Per creare un abbonamento Cloud Storage, l'account di servizio Pub/Sub deve disporre dell'autorizzazione per scrivere nel bucket Cloud Storage specifico e leggere i metadati del bucket. Per ulteriori informazioni su come concedere queste autorizzazioni, consulta la sezione successiva di questo documento.
Per ottenere le autorizzazioni necessarie per creare abbonamenti a Cloud Storage,
chiedi all'amministratore di concederti
Ruolo IAM dell'editor Pub/Sub (roles/pubsub.editor
) nel progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.
Questo ruolo predefinito contiene le autorizzazioni necessarie per creare abbonamenti a Cloud Storage. Per vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
Per creare abbonamenti a Cloud Storage sono necessarie le seguenti autorizzazioni:
-
Creare una sottoscrizione:
pubsub.subscriptions.create
-
Collegare una sottoscrizione a un argomento:
pubsub.topics.attachSubscription
-
Esegui il pull da una sottoscrizione:
pubsub.subscriptions.consume
-
Acquistare un abbonamento:
pubsub.subscriptions.get
-
Crea una sottoscrizione:
pubsub.subscriptions.list
-
Aggiornare un abbonamento:
pubsub.subscriptions.update
-
Eliminare un abbonamento:
pubsub.subscriptions.delete
-
Ottieni il criterio IAM per una sottoscrizione:
pubsub.subscriptions.getIamPolicy
-
Configura il criterio IAM per un abbonamento:
pubsub.subscriptions.setIamPolicy
Potresti anche riuscire a ottenere queste autorizzazioni con ruoli personalizzati e altri ruoli predefiniti.
Se hai bisogno di creare Cloud Storage
sottoscrizioni in un progetto associate a un argomento in un altro
chiedi all'amministratore dell'argomento di concederti anche l'editor Pub/Sub
(roles/pubsub.editor)
nell'argomento.
assegna ruoli di Cloud Storage all'account di servizio Pub/Sub
Alcuni servizi Google Cloud dispongono di account di servizio gestiti da Google Cloud,
consente ai servizi di accedere alle tue risorse. Questi account di servizio sono noti come agenti di servizio. Pub/Sub crea e gestisce un account di servizio per ogni progetto nel formatoservice-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
.
Per creare un abbonamento Cloud Storage, l'account di servizio Pub/Sub deve disporre dell'autorizzazione per scrivere nel bucket Cloud Storage specifico e leggere i metadati del bucket. Scegli una delle seguenti procedure:
Concedi le autorizzazioni a livello di bucket. Al bucket Cloud Storage specifico, concedi all'account di servizio Pub/Sub il ruolo Creatore oggetti Storage (
roles/storage.objectCreator
) e il ruolo Lettore di bucket legacy Storage (roles/storage.legacyBucketReader
).Se devi concedere ruoli a livello di progetto, puoi concedere il ruolo Amministratore Storage (
roles/storage.admin
) per il progetto che contiene nel bucket Cloud Storage. Concedi questo ruolo ai Account di servizio Pub/Sub.
Autorizzazioni del bucket
Per concedere i ruoli Creatore oggetti Storage
(roles/storage.objectCreator
) e Lettore di bucket legacy Storage
(roles/storage.legacyBucketReader
) a livello di bucket, svolgi i seguenti passaggi:
Nella console Google Cloud, vai alla pagina Cloud Storage.
Fai clic sul bucket Cloud Storage in cui desideri scrivere i messaggi.
Viene visualizzata la pagina Dettagli bucket.
Nella pagina Dettagli bucket, fai clic sulla scheda Autorizzazioni.
Nella sezione Autorizzazioni > Nella scheda Visualizza per entità, fai clic su Concedi l'accesso.
Viene visualizzata la pagina Concedi l'accesso.
Nella sezione Aggiungi entità, inserisci il nome del tuo Pub/Sub l'account di servizio.
Il formato dell'account di servizio è
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
. Ad esempio, per un progetto con PROJECT_NUMBER=112233445566
, l'account di servizio ha il formatoservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
.Nel menu a discesa Assegna ruoli > Seleziona un ruolo, inserisci
Creator
e seleziona il ruolo Creatore oggetti Storage.Fai clic su Aggiungi un altro ruolo.
Nel menu a discesa Seleziona un ruolo, inserisci
Bucket Reader
. e seleziona il ruolo Storage Legacy Bucket Reader.Fai clic su Salva.
Autorizzazioni per il progetto
Per concedere il ruolo Amministratore archiviazione
(roles/storage.admin
) a livello di progetto, svolgi i seguenti passaggi:
Nella console Google Cloud, vai alla pagina IAM.
Nella sezione Autorizzazioni > Nella scheda Visualizza per entità, fai clic su Concedi l'accesso.
Viene visualizzata la pagina Concedi l'accesso.
Nella sezione Aggiungi entità, inserisci il nome del tuo Pub/Sub l'account di servizio.
Il formato dell'account di servizio è
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
. Ad esempio, per un progetto con PROJECT_NUMBER=112233445566
, l'account di servizio ha il formatoservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
.In Assegna ruoli > nell'elenco a discesa Seleziona un ruolo inserisci
Storage Admin
e seleziona il ruolo Storage Admin.Fai clic su Salva.
Per ulteriori informazioni su IAM di Cloud Storage, consulta Gestione di identità e accessi di Cloud Storage.
Proprietà delle sottoscrizioni Cloud Storage
Quando configuri un abbonamento a Cloud Storage, devi specificare le proprietà comuni a tutti i tipi di abbonamento e alcune altre Proprietà specifiche dell'abbonamento a Cloud Storage.
Proprietà comuni degli abbonamenti
Scopri di più sulle proprietà di abbonamento comuni che puoi impostare per tutte le sottoscrizioni.
Nome bucket
Prima di creare un bucket Cloud Storage, deve esistere già un bucket abbonamento a Cloud Storage.
I messaggi vengono inviati in batch e archiviati nel bucket Cloud Storage. Un singolo batch o file viene archiviato come oggetto nel bucket.
Il bucket Cloud Storage deve avere Pagamenti a carico del richiedente disattivata.
Per creare un bucket Cloud Storage, consulta Creare bucket.
Prefisso, suffisso e data/ora del nome file
I file Cloud Storage di output generati da Cloud Storage
vengono archiviati come oggetti nel bucket Cloud Storage. Il nome
dell'oggetto archiviato nel bucket Cloud Storage è del seguente
formato: <file-prefix><UTC-date-time>_<uuid><file-suffix>
.
L'elenco seguente include i dettagli del formato del file e i campi che puoi personalizzare:
<file-prefix>
è il prefisso del nome file personalizzato. Questo campo è facoltativo.<UTC-date-time>
è una stringa personalizzabile generata automaticamente in base all'ora viene creato l'oggetto.<uuid>
è una stringa casuale generata automaticamente per l'oggetto.<file-suffix>
è il suffisso del nome file personalizzato. Questo campo è facoltativo. La Il suffisso del nome file non può terminare con "/".Puoi modificare il prefisso e il suffisso del nome file:
Ad esempio, se il valore del prefisso del nome file è
prod_
e il valore di il suffisso del nome file è_archive
, il nome di un oggetto di esempio èprod_2023-09-25T04:10:00+00:00_uN1QuE_archive
.Se non specifichi il prefisso e il suffisso del nome file, il nome dell'oggetto archiviato nel bucket Cloud Storage è nel formato:
<UTC-date-time>_<uuid>
.I requisiti di denominazione degli oggetti di Cloud Storage si applicano anche al nome file il prefisso e il suffisso. Per ulteriori informazioni, vedi Informazioni sugli oggetti Cloud Storage.
È possibile modificare la modalità di visualizzazione di data e ora nel nome file:
Matcher data/ora obbligatori che puoi utilizzare solo una volta: year (
YYYY
oYY
), mese (MM
), giorno (DD
), ora (hh
), minuto (mm
), secondo (ss
). Ad esempio,YY-YYYY
oMMM
non è valido.Corrispondenza facoltativi che puoi utilizzare una sola volta: separatore data/ora (
T
) e e la differenza di fuso orario (Z
o+00:00
).Elementi facoltativi che puoi utilizzare più volte: trattino (
-
), trattino basso (_
), due punti (:
) e barra (/
).Ad esempio, se il valore del formato data/ora nome file è
YYYY-MM-DD/hh_mm_ssZ
, il nome di un oggetto di esempio èprod_2023-09-25/04_10_00Z_uNiQuE_archive
.Se il formato data/ora del nome file termina con un carattere che non è un matcher, questo carattere sostituirà il separatore tra
<UTC-date-time>
e<uuid>
. Ad esempio, se il valore del formato data e ora del nome del file èYYYY-MM-DDThh_mm_ss-
, un nome di oggetto di esempio èprod_2023-09-25T04_10_00-uNiQuE_archive
.
Raggruppamento di file
Le sottoscrizioni Cloud Storage ti consentono di decidere quando creare un nuovo file di output archiviato come oggetto in Cloud Storage di sincronizzare la directory di una VM con un bucket. Pub/Sub scrive un file di output quando uno dei sono soddisfatte le condizioni di raggruppamento specificate. Di seguito sono riportate le condizioni di raggruppamento di Cloud Storage:
Durata massima batch di archiviazione. Questa impostazione è obbligatoria. La La sottoscrizione Cloud Storage scrive un nuovo file di output se viene superato il valore specificato per la durata massima. In caso contrario specifica il valore, viene applicato un valore predefinito di 5 minuti. Di seguito sono riportati i valori applicabili per la durata massima:
- Valore minimo = 1 minuto
- Valore predefinito = 5 minuti
- Valore massimo = 10 minuti
Byte massimi batch di archiviazione. Questa impostazione è facoltativa. L'abbonamento Cloud Storage scrive un nuovo file di output se viene superato il valore specificato di byte massimi. Di seguito sono riportate le valori per i byte massimi:
- Valore minimo = 1 kB
- Valore massimo = 10 GiB
Numero massimo di messaggi batch di archiviazione. Questa impostazione è facoltativa. La La sottoscrizione Cloud Storage scrive un nuovo file di output se è stato superato il numero massimo di messaggi specificato. Di seguito sono riportate le valori per il numero massimo di messaggi:
- Valore minimo = 1000
Ad esempio, puoi configurare una durata massima di 6 minuti e per un massimo di 2 GB. Se al quarto minuto il file di output raggiunge di 2 GB, Pub/Sub finalizza il file precedente e inizia scrivere in un nuovo file.
Una sottoscrizione Cloud Storage potrebbe scrivere su più file in un a un bucket Cloud Storage contemporaneamente. Se hai configurato di creare un nuovo file ogni 6 minuti, potresti osservare più file Cloud Storage creati ogni 6 minuti.
In alcune situazioni, Pub/Sub potrebbe iniziare a scrivere in un nuovo prima dell'ora configurata dalle condizioni di raggruppamento dei file. Un file potrebbe anche superare il valore Max byte se la sottoscrizione riceve messaggi di dimensioni maggiori del valore "Max byte".
Formato file
Quando crei un abbonamento Cloud Storage, puoi specificare il formato dei file di output da archiviare in un bucket Cloud Storage come Testo o Avro.
Testo: i messaggi vengono archiviati come testo normale. Un carattere di nuova riga separa un messaggio dal messaggio precedente nel file. Solo messaggio vengono archiviati i payload, non gli attributi o altri metadati.
Avro: i messaggi vengono archiviati in Apache Avro binario. Quando selezioni Avro, puoi attivare le seguenti proprietà aggiuntive:
Scrivi metadati: questa opzione consente di archiviare i metadati del messaggio insieme al messaggio. I metadati come i campi
subscription_name
,message_id
,publish_time
eattributes
vengono scritti nei campi di primo livello dell'oggetto Avro di output, mentre tutte le altre proprietà dei messaggi diverse dai dati (ad esempio, una order_key, se presente) vengono aggiunte come voci nella mappaattributes
.Se l'opzione metadati di scrittura è disattivata, nell'oggetto Avro di output viene scritto solo il payload del messaggio. Ecco lo schema Avro per i messaggi di output con i metadati di scrittura disattivati:
{ "type": "record", "namespace": "com.google.pubsub", "name": "PubsubMessage", "fields": [ { "name": "data", "type": "bytes" } ] }
Ecco lo schema Avro per i messaggi di output con i metadati di scrittura abilitati:
{ "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" } ] }
Utilizza schema argomento: questa opzione consente a Pub/Sub di utilizzare lo schema schema dell'argomento Pub/Sub a cui l'abbonamento è allegato quando scrivi file Avro.
Quando utilizzi questa opzione, ricordati di controllare i seguenti requisiti aggiuntivi:
Lo schema dell'argomento deve essere in formato Apache Avro.
Se sono abilitate le opzioni Utilizza schema argomento e Scrivi metadati, lo schema dell'argomento deve avere un oggetto Record nella directory principale. Pub/Sub espande l'elenco dei campi del record in modo da includere i campi dei metadati. Di conseguenza, il record non può contenere campi con lo stesso nome dei campi dei metadati (
subscription_name
,message_id
,publish_time
oattributes
).
Crea una sottoscrizione Cloud Storage
Console
-
Nella console Google Cloud, vai alla pagina Abbonamenti.
-
Fai clic su Crea sottoscrizione.
-
Inserisci un nome nel campo Subscription ID (ID abbonamento).
Per informazioni su come assegnare un nome a un abbonamento, consulta le linee guida per assegnare un nome a un argomento o a un abbonamento.
-
Scegli o crea un argomento dal menu a discesa.
La sottoscrizione riceve messaggi dall'argomento.
Per informazioni su come creare un argomento, vedi Creare e gestire argomenti.
-
Seleziona Tipo di recapito come Scrivi in Cloud Storage.
-
Per il bucket Cloud Storage, fai clic su Sfoglia.
-
Puoi selezionare un bucket esistente da qualsiasi progetto appropriato.
-
Puoi anche fare clic sull'icona di creazione e seguire le istruzioni sullo schermo per creare un nuovo bucket.
Dopo aver creato il bucket, selezionalo per l'abbonamento Cloud Storage.
Per saperne di più su come creare un bucket, consulta Creare bucket.
Quando specifichi il bucket, Pub/Sub controlla se sono presenti le autorizzazioni appropriate per l'account di servizio Pub/Sub. In caso di problemi di autorizzazione, viene visualizzato un messaggio simile al seguente:
Unable to verify if the Pub/Sub service agent has write permissions on this bucket. You may be lacking permissions to view or set permissions
. -
-
Se riscontri problemi di autorizzazione, fai clic su Imposta autorizzazione e segui le istruzioni sullo schermo.
In alternativa, segui le istruzioni in Assegnare ruoli di Cloud Storage all'account di servizio Pub/Sub.
-
In Formato file, seleziona Testo oppure Avro.
Se selezioni Avro, puoi anche specificare se vuoi archiviare i metadati del messaggio nell'output.
Per ulteriori informazioni sulle due opzioni, incluso il messaggio l'opzione dei metadati per il formato Avro, consulta la sezione File standard.
-
(Facoltativo) Puoi specificare il prefisso, il suffisso e datetime per tutti i file che devono essere scritti nel nel bucket Cloud Storage. Un file viene archiviato come oggetto nel bucket.
Per ulteriori informazioni su come impostare prefisso, suffisso e data/ora, vedi Prefisso, suffisso e data/ora.
-
Per Raggruppamento di file in batch, specifica un tempo massimo che deve trascorrere prima di creare un nuovo file.
Se vuoi, puoi anche impostare le dimensioni massime del file o il numero massimo di messaggi per i file.
Per ulteriori informazioni su entrambe le opzioni di batch di file, consulta Raggruppamento di file in batch.
-
Ti consigliamo vivamente di attivare i messaggi non recapitabili per gestire gli errori dei messaggi.
Per ulteriori informazioni, consulta l'argomento Messaggi inutilizzati.
-
Puoi mantenere le altre impostazioni predefinite e fare clic su Crea.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
- Per creare un
Sottoscrizione Cloud Storage, esegui il comando
gcloud pubsub subscriptions create
.gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --cloud-storage-bucket=BUCKET_NAME \ --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \ --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \ --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \ --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \ --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \ --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \ --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \ --cloud-storage-write-metadata --cloud-storage-use-topic-schema
Nel comando, solo
SUBSCRIPTION_ID
,--topic
e--cloud-storage-bucket
sono obbligatori. I flag rimanenti sono facoltativi e possono essere omessi.Sostituisci quanto segue:
SUBSCRIPTION_ID
: il nome o l'ID del nuovo elemento abbonamento a Cloud Storage.TOPIC_ID
: il nome o l'ID dell'argomento.BUCKET_NAME
: specifica il nome di un bucket esistente. Ad esempio,prod_bucket
. Il bucket non deve includere l'ID progetto. Per creare un bucket, consulta Creare bucket.CLOUD_STORAGE_FILE_PREFIX
: specifica il parametro per il nome file di Cloud Storage. Ad esempio:log_events_
.CLOUD_STORAGE_FILE_SUFFIX
: specifica il parametro per il nome file Cloud Storage. Ad esempio,.txt
.CLOUD_STORAGE_FILE_DATETIME_FORMAT
: Specifica il formato data/ora per il nome file di Cloud Storage. Ad esempio,YYYY-MM-DD/hh_mm_ssZ
.CLOUD_STORAGE_MAX_DURATION
: la durata massima che può trascorrere prima che venga creato un nuovo file Cloud Storage. Il valore deve essere compreso tra 1 m e 10 m. Ad esempio:5m
.CLOUD_STORAGE_MAX_BYTES
: i byte massimi che possono essere scritte in un file Cloud Storage prima di un nuovo file viene creato. Il valore deve essere compreso tra 1 KB e 10 GB. Ad esempio:20MB
.CLOUD_STORAGE_MAX_MESSAGES
: la soglia massima numero di messaggi che possono essere scritti in un file Cloud Storage prima della creazione di un nuovo file. Il valore deve essere maggiore o uguale a a 1000. Ad esempio,100000
.CLOUD_STORAGE_OUTPUT_FORMAT
: l'output per i dati scritti in Cloud Storage. I valori sono segue:text
: i messaggi vengono scritti come testo non elaborato, separati da una nuova riga.avro
: i messaggi sono scritti come file binario Avro.--cloud-storage-write-metadata
e Solo--cloud-storage-use-topic-schema
interessati richieste con formato di outputavro
.
C++
Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Go
Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub Go documentazione di riferimento.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di Pub/Sub con librerie client. Per ulteriori informazioni, consulta API Pub/Sub Java documentazione di riferimento.
Per eseguire l'autenticazione su Pub/Sub, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Monitorare una sottoscrizione Cloud Storage
Cloud Monitoring fornisce una serie di metriche monitorare gli abbonamenti.
Per un elenco di tutte le metriche disponibili relative a Pub/Sub e le relative descrizioni, consulta la documentazione di monitoraggio per Pub/Sub.
Puoi anche monitorare le sottoscrizioni all'interno di Pub/Sub.
Passaggi successivi
Risolvi i problemi relativi a un abbonamento a Cloud Storage.
Scopri di più su Cloud Storage.
Consulta i prezzi di Pub/Sub, incluso l'abbonamento a Cloud Storage.