Thema erstellen

In diesem Dokument wird beschrieben, wie Sie ein Thema in einer Schemaregistrierung erstellen. Ein Thema ist ein logischer Container für verschiedene Versionen eines Schemas. Wenn Sie ein Thema zum ersten Mal erstellen, erstellen Sie auch die erste Version des Schemas für dieses Thema.

Sie haben folgende Möglichkeiten, ein Thema zu erstellen:

Implizit (Standard): Das Standardverhalten für viele Producer- und Consumer-Clients besteht darin, automatisch ein Schema zu erstellen, das noch nicht vorhanden ist, wenn der Client eine Verbindung herstellt. Das Thema und die Version, die auf das Schema verweisen, werden ebenfalls automatisch erstellt. Das ist zwar praktisch, kann aber zu potenziellen Inkonsistenzen bei den Daten führen, wenn mehrere Clients gleichzeitig Versionen erstellen.
Explizit (empfohlen): Bei dieser Methode muss jedes Schema in der Registry erstellt werden, bevor ein Producer- oder Consumer-Client es verwenden kann. Sie können dafür die Google Cloud Console oder die Managed Kafka API verwenden.

Dieses Verhalten muss in Ihren Clienteinstellungen konfiguriert werden. Weitere Informationen finden Sie in der Dokumentation zu Ihrer Clientbibliothek für die Serialisierung oder Deserialisierung.

Hinweise

Weitere Informationen
Erstellen Sie eine Schema-Registry, falls Sie noch keine haben.
Schemaverweise

Erforderliche Rollen und Berechtigungen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Bearbeiter der verwalteten Kafka-Schemaregistrierung (roles/managedkafka.schemaRegistryEditor) für Ihr Projekt oder Ihre Schemaregistrierung zuzuweisen, damit Sie die Berechtigungen erhalten, die Sie zum Erstellen eines Themas benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierte Rolle enthält die Berechtigungen, die zum Erstellen eines Themas erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind zum Erstellen eines Themas erforderlich:

Gewähren Sie diese Berechtigung im übergeordneten Kontext oder im Standardkontext: managedkafka.versions.create

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Die Rolle Managed Kafka Schema Registry Admin (roles/managedkafka.schemaRegistryAdmin) auf höherer Ebene umfasst auch die Berechtigungen zum Erstellen und Verwalten von Themaversionen.

Weitere Informationen zu den vordefinierten Rollen, die für Managed Service for Apache Kafka verfügbar sind, finden Sie in der Dokumentation zur Zugriffssteuerung.

Subjekt oder erste Version eines Schemas erstellen

Wenn Sie ein Subjekt erstellen, erstellen Sie auch seine erste Version. Mit dieser ersten Version wird ein neues Schema erstellt oder auf ein vorhandenes Schema verwiesen.

Console

Rufen Sie in der Google Cloud Console die Seite Schema-Registries auf.

Zu Schemaregistrierungen
Klicken Sie auf den Namen der Schemaregistrierung, in der Sie ein Thema erstellen möchten.
Klicken Sie auf Betreff erstellen.
Geben Sie unter Name des Subjekts einen eindeutigen Namen für das Subjekt ein.

Der Name muss mit einem Buchstaben beginnen und darf nur Buchstaben, Zahlen und die folgenden Sonderzeichen enthalten: Bindestrich (-), Punkt (.), Unterstrich (_), Tilde (~), Prozentzeichen (%) oder Pluszeichen (+). Der Name eines Themas kann nicht geändert werden.

Weitere Informationen zur Auswahl eines Betreffnamens finden Sie unter Strategien für die Betreffbenennung.
Wählen Sie unter Kontext einen Kontext aus oder erstellen Sie einen neuen. Kontexte fungieren wie Namespaces, um Ihre Themen und Schemas zu organisieren und eine Isolation zwischen verschiedenen Gruppen zu ermöglichen.
- Wenn Sie einen vorhandenen Kontext verwenden möchten, wählen Sie ihn aus der Liste Kontext aus. Der Standardkontext wird als (default context) angezeigt.
- So erstellen Sie einen neuen Kontext:
  1. Wählen Sie in der Liste Kontext die Option Kontext erstellen aus.
  2. Geben Sie im Feld Kontextname einen Namen für den Kontext ein.
    
    Der Name muss mit einem Buchstaben beginnen und darf nur Buchstaben, Ziffern und die folgenden Sonderzeichen enthalten: Bindestrich (-), Punkt (.), Unterstrich (_), Tilde (~), Prozentzeichen (%) oder Pluszeichen (+). Der Name eines Kontexts kann nicht geändert werden.
  3. Klicken Sie auf Speichern.
Wählen Sie als Schematyp entweder Avro oder Protocol Buffer aus.
Geben Sie im Feld Schemadefinition die Schemadefinition ein. Das Format des Schemas muss dem Schematyp entsprechen. Die Namen von Schemafeldern dürfen keine vertraulichen Informationen wie personenidentifizierbare Informationen oder Sicherheitsdaten enthalten.
Wenn Ihr Schema Datenstrukturen verwendet oder von Datenstrukturen abhängt, die in anderen Schemas in der Schema-Registry definiert sind, führen Sie die folgenden Schritte aus:
1. Klicken Sie auf Schemareferenz hinzufügen.
2. Geben Sie im Feld Referenzname den Referenznamen des referenzierten Schemas ein.
3. Wählen Sie in der Liste Subject das Thema aus, das das referenzierte Schema enthält.
4. Wählen Sie in der Liste Version die Versionsnummer des referenzierten Schemas aus.
5. Klicken Sie auf OK.
Wiederholen Sie diese Schritte für jedes referenzierte Schema.
Klicken Sie auf Erstellen.

REST

Die Anfrage muss mit einem Zugriffstoken im Header Authorization authentifiziert werden. So rufen Sie ein Zugriffstoken für die aktuellen Standardanmeldedaten für Anwendungen ab: gcloud auth application-default print-access-token.

In den folgenden REST API-Beispielen wird die erste Version eines Themas erstellt.

Wenn Sie ein Thema im Standardkontext erstellen möchten, senden Sie eine POST-Anfrage an den angegebenen URI mit der Methode 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

Wenn Sie einen bestimmten Kontext verwenden, können Sie ihn alternativ mit der Methode projects.locations.schemaRegistries.contexts.subjects.versions.create in den URI der Subjektsammlung einfügen:

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

Ersetzen Sie Folgendes:

PROJECT_ID (erforderlich): Ihre Google Cloud-Projekt-ID.
LOCATION (erforderlich): Die Google Cloud Region, in der die Schema-Registry vorhanden ist.
REGISTRY_ID (erforderlich): Die ID der Zielschemaregistrierung.
CONTEXT_ID (optional): Die ID des Kontexts, der das Subjekt enthält. Verwenden Sie . für den Standardkontext, wenn Sie dies explizit angeben möchten. Andernfalls lassen Sie /contexts/CONTEXT_ID weg, um den Standardkontext implizit zu verwenden.

Der Name muss mit einem Buchstaben beginnen und darf nur Buchstaben, Ziffern und die folgenden Sonderzeichen enthalten: Bindestriche -, Punkte ., Unterstriche _, Tilden ~, Prozentzeichen % oder Pluszeichen +. Der Name eines Kontexts kann nicht geändert werden.
SUBJECT_ID (erforderlich): Die ID des neuen Themas, unter dem die erste Version erstellt werden soll.

Der Name muss mit einem Buchstaben beginnen und darf nur Buchstaben, Ziffern und die folgenden Sonderzeichen enthalten: Bindestriche -, Punkte ., Unterstriche _, Tilden ~, Prozentzeichen % oder Pluszeichen +. Der Name eines Subjekts kann nicht geändert werden.

Anfragetext:

Fügen Sie dem Anfragetext ein JSON-Objekt mit den Schemadetails hinzu:

{
  "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
}

Ersetzen Sie Folgendes:

YOUR_SCHEMA_DEFINITION_STRING (erforderlich): Ein String mit der Nutzlast der eigentlichen Schemadefinition.

Die Namen der Schematafelder dürfen keine vertraulichen Informationen wie personenidentifizierbare Informationen oder Sicherheitsdaten enthalten.
schemaType (optional): Der Typ des Schemas. Kann AVRO oder PROTOBUF sein. Wenn keine Angabe gemacht wird, ist der Standardwert AVRO.
references (optional): Ein Array von Objekten, die alle Schemas definieren, auf die in diesem Schema verwiesen wird.
- REFERENCE_NAME: Der Name, der verwendet wird, um in der Definition dieses Schemas auf das andere Schema zu verweisen.
- REFERENCED_SUBJECT_ID: die Subjekt-ID des Schemas, auf das verwiesen wird.
- REFERENCED_VERSION_NUMBER: Die spezifische Versionsnummer des Schemas des referenzierten Subjekts.
versionId, schemaId: optionale Felder, die in der Regel vom Dienst verarbeitet werden. Bei der ersten Version eines Themas ist versionId „1“.

Wenn die Anfrage erfolgreich ist und das Schema gültig ist und die Kompatibilitätsprüfungen besteht, sofern konfiguriert, gibt die API den Statuscode 200 OK zurück. Der Antworttext enthält die Schema-ID, die von der erstellten Version verwendet wird. Diese unterscheidet sich von der Versions-ID.

Weitere Informationen finden Sie in der REST API-Dokumentation.

Nächste Schritte

Apache Kafka® ist eine eingetragene Marke der Apache Software Foundation oder deren Tochtergesellschaften in den USA und/oder anderen Ländern.