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

كيفية دمج ClickPipes مع سجل مخططات لإدارة المخططات.

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

​

سجلات المخططات المدعومة لـ Kafka ClickPipes

يدعم 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 حتى الآن. إذا كنت بحاجة إلى دعمه، فتواصل مع فريقنا.

​

السجلات المتوافقة مع Confluent

​

الإعداد

للتكامل مع سجل مخططات أثناء إعداد 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 بشكل مستقل عن قيمة السجل. يمكن للمفتاح استخدام معرّف مخطط مختلف، ولكن يجب أن يستخدم عائلة السجل نفسها وتنسيق التسلسل نفسه المستخدمين للقيمة. تُخزّن مخططات المفاتيح المحلولة مؤقتًا وتُكتشف تغييرات المخطط تلقائيًا.

​

AWS Glue Schema Registry

إذا كانت مكوّنات الإنتاج لديك تُسلسل بيانات 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.

Avro فقط. تُدعم سجلات AWS Glue لتنسيق Avro فقط. يمكن لـ Glue SerDe أيضًا تأطير JSON وProtobuf، لكن ClickPipes لا يدعمهما، ويُرفضان عند إنشاء pipe.

​

الإعداد

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

الحقل	مطلوب	الوصف	مثال
نوع السجل	نعم	اختر AWS Glue	AWS Glue
منطقة AWS	نعم	المنطقة التي يوجد فيها سجل Glue. يجب أن تطابق منطقة السجل تمامًا.	us-east-1
اسم السجل	نعم	اسم سجل Glue. تُرفض المخططات التي يُحلّ مرجعها إلى سجل مختلف، لذا سيظهر أي خطأ مطبعي عند قيام ClickPipes بحل إصدار مخطط.	my-glue-registry
ARN لدور IAM	مشروط	دور مخصص للوصول إلى السجل. وهو اختياري إذا كان الوسيط يستخدم مصادقة IAM، ومطلوب في غير ذلك.	arn:aws:iam::123456789012:role/ClickHouseAccessRole-glue

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

​

إعداد IAM

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

​

الخيار أ: إعادة استخدام هوية IAM الخاصة بالوسيط

إذا كان 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 مختلف عن حساب الوسيط.

للنشرات على AWS فقط. يتطلب هذا الخيار خدمة ClickHouse Cloud منشورة على AWS، لأنه يعتمد على دور AWS IAM الخاص بالخدمة. إذا كانت خدمتك تعمل على GCP أو Azure ولم يكن الوسيط يستخدم مصادقة IAM، فلن تتمكن من تكوين دور مخصص للسجل.

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

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

2. إنشاء دور 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": "*"
       }
     ]
   }
   
3. تكوين ClickPipe

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

نطاق موارد IAM. تتبع هذه الأمثلة سياسة AWS الموثقة لمكونات إلغاء التسلسل وسياسة AWS المُدارة AWSGlueSchemaRegistryReadonlyAccess، وكلتاهما تمنح الإذن glue:GetSchemaVersion على "*". يتحقق ClickPipes بشكل مستقل من مطابقة كل مخطط تم حله مع اسم السجل الذي كوّنته، ويرفض الإصدارات الواردة من أي سجل آخر.

​

استكشاف الأخطاء وإصلاحها

الخطأ	السبب والحل
access denied retrieving schema version …: check the IAM role grants glue:GetSchemaVersion	تفتقر هوية IAM المستخدمة للوصول إلى السجل إلى صلاحية glue:GetSchemaVersion. بالنسبة إلى الوصول المستند إلى الدور، قد لا تتضمن سياسة الثقة للدور معرّف دور خدمتك أيضًا. أعد التحقق من إعداد IAM أعلاه.
… is not authorized to perform: sts:AssumeRole on resource: …	تشير سياسة الثقة إلى الكيان الأساسي الخطأ. يتضمن الخطأ الدور المحدد الذي حاول تولّي الدور. استخدم هذه القيمة في سياسة الثقة.
schema version … not found in Glue schema registry	تشير السجلات إلى إصدار مخطط غير موجود في الحساب أو المنطقة المُعدَّين. تأكد من مطابقة منطقة AWS لمنطقة السجل.
schema version … belongs to Glue registry "X", but the pipe is configured for registry "Y"	يسجّل المنتجون لديك المخططات في سجل مختلف عن السجل المحدد في الـ pipe. صحح اسم السجل، أو وجّه المنتجين إلى السجل الصحيح.
the AWS Glue schema registry only supports the Avro format	لا تدعم Glue pipes سوى تنسيق Avro. لا يتم دعم JSON وProtobuf عبر Glue SerDe.

​

القيود

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