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

Eine Google Cloud Ressource ist eine Komponente, die Sie in der erstellen oder verwenden der Google Cloud. 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 (in einer Schema-Registry)

  • Subjekt (in einer Schema-Registry oder einem Kontext)

  • Version (Versionen eines Schemas unter einem Subjekt)

  • Schema (durch ID identifiziert, mit einem oder mehreren Subjekten und Versionen verknüpft)

Weitere Informationen zur allgemeinen Google Cloud Benennung von Ressourcen finden Sie unter Ressourcennamen. Die Schema-Registry API für Managed Service for Apache Kafka wurde so konzipiert, dass sie mit einer vorhandenen Open-Source-API kompatibel ist. Daher können einige Namenskonventionen von den typischen API-Standards abweichen.

Format für die Benennung von Ressourcen

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}

  • Nutzergruppe: 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}

  • Subjekt:

    • 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 (durch ID identifiziert):

    • 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 (durch Versionsnummer unter einem Subjekt 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}

Im Folgenden wird jede Komponente in den nächsten Abschnitten aufgeschlüsselt.

Projekt-ID

Der Wert muss die Projekt-ID oder Projektnummer sein, die in der Google Cloud console verfügbar ist. Beispiel: my-cool-project ist 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:

  • Beginnen Sie nicht mit der Zeichenfolge goog.

  • Muss mit einem Buchstaben beginnen

  • Längenbeschränkungen:

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

    • Themen- und Nutzergruppen-IDs: Jede von Apache Kafka zulässige Länge. Apache Kafka-Themennamen sind auf 249 Zeichen beschränkt.

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

  • Zeichenbeschränkungen:

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

    • Themen- und Nutzergruppen-IDs: Die Validierung wird von Kafka durchgeführt. 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 sicherstellen, dass alle anderen Sonderzeichen bei der Verwendung in URLs richtig codiert oder decodiert werden.

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

Wenn Sie ein Thema aus den Kafka-Clientbibliotheken referenzieren, wird nicht der vollständige Ressourcenpfad verwendet. Es wird nur der Themenname verwendet. Wenn Sie mit Schemas über Kafka-Clientintegrationen wie Serialisierer oder Deserialisierer interagieren, verwenden Sie in der Regel den Subjektnamen anstelle des vollständigen Ressourcenpfads.

Strategien für die Benennung von Subjekten

Bei der Arbeit mit der Schema-Registry, insbesondere mit Kafka-Clientintegrationen wie Serialisierern und Deserialisierern, ist der Subjektname entscheidend. Die Strategie für die Benennung von Subjekten bestimmt, wie ein Schema in der Schema-Registry registriert und daraus abgerufen wird. Verschiedene Strategien bieten unterschiedliche Flexibilitäts- und Kontrollstufen für die Schemaentwicklung.

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

TopicNameStrategy

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

Der Subjektname wird direkt aus dem Kafka-Themennamen abgeleitet und mit key für Nachrichtenschlüssel oder value für Nachrichtenwerte angehängt. 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:

  • Themenname: orders
  • Subjekt für Nachrichtenwerte: orders-value
  • Subjekt für Nachrichtenschlüssel: orders-key

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

  • Es ist eine einfache Strategie, die für viele Anwendungsfälle geeignet ist.

  • 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 Wertschema basiert. Das liegt daran, dass der Subjektname an den Themennamen 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 Subjektname verwendet.

Hier sind einige Beispiele:

  • Avro-Schemaname: com.example.data.Customer
  • Protobuf-Nachrichtenname: com.example.data.Order
  • Subjekt für das customer-Schema: com.example.data.Customer
  • Subjekt für das order-Schema: com.example.data.Order

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

  • Da der Subjektname 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 Eintragstyp einen eigenen, eindeutigen, voll 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 und seine Entwicklung wird zentral unter einem einzigen Subjekt 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 Subjekt 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 Subjektname ist eine Kombination aus dem Kafka-Themennamen und dem vollständig qualifizierten Klassennamen des Datensatzes im Format TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.

Hier sind einige Beispiele:

  • Thema: user-events

  • Voll qualifizierter Name: com.example.events.PageView

  • Subjektname für diese Kombination: user-events-com.example.events.PageView

  • Ein anderes Thema: product-interactions

  • Voll qualifizierter Name: com.example.events.PageView

  • Subjektname für diese Kombination: product-interactions-com.example.events.PageView

Im Folgenden 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 voneinander 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:

  • Subjektnamen können aufgrund der Kombination aus Themenname und vollständig qualifiziertem Datensatznamen sehr lang werden.
Apache Kafka® ist eine eingetragene Marke der Apache Software Foundation oder deren Tochtergesellschaften in den USA und/oder anderen Ländern.