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 Thema)

• Schema (durch ID identifiziert, einem oder mehreren Fächern 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 sich einige Namenskonventionen von typischen API-Standards unterscheiden.

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 (anhand der 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 (anhand der Versionsnummer unter einem Betreff 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, 123456789123 eine Projektnummer.

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: Sie müssen zwischen 3 und 255 Zeichen lang sein.

  • Themen- und Consumer-Gruppen-IDs: Beliebige Länge, die von Apache Kafka zugelassen wird. Apache Kafka-Themennamen 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 dem regulären Ausdruck ^[a-z]([-a-z0-9]*[a-z0-9])? entsprechen. 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), Zahlen 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 +.

ACL-ID

Das acl_id definiert das Ressourcenmuster, auf das die ACL-Einträge angewendet werden. Alle ACL-Einträge in der ACL gelten für das in der ACL-ID codierte Ressourcenmuster.

acl_id muss wie einer der folgenden Datentypen strukturiert sein:

• Für ACLs im Cluster:

  • cluster

• Für ACLs für eine einzelne Ressource im Cluster:

  • topic/{RESOURCE_NAME}
  • consumerGroup/{RESOURCE_NAME}
  • transactionalId/{RESOURCE_NAME}

• Für ACLs für alle Ressourcen, die mit einem Präfix übereinstimmen:

  • topicPrefixed/{RESOURCE_NAME}
  • consumerGroupPrefixed/{RESOURCE_NAME}
  • transactionalIdPrefixed/{RESOURCE_NAME}

• Für ACLs für alle Ressourcen eines bestimmten Typs (Platzhalter):

  • allTopics (steht für topic/*)
  • allConsumerGroups (steht für consumerGroup/*)
  • allTransactionalIds (steht für transactionalId/*)

{RESOURCE_NAME}: Der Name der jeweiligen Ressource.

Beispiele:

• So erteilen Sie Berechtigungen für ein bestimmtes Thema my-topic: topic/my-topic
• So gewähren Sie Berechtigungen für alle Themen, die mit test- beginnen: topicPrefixed/test-
• So erteilen Sie Berechtigungen für den Cluster selbst: cluster
• So gewähren Sie Berechtigungen für eine Gruppe: allConsumerGroups
• So gewähren Sie Berechtigungen für eine bestimmte Transaktions-ID tx-id: transactionalId/tx-id

Sonderzeichen

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

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

Wenn Sie auf ein Thema aus den Kafka-Clientbibliotheken verweisen, wird nicht der vollständige Ressourcenpfad 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

Wenn Sie mit der Schema-Registry arbeiten, 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 Schemaregistrierung registriert und daraus abgerufen wird. Verschiedene Strategien bieten unterschiedliche Flexibilitäts- und Kontrollgrade 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 Nachrichtenwerte: orders-value
• Betreff für Nachrichtenschlüssel: orders-key

Im Folgenden 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 an ein Thema gebunden. 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 vollständig qualifizierte Klassenname des Avro- oder Protobuf-Datensatzes als Betreffname verwendet.

Hier sind einige Beispiele:

• Name des Avro-Schemas: 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

Im Folgenden 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, sofern für jeden Datensatztyp ein eindeutiger vollständig qualifizierter Name und ein entsprechendes Schema registriert sind.

• 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 einzigen 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

Bei dieser Strategie werden Aspekte von TopicNameStrategy und RecordNameStrategy kombiniert.

Der Betreffname ist eine Kombination aus dem Namen des Kafka-Themas und dem voll 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

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

• Anderes Thema: product-interactions

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

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

Hinweis :com.example.events.PageView kann sich in user-events anders entwickeln als in product-interactions.

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 innerhalb jedes Themas 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 vollständig qualifiziertem Datensatznamen recht lang werden.

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