استخدام واجهة برمجة التطبيقات (API) للتصديرات المتزامنة

Read in English | Lire en français | Leer en español آخر تحديث: 13 سبتمبر 2025

يوفر KoboToolbox طريقتين أساسيتين للوصول إلى بياناتك: التصديرات غير المتزامنة والتصديرات المتزامنة. تتضمن الطريقة القياسية غير المتزامنة تنزيل ملفات البيانات يدويًا التي تحتوي على جميع الإرسالات حتى وقت التنزيل. في المقابل، تتيح التصديرات المتزامنة التكامل التلقائي لبيانات KoboToolbox الخاصة بك مع التطبيقات الخارجية مثل Microsoft Power BI أو Excel أو Google Sheets.

مع التصديرات المتزامنة، تُحدَّث بياناتك تلقائيًا عند استلام إرسالات جديدة، مما يلغي الحاجة إلى التحديث اليدوي. توفر هذه الطريقة ملف CSV أو XLSX، مُعدًّا بإعدادات التصدير المحددة مسبقًا، والتي يمكن أن تتضمن تسميات الأسئلة واللغات والمرشحات وبيانات المجموعات المتكررة.

ملاحظة: يركز هذا المقال على التصديرات المتزامنة، وهي إحدى الطريقتين الأساسيتين لاستخدام واجهة برمجة التطبيقات (API) الخاصة بـ KoboToolbox. الطريقة الأخرى هي JSON API، المصممة للبرامج النصية المخصصة والأتمتة في الوقت الفعلي، وتقدم بيانات JSON الأولية سجلًا تلو الآخر. على عكس التصديرات المتزامنة، لا تتضمن JSON API ميزات التصدير المتقدمة مثل تسميات الأسئلة أو دعم اللغات المتعددة.

يغطي هذا المقال الخطوات التالية:

  • إنشاء تصدير مُسمى

  • استرجاع رابط التصدير المتزامن

  • ربط بياناتك بتطبيق خارجي والمصادقة

إنشاء تصدير مُسمى

لإنشاء تصديرات متزامنة، يجب عليك أولاً إنشاء تصدير مُسمى لمشروعك باتباع الخطوات التالية:

  1. في مشروع KoboToolbox الخاص بك، انتقل إلى علامة التبويب البيانات > التنزيلات.

  2. اضبط إعدادات التصدير حسب الحاجة.

  3. انقر على خيارات متقدمة لتخصيص البيانات للتصدير.

  4. اختر حفظ التحديد باسم... وقدم اسمًا للتصدير الخاص بك.

  5. انقر على تصدير لحفظ هذه الإعدادات.

استرجاع رابط التصدير المتزامن

لاسترجاع رابط التصدير المتزامن، ستحتاج إلى ما يلي:

  • معرّف أصل المشروع (Project asset UID): معرّف فريد لكل مشروع في KoboToolbox، يوجد في عنوان URL الخاص بالمشروع.

  • عنوان URL الخاص بالخادم: عنوان URL للخادم الذي تستخدمه (kf.kobotoolbox.org للخادم العالمي، أو eu.kobotoolbox.org لخادم الاتحاد الأوروبي، أو [your organization].kobotoolbox.org للخوادم الخاصة).

لمزيد من المعلومات حول استرجاع عنوان URL الخاص بالخادم ومعرّف أصل المشروع، راجع البدء باستخدام واجهة برمجة التطبيقات (API).

لاسترجاع رابط التصدير، اتبع الخطوات التالية:

  1. افتح علامة تبويب جديدة في المتصفح.

  2. استبدل عنوان URL الخاص بالخادم ومعرّف أصل المشروع في عنوان URL التالي: https://[server_url]/api/v2/assets/[project_asset_uid]/export-settings/.

  3. افتح صفحة الويب المقابلة لعنوان URL المعدّل.

  4. انتقل إلى قسم CURRENT ENDPOINT.

  5. ابحث عن إعداد التصدير الذي يطابق التصدير المُسمى الذي أنشأته في الخطوة الأولى.

  6. حدد موقع روابط data_url_csv وdata_url_xlsx، وهي روابط التصدير المتزامن لمشروعك.

  7. انسخ الرابط الذي يناسب احتياجاتك (ملف CSV أو XLSX).

استرجاع رابط التصدير المتزامن

ملاحظة: يتم تصدير المجموعات المتكررة كأوراق منفصلة في ملفات Excel ولا يتم تضمينها في تصديرات CSV. إذا كان مشروعك يحتوي على مجموعات متكررة، استخدم رابط data_url_xlsx.

ربط بياناتك بتطبيق خارجي

بعد استرجاع رابط التصدير المتزامن، يمكنك ربط بياناتك بالتطبيق الخارجي المفضل لديك. ستختلف طريقة دمج رابط التصدير المتزامن حسب التطبيق.

لمعرفة كيفية ربط بياناتك بـ Power BI لإنشاء لوحات معلومات مخصصة، راجع ربط KoboToolbox بـ Power BI.

لمعرفة كيفية ربط بياناتك بـ Microsoft Excel، راجع ربط KoboToolbox بـ Microsoft Excel.

المصادقة

يمكن للعديد من التطبيقات الخارجية الاتصال ببيانات KoboToolbox الخاصة بك. ومع ذلك، لا تدعم جميعها الطلبات المصادق عليها، وهي الطلبات التي تحمل بيانات الاعتماد (مثل مفتاح API أو اسم المستخدم وكلمة المرور) حتى يتمكن الخادم من التحقق من هوية المتصل. إذا كان التطبيق الخارجي لا يدعم الطلبات المصادق عليها، فسيتمكن فقط من الوصول إلى الموارد التي تم جعلها متاحة للعامة من خلال رابط تصدير مجهول.

لربط مشروعك بدون مصادقة (مثل Google Sheets)، ستحتاج إلى التأكد من تحديد إعداد "يمكن لأي شخص عرض الإرسالات المقدمة لهذا النموذج" في الإعدادات > المشاركة.

لمزيد من المعلومات حول مشاركة المشروع، راجع مشاركة المشاريع بإعدادات على مستوى المشروع.

بالنسبة للمشاريع التي تحتوي على بيانات حساسة أو خاصة، يجب أن يظل خيار "يمكن لأي شخص عرض الإرسالات المقدمة لهذا النموذج" غير محدد. في هذه الحالات، فكر في استخدام التطبيقات التي تدعم الطلبات المصادق عليها فقط.

عند استخدام التطبيقات التي تدعم الطلبات المصادق عليها، مثل Power BI، سيُطلب منك المصادقة الأساسية باستخدام اسم المستخدم وكلمة المرور أو رمز (يُسمى أيضًا مفتاح API) للوصول إلى البيانات. يوجد مفتاح API الخاص بك في إعدادات الحساب ضمن علامة التبويب الأمان.

لمزيد من المعلومات حول مفتاح API، راجع البدء باستخدام واجهة برمجة التطبيقات (API).

القيود

للحفاظ على موثوقية الخادم، تحتوي التصديرات المتزامنة على القيود التالية:

  • فترة تحديث البيانات: تُحدَّث البيانات في التصديرات المتزامنة كل 5 دقائق. طلبات التصدير المقدمة خلال فترة الـ 5 دقائق هذه لن تتضمن بيانات الإرسالات الجديدة المستلمة خلال فترة الـ 5 دقائق.

  • وقت إكمال التصدير: يجب أن تكتمل التصديرات خلال 120 ثانية. قد تفشل المشاريع التي تحتوي على عدد كبير من الإرسالات أو الأسئلة. لتجنب ذلك، أضف قيد استعلام في إعدادات التصدير لتحديد الإرسالات أو تصفية الأسئلة غير الضرورية. راجع هذا منشور المنتدى للحصول على إرشادات.