Michael Johnsonإذا كان مخطط مجموعة بيانات تحليلية يتضمن عمود JSON باسم attributes، لكن مفاتيحه تعتمد على بيانات الحساب، تتيح Cloudflare الآن اكتشافها عبر آلية استكشاف المخطط. أضاف تحديث 27 أكتوبر 2026 الخيار include_attributes=true: فتسرد الاستجابة المفاتيح وأنواعها التي عُثر عليها في بيانات الحساب خلال الأيام السبعة السابقة.
يحل هذا التحديث مشكلة محددة للمطورين: إذ يمكنهم التحقق من الحقول الموجودة فعليًا في المجموعة المحددة قبل إنشاء عامل تصفية. لا يزال الاسمان القديمان include_custom_attributes وcustom_attributes يعملان، لكن Cloudflare صنفتهما على أنهما مهملان. ومن الأفضل أن تعتمد عمليات التكامل الجديدة على آلية استكشاف SQL API المحدّثة.
ما الذي تعيده آلية استكشاف المخطط؟
تخزن بعض مجموعات Cloudflare Analytics أزواجًا إضافية من المفاتيح والقيم في عمود attributes. ويحدد الاستكشاف، عند استخدام الخيار الجديد، المفاتيح وأنواعها بالاستناد إلى بيانات الأيام السبعة، ثم يعيد المعلومات في الحقل attributes ضمن كائن مجموعة البيانات. وهذا مخطط مستنتج من سجلات الحساب الحديثة، يساعد على إعداد استعلام SQL.
في المثال الرسمي، تستخدم Cloudflare المسار /client/v4/analytics/sql/introspection، وتمرر معرّف الحساب واسم مجموعة البيانات events.httpRequests، كما تفعّل اكتشاف السمات:
curl --get "https://api.cloudflare.com/client/v4/analytics/sql/introspection" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--data-urlencode "account_tag=$CLOUDFLARE_ACCOUNT_TAG" \
--data-urlencode "dataset_name=events.httpRequests" \
--data-urlencode "include_attributes=true"قبل التشغيل، عيّن المتغيرين CLOUDFLARE_API_TOKEN وCLOUDFLARE_ACCOUNT_TAG في البيئة. يُمرر الرمز باعتباره بيانات اعتماد من نوع bearer؛ أما اسما المتغيرين الواردان في المثال فهما إعدادان محليان للفريق، وليسا معاملين منفصلين في Cloudflare.
من المفتاح المكتشف إلى الاستعلام
بعد الاستكشاف، افحص الحقل attributes في وصف مجموعة البيانات المطلوبة واختر مفتاحًا واردًا بالفعل في القائمة. تعرض Cloudflare مثالًا على الوصول بدقة إلى مفتاح في عمود JSON: attributes['http.method']. استخدم الاسم المكتشف في عامل التصفية، لا اسمًا مفترضًا استنادًا إلى اسم الحدث.
يمكن اتباع الخطوات العملية التالية:
- اطلب استكشاف مجموعة البيانات المطلوبة مع
include_attributes=true. - احفظ المفاتيح والأنواع الواردة في الحقل
attributesمع تاريخ التحقق. - أنشئ الاستعلام مستخدمًا اسم المفتاح الدقيق، مثل
attributes['http.method']. - اختبر الاستعلام على بيانات حسابك، وأعد عملية الاكتشاف عند تغير المخطط أو طبيعة الأحداث الواردة.
يفيد تسجيل تاريخ التحقق في ضمان إمكانية إعادة النتائج: تستنتج Cloudflare السمات من نافذة الأيام السبعة، ولذلك تعكس مجموعة المفاتيح المكتشفة البيانات الحديثة، لا مخططًا ثابتًا. وإذا لم يظهر المفتاح المطلوب في هذه النافذة، فلا يكفي غيابه عن النتيجة وحده للحكم بأنه غير متاح على نحو عام.
كيفية الانتقال من الأسماء القديمة
في الشيفرة الحالية، استبدل معامل الاستعلام include_custom_attributes بـ include_attributes، واستبدل معالجة حقل الاستجابة custom_attributes بقراءة attributes. وتفيد Cloudflare بأن الأسماء السابقة ما زالت تعمل، لذا يمكن إجراء الترحيل بمعزل عن أي معالجة عاجلة لاستعادة التكامل.
لضمان انتقال آمن، تحقّق من جزأي الواجهة: معامل الاستعلام المُرسل ومسار الحقل في الاستجابة. ثم نفّذ الاستعلام على المجموعة نفسها وقارن قائمة المفاتيح. يكشف هذا الاختبار خطأ شائعًا في الترحيل، حين يستخدم الاستعلام الاسم الجديد للمعامل، بينما تظل الشيفرة تتوقع حقل الاستجابة القديم.
الخلاصة لمسارات البيانات التحليلية
يجعل include_attributes=true حقول JSON الديناميكية قابلة للاكتشاف عبر آلية استكشاف المخطط الرسمية، كما يوفر للمطورين الأنواع إلى جانب أسماء المفاتيح. حدّث الاستعلامات الجديدة ومحللات الاستجابة لاستخدام include_attributes وحقل الاستجابة attributes، وسجّل تاريخ الاكتشاف، وأنشئ عوامل التصفية باستخدام المفاتيح التي عُثر عليها فعليًا.
