Crea un soggetto

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.

Questo documento descrive come creare un argomento in un registro dello schema. Un soggetto è un contenitore logico per diverse versioni di uno schema. Quando crei un soggetto per la prima volta, crei anche la prima versione dello schema per quel soggetto.

Puoi creare un argomento in uno dei seguenti modi:

• Implicito (predefinito): il comportamento predefinito per molti client produttori e consumatori è quello di creare automaticamente uno schema inesistente quando il client si connette. Vengono creati automaticamente anche l'oggetto e la versione che fanno riferimento allo schema. Questa operazione è comoda, ma può portare a potenziali incoerenze nei dati se più client creano versioni contemporaneamente.

• Esplicito (consigliato): in questo metodo, ogni schema deve essere creato nel registro prima che un client produttore o consumatore possa utilizzarlo. Puoi utilizzare la console Google Cloud o l'API Managed Kafka per farlo.

Questo comportamento deve essere configurato nelle impostazioni del client. Per i dettagli, consulta la documentazione della libreria client del serializzatore o del deserializzatore.

Prima di iniziare

• Scopri di più sulla panoramica dello schema.

• Crea un registro degli schemi se non ne hai già uno.

• Comprendere i riferimenti allo schema.

Ruoli e autorizzazioni richiesti

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

Autorizzazioni obbligatorie

Per creare 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.

Il ruolo di livello superiore Amministratore del registro di schema Kafka gestito (roles/managedkafka.schemaRegistryAdmin) include anche le autorizzazioni per creare e gestire le versioni dei soggetti.

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

Creare un soggetto o la prima versione di uno schema

Quando crei un soggetto, crei anche la sua prima versione. Questa prima versione crea un nuovo schema o è un riferimento a uno schema esistente.

Console

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

   Vai a Registri di schema

2. Fai clic sul nome del registro di schema in cui vuoi creare un oggetto.

3. Fai clic su Crea materia.

4. In Nome soggetto, inserisci un nome univoco per il soggetto.

   Il nome deve iniziare con una lettera e contenere solo lettere, numeri e i seguenti caratteri speciali: trattino (-), punto (.), trattino basso (_), tilde (~), percentuale (%) o segno più (+). Il nome di un soggetto non può essere modificato.

   Per saperne di più sulla scelta del nome di un soggetto, consulta Strategie di denominazione dei soggetti.

5. Per Contesto, scegli un contesto o creane uno nuovo. I contesti fungono da spazi dei nomi per organizzare i soggetti e gli schemi, fornendo isolamento tra gruppi diversi.

   • Per utilizzare un contesto esistente, selezionalo dall'elenco Contesto. Il contesto predefinito viene visualizzato come (default context).

   • Per creare un nuovo contesto, segui questi passaggi:

     1. Seleziona Crea contesto dall'elenco Contesto.

     2. Nel campo Nome contesto, inserisci un nome per il contesto.

        Il nome deve iniziare con una lettera e contenere solo lettere, numeri e i seguenti caratteri speciali: trattino (-), punto (.), trattino basso (_), tilde (~), segno di percentuale (%) o segno più (+). Il nome di un contesto non è modificabile.

     3. Fai clic su Salva.

6. In Tipo di schema, seleziona Avro o Protocol Buffer.

7. Nel campo Definizione schema, inserisci la definizione dello schema. Il formato dello schema deve corrispondere al tipo di schema. Non includere informazioni sensibili come quelle che consentono l'identificazione personale (PII) oppure dati di sicurezza nei nomi dei campi dello schema.

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

9. Fai clic su Crea.

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.

Gli esempi di API REST riportati di seguito creano la prima versione di un soggetto.

Per creare un argomento all'interno del contesto predefinito, invia una richiesta POST all'URI specificato utilizzando il metodo projects.locations.schemaRegistries.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/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 soggetti utilizzando il metodo projects.locations.schemaRegistries.contexts.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/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 . per il contesto predefinito se vuoi essere esplicito, altrimenti ometti /contexts/CONTEXT_ID per utilizzare il contesto predefinito in modo implicito.

  Il nome deve iniziare con una lettera e contenere solo lettere, numeri e i seguenti caratteri speciali: trattini -, punti ., trattini bassi _, tildi ~, segni di percentuale % o segni più +. Il nome di un contesto è immutabile.

• SUBJECT_ID (obbligatorio): l'ID del nuovo argomento in cui creare la prima versione.

  Il nome deve iniziare con una lettera e contenere solo lettere, numeri e i seguenti caratteri speciali: trattini -, punti ., trattini bassi _, tildi ~, segni di percentuale % o segni più +. Il nome di un soggetto è immutabile.

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", // 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.

  Non includere informazioni sensibili come quelle che consentono l'identificazione personale (PII) o dati di sicurezza nei nomi dei campi dello schema.

• schemaType (facoltativo): il tipo di schema. Può essere AVRO o PROTOBUF. Se omesso, il valore predefinito è AVRO.

• references (facoltativo): 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: l'ID soggetto dello schema a cui viene fatto riferimento.
  • REFERENCED_VERSION_NUMBER: il numero di versione specifico dello schema dell'argomento a cui viene fatto riferimento.

• versionId, schemaId: campi facoltativi generalmente gestiti dal servizio. Per la prima versione di un argomento, versionId sarà "1".

Se la richiesta ha esito positivo e lo schema è valido e supera i controlli di compatibilità se configurati, l'API restituisce un codice di stato 200 OK. Il corpo della risposta contiene l'ID schema utilizzato dalla versione creata, che è diverso dall'ID versione.

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

Passaggi successivi

• Scopri di più sul registro degli schemi
• Elenco degli argomenti
• Registrare una nuova versione dello schema
• Eliminare un argomento

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