Neue Schemaversion registrieren

Nachdem Sie ein Thema erstellt haben, können Sie ihm neue Versionen hinzufügen. Dieser Vorgang wird als Registrieren einer neuen Schemaversion bezeichnet. Jede neue Version stellt eine Weiterentwicklung des Schemas dar, das diesem Thema zugeordnet ist.

Ein Thema kann mehrere Versionen haben. Versionen innerhalb eines Subjekts folgen konfigurierbaren Kompatibilitätsregeln, um eine sichere Schemaentwicklung zu gewährleisten. Ein Thema kann beispielsweise erfordern, dass alle Änderungen abwärtskompatibel sind. Ein Beispiel für eine abwärtskompatible Änderung ist das Hinzufügen eines optionalen Felds. Das Hinzufügen eines Pflichtfelds gilt als nicht abwärtskompatible Änderung. Wenn Ihr Thema für die Abwärtskompatibilität konfiguriert ist, ist diese Änderung nicht zulässig. Wenn Ihr Thema jedoch für die Vorwärtskompatibilität konfiguriert ist, ist das Hinzufügen eines Pflichtfelds akzeptabel.

Kompatibilitätsprüfungen sind nicht rückwirkend. Wenn Kompatibilitätsregeln für ein Subjekt oder eine Schema-Registry geändert werden, werden bereits vorhandene Versionen im Subjekt nicht noch einmal anhand der neuen Regeln validiert. Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilitätstyp.

Erforderliche Rollen und Berechtigungen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Managed Kafka Schema Registry Editor (roles/managedkafka.schemaRegistryEditor) für Ihr Projekt oder die spezifische Schemaregistrierung und das Thema zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Registrieren einer Schemaversion für ein Thema 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 Registrieren einer Schemaversion für ein Thema erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um eine Schemaversion für ein Thema zu registrieren:

  • Erteilen 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 übergeordnete Rolle Managed Kafka Schema Registry Admin (roles/managedkafka.schemaRegistryAdmin) enthält diese Berechtigungen ebenfalls.

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

Neue Schemaversion registrieren

So registrieren Sie eine neue Schemaversion:

Console

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

    Zu Schemaregistrierungen

  2. Klicken Sie auf den Namen der Schemaregistrierung, in der Sie eine neue Schemaversion registrieren möchten.

  3. Klicken Sie unter Subjekte in dieser Schema-Registry auf den Namen des Subjekts.

  4. Klicken Sie auf der Seite Themendetails auf Version erstellen.

  5. Im Feld Schemadefinition wird die Definition der neuesten Version angezeigt. Aktualisieren Sie die Definition in diesem Feld für die neue Version. Die Namen der Schemafelder dürfen keine vertraulichen Informationen wie personenidentifizierbare Informationen oder Sicherheitsdaten enthalten.

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

  7. Optional: Wenn Sie prüfen möchten, ob das neue Schema mit der vorherigen Version kompatibel ist, klicken Sie auf Kompatibilität prüfen.

    Wenn das Schema kompatibel ist, wird ein -Häkchen angezeigt. Andernfalls wird eine Fehlermeldung angezeigt. Beheben Sie in diesem Fall den Fehler und klicken Sie noch einmal auf Kompatibilität prüfen.

    Die durchgeführte Kompatibilitätsprüfung hängt vom Kompatibilitätstyp des Subjekts ab.

  8. Klicken Sie auf Erstellen. Wenn die Schemadefinition gültig ist und die Kompatibilitätsprüfungen des Subjekts besteht, wird die neue Version unter Alle Versionen angezeigt.

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.

Wenn Sie eine neue Schemaversion für ein Subjekt im Standardkontext registrieren möchten, senden Sie eine POST-Anfrage an den entsprechenden URI mit der Methode 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

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

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

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 . (einen einzelnen Punkt) für den Standardkontext, wenn Sie ihn explizit angeben möchten. Andernfalls lassen Sie /contexts/CONTEXT_ID weg, um den Standardkontext implizit zu verwenden.
  • SUBJECT_ID (erforderlich): Die ID des Themas, unter dem die neue Version erstellt werden soll.

Anfragetext:

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

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

Ersetzen Sie Folgendes:

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

  • schemaType (optional, innerhalb des schema-Objekts): der Typ des Schemas. Kann AVRO oder PROTOBUF sein. Wenn keine Angabe gemacht wird, ist der Standardwert AVRO.

  • references (optional, innerhalb des schema-Objekts): 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: Der vollständig qualifizierte Subjektname des Schemas, auf das verwiesen wird. Beispiel: projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject.

    • REFERENCED_VERSION_NUMBER: Die spezifische Versionsnummer (Ganzzahl) des Schemas des referenzierten Subjekts.

  • versionId, schemaId: optionale Felder, die in der Regel vom Dienst verarbeitet werden. Bei der Registrierung der Schemaversion weist der Dienst die nächste verfügbare Versionsnummer zu.

Wenn die Anfrage erfolgreich ist, gibt die API den Statuscode 200 OK und einen Antworttext mit der Schema-ID zurück.

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.