Neue Schemaversion registrieren

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

Ein Subjekt kann mehrere Versionen haben. Versionen innerhalb eines Subjekts folgen konfigurierbaren Kompatibilitätsregeln, um eine sichere Schemaentwicklung zu gewährleisten. Ein Subjekt 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 wäre eine abwärtsinkompatible Änderung. Wenn Ihr Subjekt für die Abwärtskompatibilität konfiguriert ist, ist diese Änderung nicht zulässig. Wenn Ihr Subjekt jedoch für die Aufwärtskompatibilität konfiguriert ist, ist das Hinzufügen eines Pflichtfelds zulässig.

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

Erforderliche Rollen und Berechtigungen

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

Erforderliche Berechtigungen

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

  • Gewähren Sie diese Berechtigung für den übergeordneten Kontext oder den Standardkontext: managedkafka.versions.create

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

Neue Schemaversion registrieren

Führen Sie die folgenden Schritte aus, um eine neue Schemaversion zu registrieren.

Console

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

    Zu den Schema-Registries

  2. Klicken Sie auf den Namen der Schema-Registry, 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 Subjektdetails 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 Subjekt das Subjekt 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. Kompatibilitätstyp.

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

REST

Die Anfrage muss mit einem Zugriffstoken im Authorization-Header 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 projects.locations.schemaRegistries.subjects.versions.create Methode:

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, fügen Sie alternativ den Kontext in den URI der Versionssammlung ein und verwenden Sie die projects.locations.schemaRegistries.contexts.subjects.versions.create Methode.

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 sich die Schema-Registry befindet.
  • REGISTRY_ID (erforderlich): Die ID der Ziel-Schema Registry.
  • CONTEXT_ID (optional): Die ID des Kontexts der das Subjekt enthält. Verwenden Sie . (ein einzelner 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 Subjekts, unter dem die neue Version erstellt werden soll.

Anfragetext :

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

{
  "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 nicht angegeben, wird standardmäßig AVRO verwendet.

  • references (optional, innerhalb des schema-Objekts): Ein Array von Objekten, das alle Schemas definiert, auf die in diesem Schema verwiesen wird.

    • REFERENCE_NAME: Der Name, der verwendet wird, um auf das andere Schema innerhalb der Definition dieses Schemas zu verweisen.

    • REFERENCED_SUBJECT_ID: der voll qualifizierte Subjektname des referenzierten Schemas. 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 normalerweise vom Dienst verarbeitet werden. Beim Registrieren 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 ihrer Tochtergesellschaften in den USA und/oder anderen Ländern.