سجلات المخططات لـ Kafka ClickPipe

يدعم ClickPipes التكامل مع سجل مخططات لفك ترميز قيم السجلات المُرمَّزة بتنسيقَي Avro وProtobuf ومفاتيح Kafka المهيكلة.

يدعم Kafka ClickPipes فئتين من سجلات المخططات:

• السجلات المتوافقة مع Confluent: أي سجل متوافق مع واجهة برمجة تطبيقات Confluent Schema Registry، مثل Confluent Schema Registry نفسه وRedpanda Schema Registry. يدعم Avro وProtobuf.
• AWS Glue Schema Registry: لبيانات Avro المُسلسلة باستخدام AWS Glue SerDe، والتي تأتي عادةً من Amazon MSK.

لا يدعم ClickPipes Azure Schema Registry حتى الآن. إذا كنت بحاجة إلى دعمه، فتواصل مع فريقنا.

للتكامل مع سجل مخططات أثناء إعداد ClickPipes، يجب استخدام أحد الأساليب التالية:

1. توفير مسار كامل إلى موضوع المخطط (مثل: https://registry.example.com/subjects/events)
   • اختياريًا، يمكن الإشارة إلى إصدار محدد بإضافة /versions/[version] إلى URL (وإلا سيسترجع ClickPipes أحدث إصدار).
2. توفير مسار كامل إلى معرّف المخطط (مثل: https://registry.example.com/schemas/ids/1000)
3. توفير URL الجذر لسجل مخططات (مثل: https://registry.example.com)

يتصل ClickPipes بسجل مخططات عبر HTTPS باستخدام عنوان URL الذي توفّره. ولا يشترط أن يكون سجل مخططات متاحًا عبر الإنترنت العام.

إذا كان الوصول إلى وسطاء Kafka يتم عبر نقطة نهاية خاصة عكسية (AWS PrivateLink أو GCP Private Service Connect)، فيمكن لسجل مخططات استخدام الاتصال الخاص نفسه. ويحلّ ClickPipes اسم مضيف السجل عبر DNS الخاص بنقطة النهاية الخاصة العكسية، لذا يمكن الوصول إلى سجل مستضاف بشكل خاص إلى جانب الوسطاء لديك طالما أن اسم مضيفه يُحل إلى عناوين IP الخاصة بنقطة النهاية الخاصة العكسية (عبر دعم DNS الخاص بنقطة النهاية أو عبر تعيين DNS خاص مخصّص).

ضع ما يلي في اعتبارك:

• يجب أن يستخدم عنوان URL لسجل مخططات https://.
• إذا كان اسم مضيف السجل يُحل إلى عنوان خاص، فيجب أن يكون الوصول إليه ممكنًا عبر نقطة نهاية خاصة عكسية محددة لـ ClickPipe؛ وإلا فسيفشل فحص الاتصال أثناء الإعداد.

يسترجع ClickPipes المخطط من سجل مخططات المُعدّ ويطبّقه ديناميكيًا.

• إذا كان هناك معرّف المخطط مضمن في قيمة السجل، فسيستخدمه لاسترجاع المخطط.
• إذا لم يكن هناك معرّف المخطط مضمن في قيمة السجل، فسيستخدم معرّف المخطط أو اسم الموضوع المحدد في إعداد ClickPipe لاسترجاع المخطط.
• إذا كُتبت قيمة السجل بدون معرّف المخطط مضمن، ولم يتم تحديد معرّف المخطط أو اسم الموضوع في إعداد ClickPipe، فلن يتم استرجاع المخطط وسيتم تخطي الرسالة مع تسجيل SOURCE_SCHEMA_ERROR في جدول الأخطاء الخاص بـ ClickPipes.
• إذا لم تكن قيمة السجل مطابقة للمخطط، فسيتم تخطي الرسالة مع تسجيل DATA_PARSING_ERROR في جدول الأخطاء الخاص بـ ClickPipes.
• بالنسبة إلى مخططات Protobuf فقط: سيحمّل ClickPipes أي مخططات مستوردة مُعرّفة كتبعيات. أما مخططات Avro ذات المراجع الخارجية فليست مدعومة بعد.

عند تهيئة التعيينات لحقول مثل _key.id، يحل ClickPipes معرّف المخطط المضمن في مفتاح Kafka بشكل مستقل عن قيمة السجل. يمكن للمفتاح استخدام معرّف مخطط مختلف، ولكن يجب أن يستخدم عائلة السجل نفسها وتنسيق التسلسل نفسه المستخدمين للقيمة. تُخزّن مخططات المفاتيح المحلولة مؤقتًا وتُكتشف تغييرات المخطط تلقائيًا.

إذا كانت مكوّنات الإنتاج لديك تُسلسل بيانات Avro باستخدام AWS Glue SerDe (على سبيل المثال، AWSKafkaAvroSerializer مع topic في Amazon MSK)، فيمكن لـ ClickPipes حلّ هذه المخططات مباشرةً من AWS Glue Schema Registry. يستخدم Glue تنسيق wire مختلفًا وواجهة برمجة تطبيقات مختلفة عن السجلات المتوافقة مع Confluent، لذا يُهيَّأ بشكل منفصل.

يتوفر إعداد AWS Glue Schema Registry حاليًا عبر ClickHouse Cloud console فقط. ولا يُدعم عبر واجهة برمجة تطبيقات ClickPipes أو Terraform provider.

في معالج إنشاء ClickPipe، فعّل سجل المخططات في خطوة اتصال Kafka واضبط نوع السجل على AWS Glue:

لا يوجد URL لسجل لتكوينه. يحمل كل سجل تنتجه Glue SerDe معرّف إصدار مخططه الخاص، ويحلّه ClickPipes باستخدام glue:GetSchemaVersion ويخزّنه مؤقتًا، بإجراء استدعاء واحد لواجهة برمجة التطبيقات لكل إصدار مخطط مميز. يُعالَج تطور المخطط تلقائيًا: فعندما تنتقل السجلات إلى إصدار مخطط جديد أثناء التدفق، يُحلّ عند ظهوره أول مرة.

استخدم الخيار الأنسب لإعدادك من بين الخيارين. الخيار أ هو الخيار الشائع في حالة Amazon MSK.

إذا كان Kafka ClickPipe لديك يستخدم IAM للمصادقة مع MSK بالفعل، فسيستخدم ClickPipes هوية IAM نفسها لقراءة السجل. اترك حقل IAM role ARN فارغًا وأضف العبارة التالية إلى أذونات الهوية:

• IAM role: أضف العبارة إلى سياسة الأذونات الخاصة بالدور المُعدّ لـ MSK.
• IAM credentials: أضف العبارة إلى سياسة أذونات كيان IAM المرتبط بمفتاح الوصول.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ClickPipesGlueSchemaRegistryRead",
      "Effect": "Allow",
      "Action": ["glue:GetSchemaVersion"],
      "Resource": "*"
    }
  ]
}

بالنسبة إلى المصادقة المستندة إلى الدور، لا حاجة إلى تغيير سياسة الثقة؛ فعلاقة الثقة المُعدّة لـ MSK تغطي هذا الوصول بالفعل. لا تستخدم بيانات اعتماد IAM سياسة ثقة للدور.

استخدم هذا الخيار إذا كان الوسيط لديك لا يستخدم مصادقة IAM ‏(SASL/SCRAM أو SASL/PLAIN أو mTLS)، أو إذا كان السجل موجودًا في حساب AWS مختلف عن حساب الوسيط.

الحصول على ARN لدور IAM لخدمة ClickHouse

افتح الخدمة، وحدد علامة التبويب الإعدادات، ثم مرر إلى قسم معلومات أمان الشبكة، وانسخ قيمة معرّف دور الخدمة (IAM)، وهي ARN بالصيغة arn:aws:iam::123456789012:role/CH-S3-example-service-Role. يُشار إلى هذه القيمة أدناه باسم {ClickHouse_IAM_ARN}. لكل خدمة ClickHouse منشورة على AWS دور خاص بها، لذا تختلف هذه القيمة من خدمة إلى أخرى.

إنشاء دور IAM للسجل

أنشئ دور IAM في حساب AWS الخاص بك. يجب أن يبدأ اسم الدور بـ ClickHouseAccessRole-.

تكوين سياسة الثقة

استبدل {ClickHouse_IAM_ARN} بالقيمة من الخطوة السابقة.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "{ClickHouse_IAM_ARN}"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

تكوين سياسة الأذونات

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ClickPipesGlueSchemaRegistryRead",
      "Effect": "Allow",
      "Action": ["glue:GetSchemaVersion"],
      "Resource": "*"
    }
  ]
}

تكوين ClickPipe

الصق ARN للدور الجديد في حقل ARN لدور IAM في المعالج.

• Avro فقط. لا يُدعم JSON Schema وProtobuf عبر Glue SerDe.
• مصادر Kafka فقط. لا يمكن لـ ClickPipes في Kinesis استخدام سجل Glue.

تنطبق القواعد التالية على كلٍّ من السجلات المتوافقة مع Confluent وAWS Glue Schema Registry. وهي تحكم المواءمة بين مخطط القيمة المسترجَع وجدول الوجهة في ClickHouse، وتنطبق أيضًا على حقول السجل أو الرسالة المعيَّنة من مفاتيح مهيكلة ذات البادئة _key.:

• إذا كان المخطط يحتوي على حقل غير مُدرَج في مواءمة وجهة ClickHouse، فسيتم تجاهل هذا الحقل.
• إذا كان المخطط يفتقد حقلاً مُعرَّفًا في مواءمة وجهة ClickHouse، فسيُملأ عمود ClickHouse بقيمة "صفرية"، مثل 0 أو سلسلة فارغة. لاحظ أن تعبيرات DEFAULT غير مدعومة.
• إذا كان حقل المخطط وعمود ClickHouse غير متوافقين، فستفشل عمليات إدراج ذلك الصف/تلك الرسالة، وسيُسجَّل الفشل في جدول الأخطاء الخاص بـ ClickPipes. لاحظ أن بعض التحويلات الضمنية مدعومة (على سبيل المثال، بين الأنواع الرقمية)، ولكن ليس جميعها (على سبيل المثال، لا يمكن إدراج حقل سجل Avro في عمود ClickHouse من النوع Int32).