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

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

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

باستخدام واجهة برمجة التطبيقات الخاصة بـ KoboToolbox، يمكنك:

  • تنزيل البيانات تلقائيًا بتنسيق JSON أو CSV أو XLSX.

  • إنشاء عمليات تصدير عند الطلب للوحات المعلومات أو النسخ الاحتياطية أو التحليلات.

  • إرسال أو تعديل السجلات من أدوات جمع البيانات الأخرى.

  • إنشاء أو نشر المشاريع واستنساخ المشاريع الموجودة من خلال الكود البرمجي.

  • إدارة المستخدمين والأذونات ونشاط المشروع على نطاق واسع.

يتيح لك استخدام واجهة برمجة التطبيقات الخاصة بـ KoboToolbox أتمتة المهام الروتينية، والحفاظ على تحديث لوحات المعلومات، ودمج KoboToolbox مع الأنظمة الأخرى، مع تقليل الخطوات اليدوية والأخطاء. توفر هذه المقالة مقدمة عن واجهة برمجة التطبيقات الخاصة بـ KoboToolbox وتغطي الخطوات التالية:

  • استرجاع عنوان URL الخاص بالخادم

  • استرجاع مفتاح واجهة برمجة التطبيقات (API Key)

  • استرجاع المعرّف الفريد لأصل المشروع (project asset UID)

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

ملاحظة: نقاط النهاية V1 أصبحت الآن قديمة ومن المقرر إيقاف تشغيلها في يناير 2026، لصالح واجهة برمجة التطبيقات KPI v2 الأكثر قوة والمدعومة بالكامل. لمزيد من المعلومات حول الترحيل إلى KPI v2، راجع الترحيل من واجهة برمجة التطبيقات v1 إلى v2.

استرجاع عنوان URL الخاص بالخادم

عنوان URL الخاص بالخادم هو عنوان الويب الأساسي لخادم KoboToolbox الخاص بك. يتم وضعه في بداية كل طلب لواجهة برمجة التطبيقات.

بالنسبة لمعظم المستخدمين، عنوان URL الخاص بالخادم هو kf.kobotoolbox.org (إذا كنت تستخدم الخادم العالمي) أو eu.kobotoolbox.org (إذا كنت تستخدم خادم الاتحاد الأوروبي).

استرجاع عنوان URL الخاص بالخادم

استرجاع مفتاح واجهة برمجة التطبيقات (API Key)

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

هناك طرق مختلفة للحصول على مفتاح واجهة برمجة التطبيقات (API Key) الخاص بك.

الطريقة الأولى:

  1. انقر على أيقونة ملفك الشخصي في الزاوية العلوية اليمنى.

  2. حدد إعدادات الحساب.

  3. انتقل إلى علامة التبويب الأمان.

  4. مفتاح واجهة برمجة التطبيقات الخاص بك مخفي افتراضيًا. انقر على عرض لعرضه.

الطريقة الثانية:

في متصفح الويب الخاص بك، انتقل إلى https://[server-url]/token/?format=json. تأكد من استبدال [server-url] بعنوان URL الخاص بالخادم.

الطريقة الثالثة:

في الطرفية، استخدم أمر curl التالي:

curl -u username:password "https:/[server-url]/token/?format=json"

تأكد من استبدال [server-url] بعنوان URL الخاص بالخادم.

استرجاع المعرّف الفريد لأصل المشروع (project asset UID)

المعرّف الفريد لأصل المشروع (project asset UID) هو رمز فريد يحدد مشروع KoboToolbox معين ويجب تضمينه في استدعاءات واجهة برمجة التطبيقات لاستهداف هذا المشروع.

يمكنك العثور على المعرّف الفريد لأصل المشروع في عنوان URL الخاص بصفحة ملخص مشروعك. إنه سلسلة الحروف والأرقام التي تظهر بعد "forms/" في عنوان URL، على النحو التالي: https://[server-url]/#/forms/[project asset UID]/summary.

استرجاع المعرّف الفريد لأصل المشروع

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

هناك نهجان رئيسيان لربط بياناتك باستخدام واجهة برمجة التطبيقات مع KoboToolbox:

  • عمليات التصدير المتزامنة: تُرجع ملف CSV أو XLSX جاهزًا، بناءً على إعدادات التصدير المحددة مسبقًا، والذي يمكن للتطبيقات الخارجية (مثل Power BI أو Excel) تحميله مباشرة.

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

يتطلب كل نهج معرفة عنوان URL الخاص بالخادم والمعرّف الفريد لأصل المشروع لإنشاء عنوان URL مخصص للتصدير. اعتمادًا على التطبيق، قد تكون هناك حاجة إلى مفتاح واجهة برمجة التطبيقات الخاص بك للمصادقة.

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

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

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