Registra una nuova versione dello schema

Anteprima

Questo prodotto o funzionalità è soggetto ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini di servizio specifici. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Dopo aver creato un argomento, 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 quell'oggetto.

Un argomento 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 l'argomento è configurato per la compatibilità con le versioni precedenti, questa modifica non è consentita. Tuttavia, se l'oggetto è configurato per la compatibilità con le versioni future, l'aggiunta di un campo obbligatorio sarebbe accettabile.

I controlli di compatibilità non sono retroattivi. Se le regole di compatibilità vengono modificate per un registro di schemi o un soggetto, 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 Kafka gestito (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.

Il ruolo di livello superiore Amministratore del registro di schema Kafka gestito (roles/managedkafka.schemaRegistryAdmin) include anche queste autorizzazioni.

Per saperne di più sui ruoli predefiniti disponibili per Managed Service per Apache Kafka, consulta la documentazione sul controllo dell'accesso.

Registra una nuova versione dello schema

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

Console

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

   Vai a Registri di schema

2. Fai clic sul nome del registro degli schemi in cui vuoi registrare una nuova versione dello schema.

3. In Soggetti in questo registro di schema, fai clic sul nome del soggetto.

4. Nella pagina Dettagli soggetto, fai clic su Crea versione.

5. 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.

6. Se lo schema utilizza o dipende da strutture di dati definite in altri schemi nel registro degli schemi, segui questi passaggi:

   1. Fai clic su Add Schema reference (Aggiungi riferimento allo schema).
   2. Nel campo Reference name (Nome di riferimento), inserisci il nome di riferimento dello schema a cui viene fatto riferimento.
   3. Nell'elenco Oggetto, seleziona l'oggetto che contiene lo schema a cui viene fatto riferimento.
   4. Nell'elenco Versione, seleziona il numero di versione dello schema a cui viene fatto riferimento.
   5. Fai clic su OK.

   Ripeti questi passaggi per ogni schema a cui viene fatto riferimento.

7. (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 Controlla compatibilità.

   Il controllo di compatibilità eseguito dipende dal tipo di compatibilità del soggetto.

8. Fai clic su Crea. Se la definizione dello schema è valida e supera i controlli di compatibilità dell'oggetto, 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, invia una richiesta POST all'URI specifico utilizzando il metodo projects.locations.schemaRegistries.subjects.versions.create:

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, includilo nell'URI della raccolta di versioni e utilizza il metodo projects.locations.schemaRegistries.contexts.subjects.versions.create.

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): il tuo Google Cloud ID progetto.
• LOCATION (obbligatorio): la Google Cloud regione in cui esiste il registro di schemi.
• REGISTRY_ID (obbligatorio): l'ID del registro dello schema di destinazione.
• CONTEXT_ID (facoltativo): l'ID del contesto contenente l'oggetto. 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 specificando 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 viene fatto 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 viene fatto riferimento.

• versionId, schemaId: campi facoltativi generalmente gestiti dal servizio. Quando registra la versione dello schema, il servizio assegna il numero di versione successivo disponibile.

Se la richiesta riesce, l'API restituisce un codice di stato 200 OK e un corpo della risposta contenente l'ID schema.

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

Passaggi successivi

• Scopri di più sul registro degli schemi
• Elencare le versioni dell'argomento
• Eliminare una versione dell'oggetto di schema

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