Questo documento mostra come associare gli schemi per gli argomenti Pub/Sub.
Prima di iniziare
- Scopri come funzionano gli 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
Ruolo IAM dell'editor Pub/Sub (roles/pubsub.editor
) nel progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.
Questo ruolo predefinito contiene le autorizzazioni necessarie per associare e gestire gli schemi. Per vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
Per associare e gestire gli schemi sono necessarie le seguenti autorizzazioni:
-
Crea schema:
pubsub.schemas.create
-
Associa 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
-
Ottieni uno schema o una revisione dello schema:
pubsub.schemas.get
-
Elenca gli 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
-
Ottieni il criterio IAM per uno schema:
pubsub.schemas.getIamPolicy
-
Configura il criterio IAM per uno schema:
pubsub.schemas.setIamPolicy
Potresti anche riuscire a ottenere queste autorizzazioni con ruoli personalizzati altri ruoli predefiniti.
Puoi concedere ruoli e autorizzazioni a entità come utenti, gruppi domini o account di servizio. Puoi creare uno schema in un progetto a un argomento di un altro progetto. Assicurati di disporre delle autorizzazioni necessarie per per ogni progetto.
Linee guida per associare uno schema a un argomento
Puoi associare uno schema a un argomento quando crei o modifichi un argomento. Di seguito sono riportate le linee guida per associare 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 che riceve dagli editori devono seguire questo schema.
Quando associ uno schema a un argomento, devi anche specificare la codifica dei messaggi da pubblicare come
BINARY
oJSON
. Se utilizzi JSON con un Per lo schema Avro, presta particolare attenzione alle regole di codifica per i unioni.Se uno schema associato a un argomento ha revisioni, i messaggi devono corrispondere la codifica e la convalida rispetto a una revisione nell'intervallo disponibile. Se non vengono convalidate, la pubblicazione del messaggio non riesce.
Le revisioni vengono provate in ordine cronologico inverso basato su data e ora di creazione. Per creare una revisione dello schema, consulta Esegui il commit di una revisione dello schema.
Logica di convalida per uno schema di messaggi
Quando associ uno schema a un argomento e se quest'ultimo ha revisioni, puoi specificare un sottoinsieme di revisioni da utilizzare. Se non specifichi un viene utilizzato l'intero intervallo per la convalida.
Se non specifichi una revisione come Prima revisione consentita, per la convalida viene usata la revisione esistente dello schema meno recente. Se non specifichi una revisione come Ultima revisione consentita, viene usata la revisione esistente più recente dello schema.
Prendiamo l'esempio dello schema S
associato all'argomento T
.
Per lo schema S
sono stati creati in ordine gli ID revisione A
,B
, C
e D
,
dove A
è la prima o la revisione meno recente. Nessuno degli schemi è identico
o rollback di uno schema esistente.
Se imposti solo il campo Prima revisione consentita su
B
, i messaggi conformi solo allo schemaA
vengono rifiutati. mentre vengono accettati i messaggi conformi agli schemiB
,C
eD
.Se imposti solo il campo Ultima revisione consentita su
C
, vengono accettati i messaggi conformi agli schemiA
,B
eC
. e i messaggi conformi solo allo schemaD
vengono rifiutati.Se imposti entrambi i campi Prima revisione consentita su
B
e Ultima revisione consentita comeC
, messaggi conformi a gli schemiB
eC
sono accettati.Puoi anche impostare la prima e l'ultima revisione sullo stesso ID revisione. In questo caso, vengono accettati solo i messaggi conformi alla revisione.
Crea e associa uno schema quando crei un argomento
Puoi creare un argomento con uno schema utilizzando la console Google Cloud, gcloud CLI, l'API Pub/Sub o le librerie client di Cloud.
Console
Nella console Google Cloud, vai alla pagina Argomenti Pub/Sub.
Fai clic su Crea argomento.
Inserisci un ID per l'argomento nel campo ID argomento.
Per assegnare un nome a un argomento, consulta le linee guida.
Seleziona la casella Utilizza uno schema.
Conserva le impostazioni predefinite per i restanti campi.
Puoi creare uno schema o utilizzarne uno esistente.
Per creare uno schema, segui questi passaggi:
- Per Seleziona uno schema Pub/Sub, scegli 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 il tuo schema nel campo Seleziona uno schema Pub/Sub.
Seleziona la codifica del messaggio come JSON o Binario.
Lo schema appena creato ha un ID revisione. Puoi creare altri revisioni dello schema come discusso in Eseguire il commit di una revisione dello schema.
Se vuoi associare uno schema già creato, segui questi passaggi:
Per Seleziona uno schema Pub/Sub, scegli uno schema esistente.
Seleziona la codifica del messaggio come JSON o Binario.
(Facoltativo) Se lo schema selezionato ha revisioni, per l'opzione Intervallo di revisioni: Utilizza i menu a discesa per Prima revisione consentita e Ultima revisione consentita.
Puoi specificare entrambi i campi, specificarne uno solo o mantenere il valore predefinito le impostazioni in base ai tuoi requisiti.
Conserva le impostazioni predefinite per i restanti campi.
Fai clic su Crea per salvare l'argomento e assegnarlo allo schema selezionato.
gcloud
Per creare un argomento assegnato con 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 in base al
. 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 utilizzare per la convalida.
- LAST_REVISION_ID è l'ID dell'ultima revisione in base a cui eseguire la convalida.
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 del progetto Google Cloud per lo schema.
- TOPIC_PROJECT è l'ID del progetto Google Cloud per l'argomento.
REST
Per creare un argomento, utilizza la projects.topics.create
:
Richiesta:
La richiesta deve essere autenticata con un token di accesso nel
Intestazione Authorization
. Per ottenere un token di accesso per l'istanza
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 è il tuo ID 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 utilizzare per la convalida.
- LAST_REVISION_ID è l'ID dell'ultima revisione in base a cui eseguire la convalida.
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 vengono forniti
nella richiesta.
C++
Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ in 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 C# in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API C# Pub/Sub.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
PHP
Prima di provare questo esempio, segui le istruzioni per la configurazione di PHP in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API PHP Pub/Sub.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Pub/Sub.
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Ruby Pub/Sub.
Modificare uno schema associato a un argomento
Puoi modificare un argomento per collegare uno schema, rimuoverlo o aggiornare l'intervallo di revisioni utilizzato per convalidare i messaggi. In generale, se hai pianificato modifiche allo schema in uso, puoi eseguire il commit di una nuova revisione aggiornare l'intervallo di revisioni utilizzate per l'argomento.
Puoi modificare uno schema associato a un argomento utilizzando il metodo console Google Cloud, gcloud CLI, l'API Pub/Sub, o le librerie client di Cloud.
Console
Nella console Google Cloud, 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.
L'applicazione delle modifiche potrebbe richiedere alcuni minuti.
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 come richiesto.
- Se vuoi aggiornare l'intervallo di revisioni, in Intervallo di revisioni: Utilizza i menu a discesa per Prima revisione consentita e Ultima revisione consentita.
Puoi specificare entrambi i campi, specificarne uno solo o mantenere il valore predefinito le impostazioni 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 in base al
. 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 utilizzare per la convalida.
- LAST_REVISION_ID è l'ID dell'ultima revisione in base a cui eseguire la convalida.
Sia --first-revision-id
che --last-revision-id
sono facoltativi.
REST
Per aggiornare un argomento, utilizza projects.topics.patch
:
Richiesta:
La richiesta deve essere autenticata con un token di accesso nel
Intestazione Authorization
. Per ottenere un token di accesso per l'istanza
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 è il tuo ID 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 utilizzare per la convalida.
- LAST_REVISION_ID è l'ID dell'ultima revisione in base a cui eseguire la convalida.
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" } }
Sia firstRevisionId
che lastRevisionId
non sono impostati dopo il tag
aggiornamento.
C++
Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ in 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 in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Pub/Sub.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Pub/Sub.
0Passaggi successivi
- Esegui il commit di una revisione dello schema
- Pubblicare messaggi in un argomento con uno schema
- Convalidare una definizione di schema
- Convalidare un messaggio per uno schema