استخدام واجهة ClickHouse HTTP في Azure Data Factory

تُعد دالة الجدول azureBlobStorage طريقة سريعة ومريحة لإدخال البيانات من Azure Blob Storage إلى ClickHouse. ومع ذلك، قد لا يكون استخدامها مناسبًا دائمًا للأسباب التالية:

قد لا تكون بياناتك مخزنة في Azure Blob Storage — فقد تكون، على سبيل المثال، في Azure SQL Database أو Microsoft SQL Server أو Cosmos DB.
قد تمنع سياسات الأمان الوصول الخارجي إلى Blob Storage بالكامل — على سبيل المثال، إذا كان حساب التخزين مؤمَّنًا من دون نقطة نهاية عامة.

في مثل هذه السيناريوهات، يمكنك استخدام Azure Data Factory مع واجهة ClickHouse HTTP لإرسال البيانات من خدمات Azure إلى ClickHouse. تعكس هذه الطريقة اتجاه التدفق: فبدلًا من أن يسحب ClickHouse البيانات من Azure، يدفع Azure Data Factory البيانات إلى ClickHouse. ويتطلب هذا النهج عادةً أن يكون مثيل ClickHouse لديك متاحًا عبر الإنترنت العام.

يمكن تجنب تعريض مثيل ClickHouse لديك للإنترنت من خلال استخدام Self-hosted Integration Runtime الخاص بـ Azure Data Factory. يتيح هذا الإعداد إرسال البيانات عبر شبكة خاصة. ومع ذلك، فإن هذا خارج نطاق هذه المقالة. يمكنك العثور على مزيد من المعلومات في الدليل الرسمي: إنشاء Self-hosted Integration Runtime وتكوينه

تحويل ClickHouse إلى خدمة REST

تدعم Azure Data Factory إرسال البيانات إلى الأنظمة الخارجية عبر HTTP بتنسيق JSON. يمكننا استخدام هذه الإمكانية لإدخال البيانات مباشرةً إلى ClickHouse باستخدام واجهة ClickHouse HTTP. يمكنك معرفة المزيد في وثائق واجهة ClickHouse HTTP. في هذا المثال، نحتاج فقط إلى تحديد جدول الوجهة، وتعريف تنسيق بيانات الإدخال على أنه JSON، وتضمين خيارات للسماح بتحليل أكثر مرونة لقيم timestamp.

INSERT INTO my_table
SETTINGS 
    date_time_input_format='best_effort',
    input_format_json_read_objects_as_strings=1
FORMAT JSONEachRow

لإرسال هذا الاستعلام كجزء من طلب HTTP، ما عليك سوى تمريره كسلسلة مُرمَّزة بترميز URL إلى معلمة query في نقطة نهاية ClickHouse الخاصة بك:

https://your-clickhouse-url.com?query=INSERT%20INTO%20my_table%20SETTINGS%20date_time_input_format%3D%27best_effort%27%2C%20input_format_json_read_objects_as_strings%3D1%20FORMAT%20JSONEachRow%0A

يمكن لـ Azure Data Factory معالجة هذا الترميز تلقائيًا باستخدام الدالة المضمنة encodeUriComponent، لذلك لن تحتاج إلى القيام بذلك يدويًا.

يمكنك الآن إرسال بيانات بتنسيق JSON إلى عنوان URL هذا. يجب أن تتوافق البيانات مع بنية الجدول الهدف. إليك مثالًا بسيطًا باستخدام curl، بافتراض وجود جدول يحتوي على ثلاثة أعمدة: col_1 وcol_2 وcol_3.

curl \
    -XPOST "https://your-clickhouse-url.com?query=<our_URL_encded_query>" \
    --data '{"col_1":9119,"col_2":50.994,"col_3":"2019-06-01 00:00:00"}'

يمكنك أيضًا إرسال مصفوفة JSON من الكائنات، أو JSON Lines (كائنات JSON محددة بأسطر جديدة). يستخدم Azure Data Factory تنسيق مصفوفة JSON، وهو ما يعمل بشكل مثالي مع مُدخل JSONEachRow في ClickHouse. كما ترى، في هذه الخطوة لا تحتاج إلى القيام بأي شيء خاص من جانب ClickHouse. فواجهة HTTP توفّر بالفعل كل ما يلزم لتعمل كنقطة نهاية شبيهة بـ REST — ولا يتطلب الأمر أي تهيئة إضافية. الآن بعد أن جعلنا ClickHouse يعمل كنقطة نهاية REST، فقد حان الوقت لتهيئة Azure Data Factory لاستخدامه. في الخطوات التالية، سننشئ مثيلًا في Azure Data Factory، ونُعد خدمة مرتبطة بمثيل ClickHouse لديك، ونعرّف مجموعة بيانات لـ REST sink، وننشئ نشاط Copy Data لإرسال البيانات من Azure إلى ClickHouse.

إنشاء مثيل Azure Data Factory

يفترض هذا الدليل أن لديك إمكانية الوصول إلى حساب Microsoft Azure، وأنك أعددت بالفعل اشتراكًا ومجموعة موارد. إذا كان لديك Azure Data Factory مُعدّ بالفعل، فيمكنك تخطي هذه الخطوة بأمان والانتقال إلى الخطوة التالية باستخدام خدمتك الحالية.

سجّل الدخول إلى Microsoft Azure Portal وانقر على إنشاء مورد.
في جزء الفئات على اليسار، حدّد التحليلات، ثم انقر على Data Factory ضمن قائمة الخدمات الشائعة.
حدّد اشتراكك ومجموعة الموارد، وأدخل اسمًا لمثيل Data Factory الجديد، واختر المنطقة، واترك الإصدار على V2.
انقر على مراجعة + إنشاء، ثم انقر على إنشاء لبدء عملية النشر.

بمجرد اكتمال عملية النشر بنجاح، يمكنك البدء في استخدام مثيل Azure Data Factory الجديد.

إنشاء خدمة مرتبطة جديدة مستندة إلى REST

سجّل الدخول إلى Microsoft Azure Portal وافتح مثيل Data Factory الخاص بك.
في صفحة Overview الخاصة بـ Data Factory، انقر على Launch Studio.
من القائمة اليمنى، اختر Manage، ثم انتقل إلى Linked services، وانقر على + New لإنشاء خدمة مرتبطة جديدة.
في شريط البحث New linked service، اكتب REST، ثم اختر REST، وانقر على Continue لإنشاء مثيل لموصل REST.
في جزء تكوين الخدمة المرتبطة، أدخل اسمًا لخدمتك الجديدة، ثم انقر على حقل Base URL، وبعد ذلك انقر على Add dynamic content (لا يظهر هذا الرابط إلا عند تحديد الحقل).
في جزء المحتوى الديناميكي، يمكنك إنشاء عنوان URL مُعلَّم بالمعلمات، ما يتيح لك تحديد الاستعلام لاحقًا عند إنشاء datasets لجداول مختلفة — وهذا يجعل الخدمة المرتبطة قابلة لإعادة الاستخدام.
انقر على ”+” بجانب حقل التصفية وأضف parameter جديدًا، وسمّه pQuery، واضبط النوع على String، واضبط القيمة الافتراضية على SELECT 1. ثم انقر على Save.
في حقل expression، أدخل ما يلي ثم انقر على OK. استبدل your-clickhouse-url.com بالعنوان الفعلي لمثيل ClickHouse الخاص بك.
@{concat('https://your-clickhouse-url.com:8443/?query=', encodeUriComponent(linkedService().pQuery))}
بالعودة إلى النموذج الرئيسي، اختر Basic authentication، ثم أدخل username و password المستخدمَين للاتصال بـ واجهة ClickHouse HTTP، ثم انقر على Test connection. إذا كان كل شيء مُعدًّا بشكل صحيح، فستظهر لك رسالة نجاح.
انقر على Create لإكمال الإعداد.

يجب أن ترى الآن خدمتك المرتبطة الجديدة المستندة إلى REST ضمن القائمة.

إنشاء مجموعة بيانات جديدة لـ واجهة ClickHouse HTTP

الآن وبعد أن أصبح لدينا خدمة مرتبطة مُعَدًّا لواجهة ClickHouse HTTP، يمكننا إنشاء مجموعة بيانات ستستخدمها Azure Data Factory لإرسال البيانات إلى ClickHouse. في هذا المثال، سنُدرِج جزءًا صغيرًا من بيانات المستشعرات البيئية.

افتح وحدة استعلامات ClickHouse التي تفضّلها — وقد تكون ClickHouse Cloud web UI، أو عميل CLI، أو أي واجهة أخرى تستخدمها لتشغيل الاستعلامات — ثم أنشئ target table:
CREATE TABLE sensors ( sensor_id UInt16, lat Float32, lon Float32, timestamp DateTime, temperature Float32 ) ENGINE = MergeTree ORDER BY (timestamp, sensor_id);
في Azure Data Factory Studio، حدِّد Author في الجزء الأيسر. مرِّر المؤشر فوق العنصر Dataset، وانقر على أيقونة النقاط الثلاث، ثم اختر New dataset.
في شريط البحث، اكتب REST، وحدِّد REST، ثم انقر Continue. أدخل اسمًا لمجموعة البيانات وحدِّد خدمة مرتبطة التي أنشأتها في الخطوة السابقة. انقر OK لإنشاء مجموعة البيانات.
ينبغي أن ترى الآن مجموعة البيانات التي أنشأتها حديثًا مُدرجة ضمن قسم Datasets في جزء Factory Resources على اليسار. حدِّد مجموعة البيانات لفتح خصائصها. سترى المعلَمة pQuery التي جرى تعريفها في خدمة مرتبطة. انقر على حقل النص Value. ثم انقر Add dynamic content.

في الجزء الذي يُفتح، الصق الاستعلام التالي:

INSERT INTO sensors
SETTINGS 
    date_time_input_format=''best_effort'', 
    input_format_json_read_objects_as_strings=1 
FORMAT JSONEachRow

يجب استبدال جميع علامات الاقتباس المفردة ' في الاستعلام بعلامتي اقتباس مفردتين ''. وهذا مطلوب من محلّل التعبيرات في Azure Data Factory. إذا لم تقم بتهريبها، فقد لا ترى خطأً فورًا — لكنه سيفشل لاحقًا عندما تحاول استخدام مجموعة البيانات أو حفظها. على سبيل المثال، 'best_effort' يجب كتابتها بالشكل ''best_effort''.

انقر OK لحفظ التعبير. ثم انقر Test connection. إذا كان كل شيء مُعَدًّا بشكل صحيح، فسترى رسالة Connection successful. انقر Publish all أعلى الصفحة لحفظ تغييراتك.

إعداد مجموعة بيانات تجريبية

في هذا المثال، لن نستخدم مجموعة بيانات Environmental Sensors بالكامل، بل سنستخدم فقط مجموعة فرعية صغيرة متاحة على Sensors Dataset Sample.

لإبقاء هذا الدليل مركّزًا، لن نتناول الخطوات التفصيلية لإنشاء مجموعة البيانات المصدر في Azure Data Factory. يمكنك رفع البيانات التجريبية إلى أي خدمة تخزين تختارها — مثل Azure Blob Storage أو Microsoft SQL Server أو حتى بتنسيق ملف آخر يدعمه Azure Data Factory.

ارفع مجموعة البيانات إلى Azure Blob Storage لديك (أو إلى خدمة تخزين أخرى تفضّلها)، ثم انتقل في Azure Data Factory Studio إلى جزء Factory Resources. أنشئ مجموعة بيانات جديدة تشير إلى البيانات التي رفعتها. انقر على Publish all لحفظ تغييراتك.

إنشاء نشاط نسخ لنقل البيانات إلى ClickHouse

الآن بعد أن أعددنا مجموعتي بيانات الإدخال والإخراج، يمكننا إعداد نشاط Copy Data لنقل البيانات من مجموعة البيانات التجريبية إلى جدول sensors في ClickHouse.

افتح Azure Data Factory Studio، ثم انتقل إلى تبويب Author. في جزء Factory Resources، مرّر المؤشر فوق Pipeline، وانقر على أيقونة النقاط الثلاث، ثم اختر New pipeline.
في جزء Activities، وسّع قسم Move and transform، ثم اسحب نشاط Copy data إلى اللوحة.
حدّد تبويب Source، ثم اختر مجموعة البيانات المصدر التي أنشأتها سابقًا.
انتقل إلى تبويب Sink، ثم اختر مجموعة بيانات ClickHouse التي أنشأتها لجدول sensors. اضبط Request method على POST. وتأكد من أن HTTP compression type مضبوطة على None.

لا يعمل ضغط HTTP بشكل صحيح في نشاط Copy Data في Azure Data Factory. فعند تفعيله، يرسل Azure حمولة لا تتجاوز صفر بايت — ويُرجَّح أن يكون ذلك خللًا في الخدمة. احرص على إبقاء الضغط معطّلًا.

نوصي بالإبقاء على حجم الدفعة الافتراضي البالغ 10,000، أو حتى زيادته أكثر. لمزيد من التفاصيل، راجع اختيار استراتيجية الإدراج / الإدراجات الدفعية عند التزامن.

انقر على Debug أعلى اللوحة لتشغيل المسار. بعد انتظار قصير، سيُدرَج النشاط في قائمة الانتظار ثم يُنفَّذ. إذا كان كل شيء مُعدًّا بشكل صحيح، فينبغي أن تنتهي المهمة بحالة Success.
بعد اكتمال ذلك، انقر على Publish all لحفظ تغييرات المسار ومجموعة البيانات.

​تحويل ClickHouse إلى خدمة REST

​إنشاء مثيل Azure Data Factory

​إنشاء خدمة مرتبطة جديدة مستندة إلى REST

​إنشاء مجموعة بيانات جديدة لـ واجهة ClickHouse HTTP

​إعداد مجموعة بيانات تجريبية

​إنشاء نشاط نسخ لنقل البيانات إلى ClickHouse

​موارد إضافية

تحويل ClickHouse إلى خدمة REST

إنشاء مثيل Azure Data Factory

إنشاء خدمة مرتبطة جديدة مستندة إلى REST

إنشاء مجموعة بيانات جديدة لـ واجهة ClickHouse HTTP

إعداد مجموعة بيانات تجريبية

إنشاء نشاط نسخ لنقل البيانات إلى ClickHouse

موارد إضافية