Crea un soggetto

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 è 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 incongruenze 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 consumer 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

Ruoli e autorizzazioni richiesti

Per ottenere le autorizzazioni necessarie per creare un argomento, 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 argomento. 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.

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 degli schemi in cui vuoi creare un soggetto.

  3. Fai clic su Crea materia.

  4. In Nome del 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 è immutabile.

    Per saperne di più sulla scelta di un nome del 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 (~), percentuale (%) o segno più (+). Il nome di un contesto è immutabile.

      3. Fai clic su Salva.

  6. In Tipo di schema, seleziona Avro o buffer di protocollo.

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

  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 correnti: gcloud auth application-default print-access-token.

I seguenti esempi di API REST creano la prima versione di un argomento.

Per creare un argomento nel 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 schema.

  • REGISTRY_ID (obbligatorio): l'ID del registro schemi di destinazione.

  • CONTEXT_ID (facoltativo): l'ID del contesto contenente l'argomento. 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 effettiva.

    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 va a buon fine 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

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