Richtlinien zum Benennen einer Google Cloud Managed Service for Apache Kafka-Ressource

Eine Google Cloud -Ressource ist eine Komponente, die Sie in der Google Clouderstellen oder verwenden. Diese Ressourcen bilden die Bausteine Ihrer Anwendungen und Systeme, die auf der Plattform ausgeführt werden.

Zu den Ressourcen in Managed Service for Apache Kafka gehören:

  • Cluster

  • Thema

  • Nutzergruppe

  • ACL

  • Schema-Registry

  • Kontext (innerhalb einer Schema-Registry)

  • Subjekt (innerhalb einer Schema-Registry oder eines Kontexts)

  • Version (Versionen eines Schemas unter einem Subjekt)

  • Schema (durch ID identifiziert, einem oder mehreren Themen und Versionen zugeordnet)

Weitere Informationen zur allgemeinen Benennung von Google Cloud Ressourcen finden Sie unter Ressourcennamen. Die Schema-Registry-API für Managed Service for Apache Kafka wurde für die Kompatibilität mit einer vorhandenen Open-Source-API entwickelt. Daher können einige Namenskonventionen von typischen API-Standards abweichen.

Format der Ressourcennamen

Hier sind die Formate für die verschiedenen Ressourcen:

  • Cluster: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}

  • Thema: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}

  • Verbrauchergruppe: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/consumerGroup/{CONSUMER_GROUP_ID}

  • ACL: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/acl/{ACL_ID}

  • Schema-Registry: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}

  • Kontext: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}

  • Betreff:

    • Im Standardkontext: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}
    • In einem bestimmten Kontext: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}

  • Schema (identifiziert durch ID):

    • Im Standardkontext: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID}
    • In einem bestimmten Kontext: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}

  • Version (anhand der Versionsnummer unter einem Thema identifiziert):

    • Im Standardkontext: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
    • In einem bestimmten Kontext: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}

Die einzelnen Komponenten werden in den folgenden Abschnitten beschrieben.

Projekt-ID

Der Wert muss die Projekt-ID oder Projektnummer sein, die in der Google Cloud Console verfügbar ist. my-cool-project ist beispielsweise eine Projekt-ID, während 123456789123 eine Projektnummer ist.

Standort

Der Wert muss einer der unterstützten Managed Service for Apache Kafka-Standorte sein. Eine Liste der verfügbaren Standorte finden Sie unter Managed Service for Apache Kafka-Standorte.

ID

ID ist das letzte Segment im Ressourcenpfad. Variablen wie {CLUSTER_ID}, {TOPIC_ID}, {CONSUMER_GROUP_ID}, {SCHEMA_REGISTRY_ID}, {CONTEXT_ID} und {SUBJECT_ID} müssen den folgenden Richtlinien entsprechen:

  • Darf nicht mit dem String goog beginnen

  • Muss mit einem Buchstaben beginnen

  • Längenbeschränkungen:

    • Cluster-IDs: enthalten zwischen 3 und 53 Zeichen.

    • Thema, Consumer-Gruppen-IDs: Beliebige Länge, die von Apache Kafka zugelassen wird. Namen von Apache Kafka-Themen dürfen maximal 249 Zeichen lang sein.

    • Schema-Registry-ID: enthält bis zu 255 Zeichen.

    • Kontext-ID: enthält bis zu 255 Zeichen.

    • Subjekt-ID: enthält bis zu 255 UTF‑8-Bytes.

  • Zeichenbeschränkungen:

    • Cluster-IDs: Müssen mit dem regulären Ausdruck ^[a-z]([-a-z0-9]*[a-z0-9])? übereinstimmen. Das bedeutet, dass nur Kleinbuchstaben, Ziffern und Bindestriche verwendet werden dürfen. Sie muss mit einem Buchstaben beginnen und darf nicht mit einem Bindestrich enden.

    • Themen- und Nutzergruppen-IDs: Die Validierung erfolgt durch Kafka. Zulässige Zeichen sind `[a-zA-Z0-9.-], einschließlich alphanumerischer ASCII-Zeichen, Punkte (.), Unterstriche () und Bindestriche (-).

    • Schema-Registry-ID: Buchstaben (Groß- oder Kleinbuchstaben), Ziffern und Unterstriche _.

    • Kontext-ID: Buchstaben (Groß- oder Kleinbuchstaben), Ziffern und die folgenden Sonderzeichen: Bindestriche -, Punkte ., Unterstriche _, Tilden ~, Prozentzeichen % oder Pluszeichen +.

    • Subjekt-ID: Buchstaben (Groß- oder Kleinbuchstaben), Ziffern und die folgenden Sonderzeichen: Bindestriche -, Punkte ., Unterstriche _, Tilden ~, Prozentzeichen % oder Pluszeichen +.

Sonderzeichen

Sie können die im vorherigen Abschnitt aufgeführten Sonderzeichen in Ressourcen-IDs ohne URL-Codierung verwenden. Sie müssen jedoch dafür sorgen, dass alle anderen Sonderzeichen, die in URLs verwendet werden, richtig codiert oder decodiert werden.

mi-tópico ist beispielsweise eine ungültige ID, wenn ó kein zulässiges Zeichen für diesen bestimmten Ressourcentyp ist. mi-topico wäre jedoch gültig, wenn nur lateinische Grundbuchstaben zulässig sind. Dieses Format ist wichtig, wenn Sie REST-Aufrufe ausführen.

Wenn Sie auf ein Thema aus den Kafka-Clientbibliotheken verweisen, wird der vollständige Ressourcenpfad nicht verwendet. Es wird nur der Themenname selbst verwendet. Wenn Sie mit Schemas über Kafka-Clientintegrationen wie Serializer oder Deserializer interagieren, verwenden Sie in der Regel den Betreffnamen anstelle des vollständigen Ressourcenpfads.

Strategien für die Benennung von Themen

Bei der Arbeit mit der Schema-Registry, insbesondere mit Kafka-Clientintegrationen wie Serializern und Deserializern, ist der Betreffname von entscheidender Bedeutung. Die Strategie zur Benennung von Themen bestimmt, wie ein Schema in der Schema-Registry registriert und daraus abgerufen wird. Verschiedene Strategien bieten unterschiedliche Flexibilitätsgrade und Kontrollmöglichkeiten für die Schemaentwicklung.

Sie können die Strategie für die Benennung von Themen konfigurieren, indem Sie das Attribut key.subject.name.strategy oder value.subject.name.strategy in der Konfiguration Ihres Kafka-Clients festlegen.

TopicNameStrategy

Dies ist die Standardstrategie für Open-Source-Kafka-Clientbibliotheken.

Der Betreffname wird direkt aus dem Namen des Kafka-Themas abgeleitet und mit key für Nachrichtenschlüssel oder value für Nachrichtenwerte ergänzt. Wenn auto.register.schema auf true gesetzt ist, verwenden Producer-Clients topicName-value oder topicName-key für ein Thema mit dem Namen topicName.

Hier sind einige Beispiele:

  • Name des Themas: orders
  • Betreff für Nachricht: orders-value
  • Betreff für Nachrichtenschlüssel: orders-key

Hier finden Sie eine Liste der Vorteile der Verwendung von TopicNameStrategy:

  • Da es sich um eine einfache Strategie handelt, eignet sie sich für viele Anwendungsfälle.

  • Schemas sind direkt mit einem Thema verknüpft. So können Sie die Datensatztypen innerhalb eines einzelnen Themas unabhängig voneinander weiterentwickeln.

Im Folgenden finden Sie eine Liste der Nachteile der Verwendung von TopicNameStrategy:

  • Jedes Thema kann effektiv nur einen Nachrichtentyp verarbeiten, der auf dem Werteschema basiert. Das liegt daran, dass der Betreffname an den Namen des Themas gebunden ist. Wenn Sie verschiedene Arten von Datensätzen an dasselbe Thema senden müssen, funktioniert diese Strategie nicht.

RecordNameStrategy

Bei dieser Strategie wird der voll qualifizierte Klassenname des Avro- oder Protobuf-Datensatzes als Betreffname verwendet.

Hier sind einige Beispiele:

  • Avro-Schemaname: com.example.data.Customer
  • Name der Protobuf-Nachricht: com.example.data.Order
  • Betreff für das customer-Schema: com.example.data.Customer
  • Betreff für das order-Schema: com.example.data.Order

Hier finden Sie eine Liste der Vorteile der Verwendung von RecordNameStrategy:

  • Da der Betreffname nicht an das Thema gebunden ist, können Sie verschiedene Arten von Datensätzen an dasselbe Kafka-Thema senden. Das ist möglich, solange jeder Datensatztyp einen eigenen eindeutigen vollständig qualifizierten Namen und ein entsprechendes registriertes Schema hat.

  • Ein Schema für einen bestimmten Datensatztyp wie com.example.common.Address kann für mehrere Themen verwendet werden. Die Entwicklung wird zentral unter einem einzelnen Thema verwaltet.

Im Folgenden finden Sie eine Liste der Nachteile der Verwendung von RecordNameStrategy:

  • Sie müssen für alle Themen, die einen bestimmten Datensatztyp verwenden, dasselbe Thema und dieselbe Version verwenden. Das kann einschränkend sein, wenn Sie verschiedene Versionen desselben Datensatztyps in verschiedenen Themen benötigen.

TopicRecordNameStrategy

Diese Strategie kombiniert Aspekte von TopicNameStrategy und RecordNameStrategy.

Der Betreffname ist eine Kombination aus dem Namen des Kafka-Themas und dem vollständig qualifizierten Klassennamen des Datensatzes, formatiert als TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.

Hier sind einige Beispiele:

  • Thema: user-events

  • Vollständig qualifizierter Name: com.example.events.PageView

  • Name des Themas für diese Kombination: user-events-com.example.events.PageView

  • Anderes Thema: product-interactions

  • Vollständig qualifizierter Name: com.example.events.PageView

  • Name des Themas für diese Kombination: product-interactions-com.example.events.PageView

Hier finden Sie eine Liste der Vorteile der Verwendung von TopicRecordNameStrategy:

  • Ähnlich wie bei RecordNameStrategy können Sie verschiedene Arten von Datensätzen an dasselbe Thema senden.

  • Im Gegensatz zu RecordNameStrategy können Sie mit dieser Strategie das Schema für einen bestimmten Datensatztyp unabhängig in jedem Thema weiterentwickeln. Das bedeutet, dass sich my-topic-com.example.project.MyRecord anders entwickeln kann als another-topic-com.example.project.MyRecord.

Im Folgenden finden Sie eine Liste der Nachteile der Verwendung von TopicRecordNameStrategy:

  • Betreffnamen können aufgrund der Kombination aus Themenname und voll qualifiziertem Datensatznamen sehr lang werden.
Apache Kafka® ist eine eingetragene Marke der Apache Software Foundation oder ihrer verbundenen Unternehmen in den USA und/oder anderen Ländern.