Eseguire il commit di una revisione dello schema

Questo documento mostra come eseguire il commit di una revisione dello schema per gli argomenti Pub/Sub.

Prima di iniziare

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per eseguire il commit di una revisione dello schema e gestire gli schemi, chiedi all'amministratore di concederti il ruolo IAM Pub/Sub Editor (roles/pubsub.editor) nel 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 eseguire il commit di una revisione dello schema e gestire gli schemi. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per eseguire il commit di una revisione dello schema e gestire gli schemi sono necessarie le seguenti autorizzazioni:

  • Crea schema: pubsub.schemas.create
  • Collega 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 le revisioni dello schema: pubsub.schemas.get
  • Elenca schemi: pubsub.schemas.list
  • Elenca 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 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 collegarlo a un argomento che si trova in un altro progetto. Assicurati di disporre delle autorizzazioni richieste per ogni progetto.

Rivedi uno schema

Puoi eseguire il commit di una revisione dello schema utilizzando la Google Cloud console, gcloud CLI, l'API Pub/Sub, o le librerie client di Cloud.

Di seguito sono riportate alcune linee guida per eseguire il commit di una revisione dello schema:

  • Puoi rivedere uno schema entro vincoli specifici:

    • Per gli schemi Protocol Buffer, puoi aggiungere o rimuovere campi facoltativi. Non puoi aggiungere o eliminare altri campi. Inoltre, non puoi modificare alcun campo esistente.

    • Per gli schemi Avro, consulta la documentazione di Avro per le regole relative alla risoluzione dello schema. Una nuova revisione deve seguire le regole come se fosse sia lo schema del lettore sia lo schema dello scrittore.

    • Uno schema può avere un massimo di 20 revisioni contemporaneamente. Se superi il limite, elimina una revisione dello schema prima di crearne un'altra.

  • A ogni revisione è associato un ID di revisione univoco. L'ID di revisione è un UUID di otto caratteri generato automaticamente.

  • Quando aggiorni l'intervallo di revisione o la revisione di uno schema utilizzato per la convalida dell'argomento, potrebbero essere necessari alcuni minuti prima che le modifiche diventino effettive.

Console

Per creare una revisione dello schema:

  1. Nellaconsole, vai alla pagina Schemi Pub/Sub. Google Cloud

    Vai a Schemi

  2. Fai clic sull'ID schema di uno schema esistente.

    Si apre la pagina Dettagli schema dello schema.

  3. Fai clic su Crea revisione.

    Si apre la pagina Crea revisione dello schema.

  4. Apporta le modifiche necessarie.

    Ad esempio, per lo schema di esempio in Avro che hai creato in Crea uno schema, puoi aggiungere un altro campo facoltativo denominato Price nel seguente modo:

     {
   "type": "record",
   "name": "Avro",
   "fields": [
     {
       "name": "ProductName",
       "type": "string",
       "default": ""
     },
     {
       "name": "SKU",
       "type": "int",
       "default": 0
     },
     {
       "name": "InStock",
       "type": "boolean",
       "default": false
     },
     {
       "name": "Price",
       "type": "double",
       "default": "0.0"
     }
   ]
 }

  5. Fai clic su Convalida definizione per verificare se la definizione dello schema è corretta.

  6. Puoi anche convalidare i messaggi per lo schema.

    1. Fai clic su Test messaggio per testare un messaggio di esempio.

    2. Nella finestra Test messaggio, seleziona un tipo di Codifica messaggio.

    3. Nel corpo del messaggio, inserisci un messaggio di test.

      Ad esempio, ecco un messaggio di esempio per lo schema di test. In questo esempio, seleziona Codifica messaggio come JSON.

      {"ProductName":"GreenOnions", "SKU":34543, "Price":12, "InStock":true}

    4. Fai clic su Test.

  7. Fai clic su Esegui commit per salvare lo schema.

gcloud

gcloud pubsub schemas commit SCHEMA_ID \
        --type=SCHEMA_TYPE \
        --definition=SCHEMA_DEFINITION

Dove:

Puoi anche specificare la definizione dello schema in un file:

gcloud pubsub schemas commit SCHEMA_ID \
        --type=SCHEMA_TYPE \
        --definition-file=SCHEMA_DEFINITION_FILE

Dove:

  • SCHEMA_TYPE è avro o protocol-buffer.
  • SCHEMA_DEFINITION_FILE è un string contenente il percorso del file con la definizione dello schema, formattata in base al tipo di schema scelto .

REST

Per eseguire il commit di una revisione dello schema, invia una richiesta POST come la seguente:

POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/schemas/SCHEMA_ID:commit
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json --data @response-body.json

Specifica i seguenti campi nel corpo della richiesta:

{
  "definition": SCHEMA_DEFINITION
  "type": SCHEMA_TYPE
  "name": SCHEMA_NAME
}

Dove:

  • SCHEMA_TYPE è AVRO o PROTOCOL_BUFFER.
  • SCHEMA_DEFINITION è una stringa contenente la definizione di schema, formattata in base al tipo di schema scelto.
  • SCHEMA_NAME è il nome di uno schema esistente.

Il corpo della risposta deve contenere una rappresentazione JSON di una risorsa schema. Ad esempio:

{
  "name": SCHEMA_NAME,
  "type": SCHEMA_TYPE,
  "definition": SCHEMA_DEFINITION
  "revisionId": REVISION_ID
  "revisionCreateTime": REVISION_CREATE_TIME
}

Dove:

  • REVISION_ID è l'ID generato dal server per la revisione.
  • REVISION_CREATE_TIME è il timestamp ISO 8601 in cui è stata creata la revisione.

Go

L'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice deprecati.

Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.

Avro

import (
	"context"
	"fmt"
	"io"
	"os"

	pubsub "cloud.google.com/go/pubsub/v2/apiv1"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// commitAvroSchema commits a new Avro schema revision to an existing schema.
func commitAvroSchema(w io.Writer, projectID, schemaID, avscFile string) error {
	// projectID := "my-project-id"
	// schemaID := "my-schema-id"
	// avscFile = "path/to/an/avro/schema/file(.avsc)/formatted/in/json"
	ctx := context.Background()
	client, err := pubsub.NewSchemaClient(ctx)
	if err != nil {
		return fmt.Errorf("pubsub.NewSchemaClient: %w", err)
	}
	defer client.Close()

	// Read an Avro schema file formatted in JSON as a byte slice.
	avscSource, err := os.ReadFile(avscFile)
	if err != nil {
		return fmt.Errorf("error reading from file: %s", avscFile)
	}

	schema := &pubsubpb.Schema{
		Name:       fmt.Sprintf("projects/%s/schemas/%s", projectID, schemaID),
		Type:       pubsubpb.Schema_AVRO,
		Definition: string(avscSource),
	}
	req := &pubsubpb.CommitSchemaRequest{
		Name:   fmt.Sprintf("projects/%s/schemas/%s", projectID, schemaID),
		Schema: schema,
	}
	s,