Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Registra una nuova versione dello schema

Dopo aver creato un soggetto, puoi aggiungervi nuove versioni. Questa procedura è nota come registrazione di una nuova versione dello schema. Ogni nuova versione rappresenta un'evoluzione dello schema associato a quel soggetto.

Un soggetto può avere più versioni. Le versioni all'interno di un soggetto seguono regole di compatibilità configurabili per garantire un'evoluzione sicura dello schema. Ad esempio, un soggetto può richiedere che tutte le modifiche siano compatibili con le versioni precedenti. Un esempio di modifica compatibile con le versioni precedenti è l'aggiunta di un campo facoltativo. L'aggiunta di un campo obbligatorio è considerata una modifica incompatibile con le versioni precedenti; se il soggetto è configurato per la compatibilità con le versioni precedenti, questa modifica non è consentita. Tuttavia, se il soggetto è configurato per la compatibilità con le versioni successive, l'aggiunta di un campo obbligatorio è accettabile.

I controlli di compatibilità non sono retroattivi. Se le regole di compatibilità vengono modificate per un soggetto o un registro di schemi, le versioni già esistenti all'interno del soggetto non vengono riconvalidate in base alle nuove regole. Per saperne di più sulla compatibilità, consulta Informazioni sul tipo di compatibilità.

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per registrare una versione dello schema per un soggetto, chiedi all'amministratore di concederti il ruolo IAM Editor del registro di schemi di Managed Kafka (roles/managedkafka.schemaRegistryEditor) nel progetto o nel registro di schemi e nel soggetto specifici. 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 registrare una versione dello schema per un soggetto. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per registrare una versione dello schema per un soggetto sono necessarie le seguenti autorizzazioni:

Concedi questa autorizzazione nel contesto principale o nel contesto predefinito: managedkafka.versions.create

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Registrare una nuova versione dello schema

Per registrare una nuova versione dello schema, segui questi passaggi.

Console

Nella Google Cloud console, vai alla pagina Registri di schemi.

Vai ai registri di schemi
Fai clic sul nome del registro di schemi in cui vuoi registrare una nuova versione dello schema.
In Soggetti in questo registro di schemi, fai clic sul nome del soggetto.
Nella pagina Dettagli soggetto, fai clic su Crea versione.
Il campo Definizione dello schema mostra la definizione dell'ultima versione. Aggiorna la definizione in questo campo per la nuova versione. Non includere informazioni sensibili come quelle che consentono l'identificazione personale (PII) o dati di sicurezza nei nomi dei campi dello schema.
Se lo schema utilizza o dipende da strutture di dati definite in altri schemi nel registro di schemi, segui questi passaggi:
1. Fai clic su Aggiungi riferimento allo schema.
2. Nel campo Nome di riferimento, inserisci il nome di riferimento dello schema a cui fai riferimento.
3. Nell'elenco Soggetto, seleziona il soggetto che contiene lo schema a cui fai riferimento.
4. Nell'elenco Versione, seleziona il numero di versione dello schema a cui fai riferimento.
5. Fai clic su OK.
Ripeti questi passaggi per ogni schema a cui fai riferimento.
(Facoltativo) Per verificare se il nuovo schema è compatibile con la versione precedente, fai clic su Verifica compatibilità.

Se lo schema è compatibile, viene visualizzato un segno di spunta. In caso contrario, viene visualizzato un messaggio di errore. In questo caso, correggi l'errore e fai di nuovo clic su Verifica compatibilità.

Il controllo di compatibilità eseguito dipende dal tipo di compatibilità del soggetto .
Fai clic su Crea. Se la definizione dello schema è valida e supera i controlli di compatibilità del soggetto, la nuova versione viene visualizzata in Tutte le versioni.

REST

La richiesta deve essere autenticata con un token di accesso nell'intestazione Authorization. Per ottenere un token di accesso per le credenziali predefinite dell'applicazione corrente: gcloud auth application-default print-access-token.

Per registrare una nuova versione dello schema per un soggetto all'interno del contesto predefinito, effettua una richiesta POST all'URI specifico utilizzando il projects.locations.schemaRegistries.subjects.versions.create metodo:

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

In alternativa, se utilizzi un contesto specifico, includi il contesto nell' URI della raccolta delle versioni e utilizza il projects.locations.schemaRegistries.contexts.subjects.versions.create metodo.

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Sostituisci quanto segue:

PROJECT_ID (obbligatorio): l' Google Cloud ID progetto.
LOCATION (obbligatorio): la Google Cloud regione in cui esiste il registro di schemi.
REGISTRY_ID (obbligatorio): l'ID del registro di schemi di destinazione.
CONTEXT_ID (facoltativo): l'ID del contesto contenente il soggetto. Utilizza . (un singolo punto) per il contesto predefinito se vuoi essere esplicito, altrimenti ometti /contexts/CONTEXT_ID per utilizzare il contesto predefinito in modo implicito.
SUBJECT_ID (obbligatorio): l'ID del soggetto in cui creare la nuova versione.

Corpo della richiesta:

Includi un oggetto JSON nel corpo della richiesta che specifica i dettagli dello schema:

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF" | "JSON", // Optional, defaults to AVRO
  "references": [ // Optional
    {
      "name": "REFERENCE_NAME",
      "subject": "REFERENCED_SUBJECT_ID",
      "version": REFERENCED_VERSION_NUMBER
    }
    // ... more references
  ]
  // "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
  // "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}

Sostituisci quanto segue:

YOUR_SCHEMA_DEFINITION_STRING (obbligatorio): una stringa contenente il payload della definizione dello schema effettivo.
schemaType (facoltativo, all'interno dell'oggetto schema): il tipo di schema. Può essere AVRO o PROTOBUF. Se omesso, il valore predefinito è AVRO.
references (facoltativo, all'interno dell'oggetto schema): un array di oggetti che definiscono gli schemi a cui fa riferimento questo schema.
- REFERENCE_NAME: il nome utilizzato per fare riferimento all'altro schema all'interno della definizione di questo schema.
- REFERENCED_SUBJECT_ID: il nome completo del soggetto dello schema a cui fai riferimento. Esempio: projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject.
- REFERENCED_VERSION_NUMBER: il numero di versione specifico (intero) dello schema del soggetto a cui fai riferimento.
versionId, schemaId: campi facoltativi in genere gestiti dal servizio. Quando registri la versione dello schema, il servizio assegna il numero di versione disponibile successivo.

Se la richiesta va a buon fine, l'API restituisce un codice di stato 200 OK e un corpo della risposta contenente l'ID dello schema.

Per saperne di più, consulta la documentazione dell'API REST.

Passaggi successivi

Apache Kafka® è un marchio registrato di The Apache Software Foundation o delle sue affiliate negli Stati Uniti e/o in altri paesi.