نحن نشجع المبرمجين على الربط مع موقعنا. ويمكنك القيام بذلك من خلال نسخ عنوان الموقع (URL) من شريط العناوين أو إنشاء واجهة برمجة التطبيقات/عنوان الموقع الخاص بك (API/URL) (انظر أدناه). ومع ذلك نطلب منك إنشاء روابط مباشرة إلى موقعنا مع عدم حفظ الوحدات المكونة لصفحة البنك (frame) مع شعار الموقع الخاص بك.
أصبحت الآن لدينا طريقة جديدة ومحسنة للربط إلى ملفات التعريف والنتائج الخاصة بالوثائق. انظر الوثائق والأمثلة أدناه.
واجهة برمجة التطبيقات لصفحة الوثائق والتقارير
سيدعم موقع الوثائق والتقارير (D&R) عناوين مواقع إنترنت بسيطة لنوعين من الصفحات: صفحات النتائج وصفحات ملفات تعريف الوثائق. وسنعمل على التأكد من اعتماد واجهة برمجة التطبيقات حتى في حالة نقل الوثائق والتقارير إلى نظام أساسي جديد في المستقبل، حتى لا يحتاج المستخدمون إلى تغيير عناوين المواقع لديهم التي تربط إلى الوثائق الخاصة بنا.
وتتكون عناوين المواقع لهذه الصفحات من ثلاثة أجزاء. وتحدد هذه الأجزاء الثلاثة معاً (1) التطبيق الذي سيقوم بمعالجة هذا الطلب، (2) نوع الصفحة التي سيتم إرجاعها، (3) الوثيقة أو مجموعة الوثائق التي سيتم تقديمها على هذه الصفحة.
وتأخذ هذه الأجزاء الثلاثة الشكل التالي.
http:///?
اسم المضيف
يمثل الجزء الأول من عنوان موقع إنترنت، فنياً، مضيف هذا الموقع. سيكون اسم المضيف "documents.albankaldawli.org".
نوع الطلب
يحدد نوع الطلب، والذي يمثل الجزء الثاني من عنوان موقع إنترنت، الصفحة التي سيتم إرجاعها. وسيكون نوع الطلب إما "record" أو "query". يقوم نوع الطلب "record" بإرجاع ملف التعريف (أو سجل البيانات) الذي تنتمي إلى وثيقة بعينها. بينما يقوم نوع الطلب "query" بإرجاع مجموعة من الوثائق تطابق هذا الاستعلام.
| نوع الطلب | الصفحة التي يتم إرجاعها |
|---|---|
| سجل record | ملف تعريف كامل عن وثيقة بعينها مع وجود رابط أو أكثر إلى الوثيقة نفسها. |
| استعلام query | استعلام يحدد مجموعة من الوثائق يتم تقديمها على هيئة قائمة أو جدول. |
قائمة المعلمات
يتكون الجزء الثالث والأخير من عنوان الموقع من معلمة أو أكثر وقيمها. وتحدد هذه المعلمات وقيمها الوثيقة أو مجموعة الوثائق التي يتم تقديمها في الصفحة. وتكون قائمة المعلمات وقيمها مفصولة عن نوع الطلب الذي يسبقها بحرف علامة الاستفهام "?".
تحتوي الطلبات من النوع "Record" على معلمة مطلوبة واحدة، "docid"، وتكون قيمتها ImageBank أو المعرف D&R لوثيقة ملف التعريف الذي سيتم عرضه في الصفحة. ويفصل اسم المعلمة "docid" عن قيمتها العلامة "=".
وبالإضافة إلى المعلمة docid، تعتمد الطلبات من النوع record أيضاً المعلمة الاختيارية pageLanguage. وتحدد هذه المعلمة لغة الصفحة التي تعرض السجل ويمكن استخدامها للمواقع التي لا تستخدم اللغة الإنجليزية لتقديم وثائق ImageBank بنفس لغة الموقع. حالياً، تعتمد الطلبات باللغتين الفرنسية والإسبانية.
| اسم المعلمة | الاستخدام |
|---|---|
| docid | معرف D&R للوثيقة التي سيتم إرجاع ملف التعريف الخاص بها |
| pageLanguage | لغة الصفحة التي تعرض السجل. وهذه المعلمة غير متوفرة حالياً. |
فيما يلي مثال لعنوان موقع إنترنت:
documents.albankaldawli.org/record?docid=000160016_20040929135419
أما الطلبات من النوع "Query" فهي طلبات للحصول على مجموعة من الوثائق يتم تقديمها على هيئة قائمة في الصفحة التي يتم إرجاعها. ويمكن أن تحتوي الطلبات من النوع "Query" على معلمة أو أكثر. وتحدد كل معلمة إضافية بدقة أكبر أو تقيد ما سيتم إرجاعه. وتقابل هذه المعلمات سمة موجودة في كل سجل أو ملف تعريف لإحدى الوثائق. ويفصل اسم كل معلمة عن قيمتها العلامة "=". وعند استخدام أكثر من معلمة/زوج قيم، يفصل كل زوج جديد عن الزوج السابق بالحرف "&". ولا يتم وضع الحرف "&" قبل الزوج الأول. وللاستعلام عن أكثر من قيمة واحدة لإحدى السمات، إما أن تقوم بتضمين معلمة إضافية/زوج إضافي لهذه السمة (تحتوي كل واحدة على قيمة واحدة) أو أن تستخدم اسم المعلمة مرة واحدة وتقوم بسرد القيمة مع فصل القيم عن بعضها بوضع مسافة. ويزيد الاستعلام عن قيم متعددة لإحدى السمات من عدد الوثائق التي يتم إرجاعها حيث يمكن تضمين الوثائق التي يتم العثور عليها لكل قيمة يتم تمريرها في النتائج.
ويمكن أيضاً تحديد لغة الصفحة التي تعرض النتائج في الطلبات من النوع query كما هو الحال مع الطلبات من النوع record. ويتم حاليا دعم الطلبات باللغتين الفرنسية والإسبانية.
| اسم المعلمة | القيمة | الاستخدام |
|---|---|---|
| text | text | كلمة أو أكثر |
| title | text | عنوان الوثيقة |
| collection | text | عنوان مجموعة الوثائق التي تنتمي إليها الوثيقة |
| sourceCitation | Text | ذكر المصدر |
| author | text | مؤلف الوثيقة |
| region | text or ID | المنطقة التي تنتمي إليها الوثيقة |
| country | text or ID | البلد الذي تنتمي إليها الوثيقة |
| sector | text or ID | القطاع الذي تنتمي إليها الوثيقة |
| subsector | text or ID | القطاع الفرعي الذي تنتمي إليها الوثيقة |
| topic | text or ID | موضوع تتناوله الوثيقة |
| majorDocType | text or ID | نوع الوثيقة الرئيسية التي تنتمي إليها الوثيقة |
| docType | text or ID | الوثيقة |
| language | text or ID | اللغة التي تمت كتابة الوثيقة بها أو ترجمته إليها |
| date | yyyy/mm/dd | تاريخ نشر الوثيقة أو وضعها على الشبكة |
| startDate | yyyy/mm/dd | بدء نطاق تاريخ. يجب أن تكون الوثائق التي يتم إرجاعها تم نشرها أو وضعها على الشبكة في هذا التاريخ أو بعده. ويمكن استخدامها مع أو بدون استخدام المعلمة endDate. عند عدم استخدام المعلمة endDate، ينتهي النطاق بتاريخ اليوم. |
| endDate | yyyy/mm/dd | نهاية نطاق تاريخ. يجب أن تكون الوثائق التي يتم إرجاعها تم نشرها أو وضعها على الشبكة في هذا التاريخ أو قبله. ويمكن استخدامها مع أو بدون استخدام المعلمة startDate. عند عدم استخدام المعلمة startDate، يتضمن النطاق كل التواريخ قبل تاريخ اليوم. |
| report | ID | رقم التقرير الذي تم تعيينه لهذه الوثيقة |
| loan | ID | رقم القرض الذي تنتمي إليها هذه الوثيقة |
| credit | ID | رقم الاعتماد المقترن بهذه الوثيقة |
| project | text or ID | اسم أو معرف المشروع الذي تنتمي إليها الوثيقة |
| trustFund | ID | الصندوق الاستئماني الذي تقترن به الوثيقة |
| pageSize | number | عدد النتائج التي يتم إظهارها في الصفحة (بحد أقصي 50) |
| pageLanguage | ID | لغة الصفحة التي تعرض السجل. حالياً، تعتمد الطلبات باللغتين الفرنسية والإسبانية. |
| sortBy | السمة (“date” أو “title” أو “report” أو “docType”) التي يجب فرز النتائج باستخدامها. يكون الفرز تصاعدياً باستثناء التاريخ الذي يكون تنازلياً. |
وفيما يلي بعض الأمثلة.
لسرد وثائق حول موضوع بعينه
documents.albankaldawli.org/query?topic=Education
لسرد وثائق ذات صلة بموضوع بعينه وبلد…
documents.albankaldawli.org/query?country=China&topic=Education
لإرجاع كل الوثائق التي تم نشرها أو إصدارها في تاريخ بعينه…
documents.albankaldawli.org/query?date=2004/2/4
لإرجاع كل الوثائق التي تم نشرها أو إصدارها حول موضوع تم نشره أو إصداره بين تاريخين….
documents.albankaldawli.org/query?startDate=2004/1/1&endDate=2004/2/1&topic=Agriculture
لإرجاع كل الوثائق باللغة العربية ...
documents.albankaldawli.org/query?language=Arabic