Registra una nuova versione dello schema

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 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 argomento 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 viene considerata una modifica incompatibile con le versioni precedenti. Se l'oggetto è 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 soggetti o 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 argomento 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.

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 le informazioni che consentono l'identificazione personale (PII) o dati di sicurezza nei nomi dei campi dello schema.

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

    1. Fai clic su 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à 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 correnti: 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 schema.
  • REGISTRY_ID (obbligatorio): l'ID del registro schemi di destinazione.
  • CONTEXT_ID (facoltativo): l'ID del contesto contenente l'argomento. 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 effettiva.

  • 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 registri la versione dello schema, il servizio assegna il successivo numero di versione disponibile.

Se la richiesta va a buon fine, 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

Apache Kafka® è un marchio registrato di Apache Software Foundation o dei suoi affiliati negli Stati Uniti e/o in altri paesi.