Questo documento mostra come associare gli schemi agli argomenti Pub/Sub.
Prima di iniziare
- Comprendere il funzionamento degli schemi Pub/Sub.
- Crea uno schema.
Ruoli e autorizzazioni richiesti
Per ottenere le autorizzazioni necessarie per associare e gestire gli schemi, chiedi all'amministratore di concederti il ruolo IAM Editor Pub/Sub (roles/pubsub.editor
) nel tuo progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Questo ruolo predefinito contiene le autorizzazioni necessarie per associare e gestire gli schemi. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
Per associare e gestire gli schemi sono necessarie le seguenti autorizzazioni:
-
Crea schema:
pubsub.schemas.create
-
Allega lo schema all'argomento:
pubsub.schemas.attach
-
Esegui il commit di una revisione dello schema:
pubsub.schemas.commit
-
Elimina uno schema o una revisione dello schema:
pubsub.schemas.delete
-
Recuperare uno schema o le revisioni dello schema:
pubsub.schemas.get
-
Elenca schemi:
pubsub.schemas.list
-
Elenca le revisioni dello schema:
pubsub.schemas.listRevisions
-
Esegui il rollback di uno schema:
pubsub.schemas.rollback
-
Convalida un messaggio:
pubsub.schemas.validate
-
Recupera il criterio IAM per uno schema:
pubsub.schemas.getIamPolicy
-
Configura il criterio IAM per uno schema:
pubsub.schemas.setIamPolicy
Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.
Puoi concedere ruoli e autorizzazioni a entità come utenti, gruppi, domini o service account. Puoi creare uno schema in un progetto e allegarlo a un argomento che si trova in un altro progetto. Assicurati di disporre delle autorizzazioni necessarie per ogni progetto.
Linee guida per associare uno schema a un argomento
Puoi associare uno schema a un argomento quando lo crei o lo modifichi. Di seguito sono riportate le linee guida per l'associazione di uno schema a un argomento:
Puoi associare uno schema a uno o più argomenti.
Dopo che uno schema è associato a un argomento, ogni messaggio che l'argomento riceve dagli editori deve seguire lo schema.
Quando associ uno schema a un argomento, devi anche specificare la codifica dei messaggi da pubblicare come
BINARY
oJSON
. Se utilizzi JSON con uno schema Avro, presta particolare attenzione alle regole di codifica per le unioni.Se uno schema associato a un argomento ha revisioni, i messaggi devono corrispondere alla codifica e convalidarsi in base a una revisione all'interno dell'intervallo disponibile. Se non vengono convalidati, il messaggio non viene pubblicato.
Le revisioni vengono provate in ordine cronologico inverso in base all'ora di creazione. Per creare una revisione dello schema, vedi Eseguire il commit di una revisione dello schema.
Logica di convalida per uno schema di messaggio
Quando associ uno schema a un argomento e se lo schema ha revisioni, puoi specificare un intervallo di revisioni da utilizzare. Se non specifichi un intervallo, viene utilizzato l'intero intervallo per la convalida.
Se non specifichi una revisione come Prima revisione consentita, per la convalida viene utilizzata la revisione meno recente esistente per lo schema. Se non specifichi una revisione come Ultima revisione consentita, viene utilizzata la revisione più recente esistente per lo schema.
Prendiamo l'esempio dello schema S
collegato all'argomento T
.
Lo schema S
ha gli ID revisione A
,B
, C
e D
creati in ordine,
dove A
è la prima o la revisione meno recente. Nessuno degli schemi è identico
tra loro o rollback di uno schema esistente.
Se imposti solo il campo Prima revisione consentita come
B
, i messaggi conformi solo allo schemaA
vengono rifiutati, mentre i messaggi conformi agli schemiB
,C
eD
vengono accettati.Se imposti solo il campo Ultima revisione consentita come
C
, i messaggi conformi agli schemiA
,B
eC
vengono accettati, mentre i messaggi conformi solo allo schemaD
vengono rifiutati.Se imposti entrambi i campi Prima revisione consentita su
B
e Ultima revisione consentita suC
, i messaggi conformi agli schemiB
eC
vengono accettati.Puoi anche impostare la prima e l'ultima revisione sullo stesso ID revisione. In questo caso, vengono accettati solo i messaggi conformi a quella revisione.
Creare e associare uno schema quando crei un argomento
Puoi creare un argomento con uno schema utilizzando la Google Cloud console, gcloud CLI, l'API Pub/Sub o le librerie client di Cloud.
Console
Nella Google Cloud console, vai alla pagina Argomenti Pub/Sub.
Fai clic su Crea argomento.
Nel campo ID argomento, inserisci un ID per l'argomento.
Per assegnare un nome a un argomento, consulta le linee guida.
Seleziona la casella Utilizza uno schema.
Mantieni le impostazioni predefinite per i campi rimanenti.
Puoi creare uno schema o utilizzarne uno esistente.
Se stai creando uno schema, segui questi passaggi: `
- In Seleziona uno schema Pub/Sub, seleziona Crea un nuovo schema.
La pagina Crea schema viene visualizzata in una scheda secondaria.
Segui i passaggi descritti in Creare uno schema.
Torna alla scheda Crea argomento e fai clic su Aggiorna.
Cerca lo schema nel campo Seleziona uno schema Pub/Sub.
Seleziona la codifica dei messaggi come JSON o Binario.
Lo schema che hai appena creato ha un ID revisione. Puoi creare revisioni dello schema aggiuntive come descritto in Eseguire il commit di una revisione dello schema.
Se stai associando uno schema già creato, segui questi passaggi:
In Seleziona uno schema Pub/Sub, seleziona uno schema esistente.
Seleziona la codifica dei messaggi come JSON o Binario.
(Facoltativo) Se lo schema selezionato ha revisioni, per Intervallo di revisioni, utilizza i menu a discesa per Prima revisione consentita e Ultima revisione consentita.
Puoi specificare entrambi i campi, solo uno o mantenere le impostazioni predefinite in base ai tuoi requisiti.
Mantieni le impostazioni predefinite per i campi rimanenti.
Fai clic su Crea per salvare l'argomento e assegnarlo allo schema selezionato.
gcloud
Per creare un argomento a cui è assegnato uno schema creato in precedenza, esegui il comando
gcloud pubsub topics create
:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
Dove:
- TOPIC_ID è l'ID dell'argomento che stai creando.
- ENCODING_TYPE è la codifica dei messaggi convalidati rispetto allo schema. Questo valore deve essere impostato su
JSON
oBINARY
. - SCHEMA_ID è l'ID di uno schema esistente.
- FIRST_REVISION_ID è l'ID della revisione meno recente da convalidare.
- LAST_REVISION_ID è l'ID della revisione più recente da convalidare.
Sia --first-revision-id
che --last-revision-id
sono facoltativi.
Puoi anche assegnare uno schema da un altro progetto Google Cloud :
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --schema-project=SCHEMA_PROJECT \ --project=TOPIC_PROJECT
Dove:
- SCHEMA_PROJECT è l'ID progetto del progetto Google Cloud per lo schema.
- TOPIC_PROJECT è l'ID progetto del progetto Google Cloud per l'argomento.
REST
Per creare un argomento, utilizza il metodo projects.topics.create
:
Richiesta:
La richiesta deve essere autenticata con un token di accesso nell'intestazione
Authorization
. Per ottenere un token di accesso per le attuali
Credenziali predefinite dell'applicazione: gcloud auth application-default print-access-token
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Corpo della richiesta:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
Dove:
- PROJECT_ID è l'ID progetto.
- TOPIC_ID è l'ID del tuo argomento.
- SCHEMA_NAME è il nome dello schema in base al quale devono essere convalidati i messaggi pubblicati. Il formato è:
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE è la codifica dei messaggi convalidati in base allo schema. Deve essere impostato su
JSON
oBINARY
. - FIRST_REVISION_ID è l'ID della revisione meno recente da convalidare.
- LAST_REVISION_ID è l'ID della revisione più recente da convalidare.
Sia firstRevisionId
che lastRevisionId
sono facoltativi.
Risposta:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
firstRevisionId
e lastRevisionId
vengono omessi se non forniti
nella richiesta.
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C#.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
PHP
Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub PHP.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Ruby.
Modificare uno schema associato a un argomento
Puoi modificare un argomento per allegare uno schema, rimuovere uno schema o aggiornare l'intervallo di revisioni utilizzato per la convalida dei messaggi. In generale, se hai pianificato modifiche allo schema in uso, puoi eseguire il commit di una nuova revisione e aggiornare l'intervallo di revisioni utilizzato per l'argomento.
Puoi modificare uno schema associato a un argomento utilizzando la consoleGoogle Cloud , gcloud CLI, l'API Pub/Sub o le librerie client di Cloud.
Console
Nella Google Cloud console, vai alla pagina Argomenti Pub/Sub.
Fai clic sull'ID argomento di un argomento.
Nella pagina dei dettagli dell'argomento, fai clic su Modifica.
Puoi apportare le seguenti modifiche allo schema.
Potrebbero essere necessari alcuni minuti prima che le modifiche vengano applicate.
Se vuoi rimuovere lo schema dall'argomento, nella pagina Modifica argomento, deseleziona la casella di controllo Utilizza uno schema.
Se vuoi modificare lo schema, nella sezione Schema, seleziona il nome di uno schema.
Aggiorna gli altri campi in base alle necessità.
- Se vuoi aggiornare l'intervallo di revisione, per Intervallo di revisione, utilizza i menu a discesa per Prima revisione consentita e Ultima revisione consentita.
Puoi specificare entrambi i campi, solo uno o mantenere le impostazioni predefinite in base ai tuoi requisiti.
Fai clic su Aggiorna per salvare le modifiche.
gcloud
gcloud pubsub topics update TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_NAME \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
Dove:
- TOPIC_ID è l'ID dell'argomento che stai creando.
- ENCODING_TYPE è la codifica dei messaggi convalidati rispetto allo schema. Questo valore deve essere impostato su
JSON
oBINARY
. - SCHEMA_NAME è il nome di uno schema esistente.
- FIRST_REVISION_ID è l'ID della revisione meno recente da convalidare.
- LAST_REVISION_ID è l'ID della revisione più recente da convalidare.
Sia --first-revision-id
che --last-revision-id
sono facoltativi.
REST
Per aggiornare un argomento, utilizza il metodo projects.topics.patch
:
Richiesta:
La richiesta deve essere autenticata con un token di accesso nell'intestazione
Authorization
. Per ottenere un token di accesso per le attuali
Credenziali predefinite dell'applicazione: gcloud auth application-default print-access-token
.
PATCH https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Corpo della richiesta:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" "update_mask": } }
Dove:
- PROJECT_ID è l'ID progetto.
- TOPIC_ID è l'ID del tuo argomento.
- SCHEMA_NAME è il nome dello schema in base al quale devono essere convalidati i messaggi pubblicati. Il formato è:
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE è la codifica dei messaggi convalidati in base allo schema. Deve essere impostato su
JSON
oBINARY
. - FIRST_REVISION_ID è l'ID della revisione meno recente da convalidare.
- LAST_REVISION_ID è l'ID della revisione più recente da convalidare.
Sia firstRevisionId
che lastRevisionId
sono facoltativi.
Risposta:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
firstRevisionId
e lastRevisionId
non sono impostati dopo l'aggiornamento.
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java di Pub/Sub.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
Passaggi successivi
- Esegui il commit di una revisione dello schema
- Pubblicare messaggi in un argomento con uno schema
- Convalidare una definizione dello schema
- Convalidare un messaggio per uno schema