استخدام SmartDocuments لتوثيق واجهات برمجة التطبيقات

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستندات Apigee X.
المعلومات

تتيح لك ميزة "المستندات الذكية" توثيق واجهات برمجة التطبيقات على بوابة مطوّري برامج Drupal 7 بطريقة تجعل مستندات واجهة برمجة التطبيقات تفاعلية بالكامل. الوثائق التفاعلية تعني أن مستخدمي البوابة يمكنهم إجراء ما يلي:

  • الاطّلاع على واجهات برمجة التطبيقات
  • إرسال طلب مباشر إلى واجهة برمجة التطبيقات
  • الاطّلاع على ردّ مباشر من واجهة برمجة التطبيقات

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

واجهة برمجة تطبيقات إدارة Edge هي واجهة برمجة تطبيقات RESTful تتيح لك الوصول إلى خدمات واجهة برمجة التطبيقات باستخدام أي عميل HTTP. تستخدم Apigee مستندات ذكية لإنشاء مستندات تفاعلية لواجهة برمجة تطبيقات إدارة Edge. راجع وثائق واجهة برمجة التطبيقات هذه هنا.

مثال على بوابة Smart Docs

لاستخدام Smartالمستندات، يجب أن يكون لديك بوابة Apigee Developer Services. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء بوابة المطوّرين.

من الصفحة الرئيسية لبوابة مطوّري البرامج، انقر على واجهات برمجة التطبيقات في شريط التنقل العلوي لعرض صفحة مستندات واجهة برمجة التطبيقات.

هناك اثنان من واجهات برمجة التطبيقات موثّقة على البوابة: Hello World وPet Store Example.

تم إنشاء واجهة برمجة التطبيقات Hello World API من خلال مواصفات OpenAPI المستهدفة الوهمية mocktarget.yaml. لمزيد من المعلومات، يُرجى الاطّلاع على https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

تم إنشاء مثال على واجهة برمجة التطبيقات لمتجر الحيوانات الأليفة من الإصدار التجريبي لمتجر الحيوانات الأليفة الكلاسيكي.

استكشاف واجهة برمجة التطبيقات Hello World:

  1. انقر على Hello World API. يتم عرض صفحة ملخّص واجهة برمجة التطبيقات Hello World API:
  2. انقر على عرض تأكيد واجهة برمجة التطبيقات. يتم عرض المستندات الذكية لهذا المورد:
  3. انقر على إرسال هذا الطلب.
  4. الاطّلاع على الرد الذي تم إرجاعه:
    HTTP/1.1 200 OK
    Connection:
    keep-alive
    Content-Length:
    18
    Content-Type:
    text/html; charset=utf-8
    Date:
    Tue, 21 Jun 2016 21:49:32 GMT
    ETag:
    W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
    X-Powered-By:
    Apigee
    <H2>I <3 APIs</H2>
    
  5. انقر على علامة التبويب طلب لعرض الطلب، أو على علامة التبويب cURL لعرض طلب cURL المقابل.

كيفية توثيق واجهات برمجة التطبيقات باستخدام Smart Docs

تمثل "المستندات الذكية" واجهات برمجة التطبيقات باستخدام model، حيث يحتوي النموذج على جميع المعلومات المتعلقة بواجهات برمجة التطبيقات. تستخرج البوابة معلومات عن واجهات برمجة التطبيقات من النموذج لعرض صفحات المستندات على البوابة كعُقد Drupal، حيث تتوافق كل عقدة Drupal مع صفحة من المستندات على البوابة.

في ما يلي الخطوات العامة التي تتّبعها لاستخدام ميزة "المستندات الذكية":

  1. ضبط وحدة Drupal Smart Docs على البوابة
  2. إنشاء نموذج "مستندات ذكية"
  3. إضافة واجهات برمجة التطبيقات إلى النموذج من ملف WADL أو مواصفات OpenAPI (المعروفة سابقًا باسم Swagger) أو يدويًا
  4. عرض النموذج كمجموعة من عُقد Drupal. تحتوي كل عقدة Drupal على معلومات حول واجهة برمجة تطبيقات واحدة. على سبيل المثال، إذا كان أحد الموارد في واجهة برمجة التطبيقات يتيح استخدام طلبَي POST وPUT، تنشئ أداة Smart Docs عقدة منفصلة في Drupal لكل من POST وPUT.
  5. انشر عُقد Drupal. بعد نشر اللوحة، يمكن لمستخدمي البوابة عرض واجهة برمجة التطبيقات الخاصة بك والتفاعل معها.
  6. تعديل عُقد Drupal، سواء قبل نشرها أو بعدها. يمكنك تعديل عُقد Drupal باستخدام محرِّر Drupal أو عن طريق تعديل ملف WADL الأصلي أو OpenAPI Specification. عند الانتهاء من تعديل ملف WADL أو مواصفات OpenAPI، يجب استيراده مرة أخرى إلى النموذج كنسخة جديدة، ثم عرض التغييرات ونشرها.
  7. فعِّل بروتوكول أمان طبقة النقل (TLS). بما أنّ ميزة "المستندات الذكية" يمكنها إرسال بيانات اعتماد المصادقة إلى الخلفية كجزء من عملية تقديم طلب إلى واجهات برمجة التطبيقات، عليك تفعيل بروتوكول أمان طبقة النقل (TLS) على بوابتك لضمان أمان بيانات الاعتماد هذه. في بيئات إنتاج المدخل واختباره، توفِّر Apigee شهادة بروتوكول أمان طبقة النقل (TLS) المطلوبة لإجراء طلبات https:// . قبل الانتقال إلى المنصة، يجب الحصول على شهادة بروتوكول أمان طبقة النقل (TLS) وتفعيل بروتوكول أمان طبقة النقل (TLS). لمزيد من المعلومات، يُرجى الاطّلاع على استخدام بروتوكول أمان طبقة النقل (TLS) على البوابة.

لمحة عن نماذج SmartDoc ونماذجها

عند إنشاء نموذج في البوابة، يتم تخزين النموذج في مؤسسة Edge، وليس في Drupal. النموذج هو كتلة كبيرة من JSON يحمل اسمًا داخليًا (مثل "my-smartdocs-api")، وهو يحدّد بنية واجهة برمجة التطبيقات. من ناحية أخرى، تعرض البوابة النموذج بتنسيق HTML وتوفّر واجهة تعديل للنموذج. أي تعديلات يتم إجراؤها على واجهة برمجة التطبيقات في المنصة يتم إرسالها تلقائيًا إلى نموذج المصدر.

تم التخزين في المؤسسة

تم التخزين في Drupal

الطرازات

النماذج

عُقد Drupal مع وظيفة التعديل

افترِض أنّ لديك عدّة بوابات في مؤسستك (على سبيل المثال، قسم تطوير البرامج والمسرح والإنتاج). في Pantheon، يمكنك نقل البوابة من بيئة إلى أخرى. ويبدو أنّ كل نسخة من البوابة الإلكترونية تحتوي على نموذج خاص بها، ولكن جميعها يشير إلى نموذج المصدر. في حال تعديل واجهة برمجة التطبيقات في قناة dev، سيتم تحديث النموذج وستظهر التغييرات في مرحلة الإنتاج. وبالمثل، إذا حذفت نموذجًا في المطوّر، سيتم حذف المصدر ولن يبقى متاحًا في مرحلة الإنتاج.

وتتحكّم النماذج في مظهر ومضمون "مستندات Google الذكية"، ويتم تخزين تلك النماذج (التي تستند إليها الأشرطة المقلَّدة وملفات CSS) مع كل مثيل بوابة. إذًا، يمكن لكل بوابة من الناحية النظرية استخدام نموذج فريد لكل نموذج. ومع ذلك، إحدى ميزات إطار العرض هي أنّه يتم تطبيق نموذج تلقائي (إما النموذج التلقائي Apigee أو نموذج تقدّمه) على كل نموذج.

ويوضح الرسم البياني التالي العلاقة بين النماذج والبوابات. تُظهر الأسهم الخضراء المزامنة التلقائية.

يسرد الأمر cURL التالي جميع النماذج في مؤسستك:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

ضبط وحدة "مستندات ذكية"

استخدمت Apigee مستندات ذكية في "مستندات Google" كوحدة مخصّصة في Drupal. اتّبِع الإجراء التالي لضبط وحدة "المستندات الذكية".

لضبط وحدة "مستندات Google" الذكية:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختر الوحدات في قائمة إدارة Drupal. ستظهر قائمة بجميع وحدات Drupal المثبَّتة.
  3. فعِّل وحدة SmartDocs.
  4. احفظ الضبط.
  5. اختَر الوحدات في قائمة المشرف في Drupal.
  6. اختَر Smart Docs -> الأذونات وتأكَّد من تفعيل "تنفيذ المهام الإدارية لوحدة المستندات الذكية" لدور "المشرف".
  7. اختَر الإعدادات > بوابة مطوّري البرامج في قائمة إدارة Drupal.
  8. اضبط مهلة الاتصال ومهلة الطلب على 16 ثانية.
  9. احفظ الضبط.
  10. ضبط إعدادات عناوين URL:
    1. اختَر الضبط > البحث والبيانات الوصفية > الأسماء المستعارة لعناوين URL > الإعدادات من قائمة Drupal.
    2. اضبط الحدّ الأقصى لطول الاسم المستعار والحدّ الأقصى لطول المكوِّن على 255.
    3. وسِّع علامات الترقيم.
    4. بالنسبة إلى إعدادات القوس المعقوف الأيسر ({) والقوس المجعد الأيمن (})، اختَر ما مِن إجراء (عدم الاستبدال).
    5. انقر على حفظ الضبط.
  11. إذا كانت بوابة المطوّر الخاصة بك ستُعرض للمستخدمين في شبكة داخلية بدون الوصول إلى الإنترنت، أو إذا كانت مجموعة فرعية من واجهات برمجة التطبيقات على شبكة خاصة، اضبط عنوان URL للخادم الوكيل لواجهة برمجة تطبيقات Smart Docs على النحو التالي:
    1. اختَر الضبط > Smartالمستندات في قائمة Drupal Administration (إدارة Drupal).
    2. عليك توسيع قسم الإعدادات المتقدمة.
    3. يمكنك تعديل حقل عنوان URL للخادم الوكيل في Smart Docs كما يلي: <host>/smartdocs/v1/sendrequest.
      يجب أن توفر المساعدة المضمّنة القيمة المطلوبة لبيئتك. على سبيل المثال:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      القيمة التلقائية لهذا الحقل هي: https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest
    4. انقر على حفظ الضبط.

إنشاء نموذج

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

يحدد كل نموذج اسمًا داخليًا فريدًا يحدد أيضًا عنوان URL الأساسي لعقد Drupal التي تم إنشاؤها. يكون عنوان URL لكل عقدة Drupal على النحو التالي:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

المكان:

  • drupalBasePath: عنوان URL الأساسي للبوابة.
  • internalName: الاسم الداخلي للنموذج.
  • httpMethod: هو طريقة HTTP لواجهة برمجة التطبيقات، مثل الحصول عليها أو وضع أو نشر مشاركة أو حذف.
  • resourcePath: مسار الموارد

على سبيل المثال، إذا حدّدت الاسم الداخلي "mymodel"، سيكون عنوان URL لعقدة Drupal التي تم إنشاؤها لطلب GET لمورد باسم "/books" على النحو التالي:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

لإنشاء نموذج

عند إنشاء نموذج، يتم تخزينه في مؤسسة Edge كمصدر لبنية واجهة برمجة التطبيقات. لمزيد من المعلومات، يُرجى الاطّلاع على لمحة عن نماذج SmartDoc ونماذجها.

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > مستندات ذكية في قائمة إدارة Drupal.
  3. اختَر طراز جديد في أعلى الصفحة.
  4. أدخِل الحقول التالية:
    • الاسم: اسم النموذج الذي سيتم عرضه على الموقع الإلكتروني.
    • الاسم الداخلي: أثناء كتابة الاسم، يظهر الاسم الداخلي. الاسم الداخلي للنموذج الذي يجب أن يكون فريدًا بين جميع النماذج. يجب أن يحتوي الاسم الداخلي على أحرف صغيرة وأرقام وواصلات فقط بدون مسافات. اختَر تعديل لتعديل هذا الاسم.
    • الوصف: وصف للنموذج.
  5. اختَر إنشاء نموذج.

بعد إنشاء النموذج، ستتم إعادة توجيهك إلى صفحة النموذج. من هناك، يمكنك استخدام القائمة المنسدلة "العمليات" لإجراء ما يلي:

  • استورد ملف WADL يصف واجهة برمجة التطبيقات أو حدِّد عنوان URL لمواصفات OpenAPI التي تصف واجهة برمجة التطبيقات.
  • إضافة مراجعة إلى النموذج
  • عدِّل إعدادات النموذج، بما في ذلك أوراق الأنماط التي يستخدمها النموذج.
  • تصدير النموذج إلى ملف
  • احذف النموذج.

إضافة واجهات برمجة التطبيقات إلى نموذج

يمكنك إضافة واجهات برمجة التطبيقات إلى أحد النماذج عن طريق:

  • استيراد ملف WADL يحتوي على تعريف واجهة برمجة التطبيقات
  • استيراد مواصفات OpenAPI (OpenAPI 2.0 أو 1.2)
  • إنشاء الموارد والطرق يدويًا

يمكنك أيضًا استيراد ملف JSON في Smart Docs إلى أحد النماذج. يتم إنشاء هذا الملف عادةً من خلال تصدير نموذج حالي أولاً وتعديل الملف ثم استيراد التعديلات. لمزيد من المعلومات، يمكنك الاطّلاع على قسم تصدير نموذج واستيراده أدناه.

فيديو: يمكنك مشاهدة فيديو قصير للتعرّف على كيفية إضافة واجهات برمجة التطبيقات إلى نموذج "مستندات ذكية" من خلال استيراد مواصفات OpenAPI.

استيراد WADL

بعد إنشاء نموذج بنجاح، يمكنك استيراد ملف WADL يصف واجهة برمجة التطبيقات الخاصة بك. في كل مرة تستورد فيها ملف WADL، يتم تلقائيًا إنشاء نسخة جديدة من النموذج.

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  3. اختَر النموذج الذي تريد تحديثه.
  4. ضمن العمليات، اختَر استيراد.
  5. اختَر WADL في القائمة المنسدلة اختيار التنسيق في صفحة استيراد Smart Docs.
  6. اختَر ملف أو عنوان URL في القائمة المنسدلة نوع التحميل.
    1. إذا اخترت ملف، انتقِل إلى ملف WADL.
    2. إذا اختَرت عنوان URL، حدِّد عنوان URL لملف WADL.
  7. انقر على استيراد لاستيراده إلى النموذج. ويمكنك الآن عرض النموذج.
  8. ستتم إعادة توجيهك إلى صفحة معلومات النموذج حيث يمكنك عرض النموذج.

استيراد مواصفات OpenAPI

بعد إنشاء نموذج بنجاح، يمكنك استيراد مواصفات OpenAPI (المعروفة سابقًا باسم Swagger). يدعم Edge الإصدار 1.2 و2.0 من OpenAPI.

يستخدم OpenAPI الملفات التي تحتوي على كائنات JSON لوصف واجهة برمجة التطبيقات. في كل مرة تستورد فيها مواصفات OpenAPI، يتم تلقائيًا إنشاء نسخة جديدة من النموذج.

لاستيراد مواصفات OpenAPI:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. حدد المحتوى > مستندات ذكية في قائمة إدارة Drupal.
  3. اختَر النموذج الذي تريد تحديثه.
  4. ضمن العمليات، اختَر استيراد.
  5. اختَر Swagger JSON أو Swagger YAML في القائمة المنسدلة اختيار تنسيق في صفحة استيراد Smart Docs.
  6. اختَر ملف أو عنوان URL في القائمة المنسدلة نوع التحميل (يجب اختيار عنوان URL للإصدار OpenAPI 1.2).
    1. إذا اخترت File (ملف)، انتقِل إلى مواصفات OpenAPI.
    2. إذا اخترت URL، حدِّد عنوان URL لمواصفات OpenAPI.
  7. انقر على استيراد لاستيراده إلى النموذج.
  8. ستتم إعادة توجيهك إلى صفحة معلومات النموذج حيث يمكنك عرض النموذج.

إنشاء الموارد والطرق يدويًا

إذا لم يكن لديك ملف WADL أو مواصفات OpenAPI التي تمثل واجهة برمجة التطبيقات، يمكنك إضافة واجهات برمجة التطبيقات يدويًا إلى نموذجك. بالإضافة إلى ذلك، إذا استخدمت ملف WADL أو مواصفات OpenAPI لإنشاء النموذج، يمكنك استخدام هذا الإجراء لتعديل واجهات برمجة التطبيقات الخاصة بك، بما في ذلك إضافة واجهات برمجة تطبيقات جديدة بعد الاستيراد.

لإضافة واجهة برمجة تطبيقات يدويًا:

  1. قم بإنشاء نسخة جديدة من النموذج.

    عند إنشاء المراجعة، يمكنك تحديد مسار أساسي واحد لجميع واجهات برمجة التطبيقات في النموذج، ما يعني أنّ جميع واجهات برمجة التطبيقات في نموذج ما تشترك في المسار الأساسي نفسه. على سبيل المثال، حدِّد المسار الأساسي على النحو التالي:

    https://myCompany.com/v1

    عند إضافة موارد إلى النموذج، يتم توسيع المسار الأساسي.
  2. حدد موردًا واحدًا أو أكثر للنموذج. يتم دمج مسار المورد مع المسار الأساسي لمراجعة النموذج لتحديد عنوان URL الكامل للمورد. على سبيل المثال، إذا كان المورد يحدّد مسار "/login"، سيكون عنوان URL الكامل للمورد هو:

    https://myCompany.com/v1/login
  3. حدد طريقة واحدة أو أكثر لكل مورد. تحدِّد الطريقة فعل HTTP الذي يمكن استدعاؤه في المورد. على سبيل المثال، بالنسبة إلى المورد "/login" (تسجيل الدخول)، يمكنك استخدام POST لتسجيل الدخول وDELETE لتسجيل الخروج. لا يتيح هذا المورد استخدام أفعال HTTP أخرى، مثل PUT أو GET. ومن ثم، حدد طريقتين للمورد، إحداهما لطريقة POST والأخرى لـ DELETE.

    تستخدم الطريقة عنوان URL للمورد من موردها الرئيسي. وبالتالي، يتم تحديد جميع الطرق التي لها عنوان URL نفسه ضمن مورد واحد في "مستندات Google الذكية".

كقاعدة عامة:

  • يمكنك إنشاء نموذج "مستندات ذكية" مختلف لكل مسار أساسي فريد في واجهة برمجة التطبيقات.
  • حدِّد مورد "مستندات ذكية" مختلفًا لكل مورد فريد في واجهة برمجة التطبيقات.
  • حدد طريقة SmartDocuments مختلفة لكل فعل HTTP متوافق مع أحد الموارد.

إنشاء نسخة جديدة من نموذج

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

لإنشاء نسخة جديدة من أحد النماذج:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. حدد المحتوى > مستندات ذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تعديله، اختَر إضافة نسخة سابقة ضمن العمليات.
  4. في صفحة Add API Revision (إضافة مراجعة لواجهة برمجة التطبيقات)، أدخِل المعلومات التالية:
    • الاسم المعروض: اسم النسخة السابقة كما يظهر في البوابة.
    • رقم تعريف الإصدار: معرّف قصير للنسخة السابقة.
    • الوصف: وصف النسخة السابقة.
    • عنوان URL للقاعدة: عنوان URL الأساسي لجميع واجهات برمجة التطبيقات في نسخة النموذج. ويمكن أن يستخدم النموذج عناوين URL أساسية مختلفة لكل نسخة سابقة. على سبيل المثال، يمكنك تضمين مؤشر الإصدار في عنوان URL الأساسي. بالنسبة إلى المراجعة الأولى للنموذج، يكون عنوان URL الأساسي على النحو التالي:
      https://myCompany.com/v1
      بالنسبة إلى النسخة السابقة، يمكن أن يكون عنوان URL الأساسي على النحو التالي:
      https://myCompany.com/v2
  5. اختَر إضافة نسخة سابقة. تتم إعادة توجيهك إلى صفحة مراجعة النموذج. يمكنك الآن تحديد الموارد في النموذج.

تعريف المورد

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

لتحديد مورد:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. حدد المحتوى > مستندات ذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تعديله، ضمن العمليات، اختَر مراجعات واجهة برمجة التطبيقات لعرض جميع المراجعات الخاصة بأحد النماذج.
  4. اختَر نسخة سابقة لتعديلها.
  5. في صفحة النسخة السابقة، حدد Add Resource (إضافة مورد) من القائمة المنسدلة.
  6. في صفحة إضافة مورد، أدخِل المعلومات التالية:
    • الاسم المعروض: اسم المورد.
    • المسار: مسار المورد، الذي يبدأ بـ "/". يتم دمج قيمة المسار مع عنوان URL الأساسي لنسخة النموذج لإنشاء عنوان URL الكامل للمصدر.
    • الوصف: وصف المورد.
    • المَعلمات: يمكنك إدخال كائن JSON الذي يحدّد كل مَعلمة على المورد اختياريًا. في ما يلي توضيح لهذه المَعلمات.
  7. اختَر إضافة مورد. ستتم إعادة توجيهك إلى صفحة النموذج. يمكنك الآن تحديد الطرق على المورد.

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

بدلاً من ذلك، يمكنك تحديد مُعلَّمات في إحدى الطرق. على سبيل المثال، قد تتوافق طريقة POST مع مَعلمات طلب البحث غير المتوافقة مع طريقة DELETE. وبالتالي، أضِف أي معلَمات خاصة بأي طريقة عند تعريفها، كما هو موضّح أدناه.

تعرِض الصورة التالية صفحة حالية في "مستندات ذكية" لواجهة برمجة التطبيقات الموافقة على Apigee أو إبطالها لواجهة برمجة التطبيقات مع تمييز كل نوع من أنواع المَعلمات:

يُحدَّد كل نوع من أنواع المَعلمات من خلال كائن JSON:

Type

كائن JSON

Notes

النموذج

{
"dataType": "string",
"defaultValue": "",
"description": "اسم المؤسسة.",
"name": "org_name",
"مطلوب": صحيح،
"type": "TEMPLATE"
}

تكون مَعلمات النموذج مطلوبة دائمًا، لذا اضبط السمة required على true، واحذف القيمة إلى defaultValue.

تظهر قيمة description في نافذة منبثقة عندما يمرِّر المستخدم مؤشر الماوس فوق عنوان URL في صفحة Smart Docs.

طلب

{
"dataType": "string",
"defaultValue": "",
"description": "الموقع.",
"name": "w",
"مطلوب": صحيح,
"type": "QUERY"
}

مع ذلك، يمكن لمَعلمات طلب البحث المطلوبة تحديد defaultValue، ولكن في كثير من الأحيان لا يمكن ذلك.

بالنسبة إلى مَعلمات طلب البحث الاختيارية، اضبط السمة required على false وحدِّد قيمة على defaultValue.

العنوان

{
"dataType": "string",
"defaultValue": "application/json",
"description": "التحديد كـ <code>application/json</code>.",
"name": "Content-Type",
"required": true,
"type": "Header"
}

لاحظ كيف يمكنك استخدام علامات HTML في الوصف.

تحدِّد مَعلمة النموذج متغيّرًا في مسار الموارد. على سبيل المثال، يمكنك تحديد معلَمتين للنموذج على المورد. لاحِظ كيف يتم فصل كل تعريف معلَمة في مصفوفة المعلَمات بفاصلة:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

يمكنك بعد ذلك استخدام معلمات النموذج في تعريف مسار المورد، والذي يقع ضمن "{}". على سبيل المثال، يمكنك ضبط المسار على:

/login/{org_name}/{developer_email}

في صفحة واجهة برمجة تطبيقات Smart Docs، على المستخدم تعديل عنوان URL لتحديد الجزء org_name وdeveloper_email من عنوان URL قبل أن يتمكن من إرسال طلب.

تعريف طريقة

حدد طريقة واحدة أو أكثر لكل مورد. يحدّد تعريف الطريقة فعل HTTP الذي يمكن استدعاؤه في المورد. يمكن أن يتضمن المورد طريقة واحدة محددة أو عدة طرق.

كجزء من تحديد الطريقة، يجب تحديد أي معلَمات تستخدمها الطريقة، بما في ذلك معلَمات طلب البحث والعنوان. اطّلِع على الوصف أعلاه للحصول على معلومات عن إضافة معلَمات إلى طريقة معيّنة.

تُظهر الصورة التالية صفحة Smart Docs الحالية لواجهة برمجة تطبيقات إنشاء مطوّر Apigee مع تمييز كل منطقة من الصفحة بالقيمة المقابلة التي حددتها عند تحديد إحدى الطرق:

تعرِض الصورة التالية الصفحة نفسها ولكن مع اختيار "وصف نص الطلب":

لتحديد طريقة:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. حدد المحتوى > مستندات ذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تعديله، ضمن العمليات، اختَر مراجعات واجهة برمجة التطبيقات لعرض جميع المراجعات الخاصة بأحد النماذج.
  4. اختَر نسخة سابقة لتعديلها.
  5. في صفحة المراجعة، اختَر Add Method (إضافة طريقة) من القائمة المنسدلة لأحد الموارد.
  6. في صفحة تعديل الطريقة، أدخِل المعلومات التالية:
    • الاسم المعروض: اسم واجهة برمجة التطبيقات، والذي يصبح أيضًا عنوانًا لصفحة Drupal لواجهة برمجة التطبيقات.
    • الوصف: وصف واجهة برمجة التطبيقات
    • الطريقة الفعل: نوع فعل HTTP.
    • أنظمة الأمان: حدِّد وضع المصادقة للطريقة إن وجد. ولمزيد من المعلومات، يُرجى الاطّلاع على ضبط نوع مصادقة "المستندات الذكية".
    • نوع المحتوى: نوع محتوى الطلب والردّ. راجِع القسم أدناه حول ضبط طُرق المصادقة المختلفة.
    • المَعلمات: (اختياري) أي مَعلمات طلب بحث أو عنوان للطريقة. راجِع الوصف أعلاه لإضافة مَعلمة إلى مورد معيّن للحصول على مزيد من المعلومات.
    • مستندات نص الطلب: (اختياري) يُرجى وصف نص الطلب. تأخذ طريقتا POST وPUT نص الطلب. يمكنك استخدام هذه المنطقة لوصفها. إذا حذفت هذه القيمة، سيتم حذف رابط الوصف ضمن نص الطلب من صفحة "مستندات Google الذكية" التي تم إنشاؤها.
    • مثال لنص الطلب: (اختياري) اعرض مثالاً لنص الطلب، عادةً ككائن JSON أو XML. بالنسبة إلى أفعال POST وPUT، يتم تمرير مثال نص الطلب كجزء من كل طلب. يعدّل مستخدمو صفحة SmartDocuments هذا المثال قبل إرسال طلب إلى واجهة برمجة التطبيقات. إذا حذفت هذه القيمة، سيتم حذف رابط القيمة ضمن نص الطلب من صفحة "مستندات ذكية" التي تم إنشاؤها.
    • العلامات: مصفوفة من العلامات المرتبطة بواجهة برمجة التطبيقات. تستخدم ميزة "مستندات Google" العلامات لتجميع واجهات برمجة التطبيقات المتشابهة معًا. على سبيل المثال، يمكنك تطبيق العلامة "الإحصاءات" على جميع واجهات برمجة التطبيقات المتعلّقة بالإحصاءات. يمكنك تجميع واجهات برمجة التطبيقات من موارد مختلفة ضمن علامة واحدة إذا كانت جميعها تستخدم العلامة نفسها.
  7. اختَر إضافة طريقة. ستتم إعادة توجيهك إلى صفحة النموذج. يمكنك الآن عرض الطريقة ونشرها.

عرض نموذج

بعد إضافة واجهات برمجة تطبيقات إلى نموذج، يمكنك عرض النموذج. يحوِّل العرض وصف النموذج لواجهة برمجة التطبيقات إلى عُقد Drupal. عند اكتمال العرض، ستكون لديك عقدة Drupal واحدة لكل واجهة برمجة تطبيقات، حيث تتطابق كل عقدة Drupal مع صفحة HTML.

ويمكنك اختيار عرض النموذج بأكمله في آنٍ واحد أو اختيار واجهات برمجة تطبيقات فردية للعرض.

لعرض نموذج:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. حدد المحتوى > مستندات ذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد عرضه، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. اختَر النسخة السابقة التي تريد عرضها. يمكنك عرض العُقد فقط من نسخة سابقة واحدة من النموذج.
  5. اختَر طرق العرض.
  6. اختَر عُقد العرض من القائمة المنسدلة خيارات التحديث.
  7. انقر على تعديل.
  8. ستظهر شاشة تحميل للاطّلاع على مستوى التقدّم المحرز في العُقد التي يتم عرضها.
    بعد عرض العُقد، يظهر رقم تعريف عقدة Drupal لكل واجهة برمجة تطبيقات ضمن العمود Node Association (ربط العُقد) في النموذج. انقر على الرابط في العمود ارتباط العُقد لرؤية العقدة المعروضة.

بدلاً من اختيار عُقد العرض، يمكنك اختيار عرض ونشر العُقد لعرض واجهات برمجة التطبيقات ونشرها فورًا كعقدة Drupal.

عُقد النشر

لا تكون العُقدة مرئية لمستخدمي البوابة حتى يتم نشرها. يمكنك اختياريًا نشر العُقد أثناء عملية العرض. إذا اخترت عدم نشر العُقد، عليك نشرها يدويًا بعد اكتمال العرض.

لنشر عقدة:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد نشره، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. اختَر النسخة السابقة التي تريد نشرها. يمكنك فقط نشر العُقد من نسخة واحدة من النموذج.
  5. اختَر طُرق النشر.
  6. اختَر العُقد في النسخة السابقة لنشرها.
  7. اختَر عُقد النشر من القائمة المنسدلة خيارات التعديل.
  8. انقر على تعديل.
  9. انتقِل إلى العُقدة عن طريق اختيار رقم تعريفها ضمن العمود ربط العُقدة.

بشكل تلقائي، يكون عنوان URL الخاص بـ Drupal لعقدة واجهة برمجة تطبيقات منشورة على النحو التالي: http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>. استخدِم الإجراء التالي للتحكّم في شكل عنوان URL:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر الضبط > البحث والبيانات الوصفية > الأسماء المستعارة لعناوين URL > الأنماط في قائمة إدارة Drupal.
  3. ضمن النمط لجميع مسارات طريقة "مستندات Google الذكية"، حدِّد الطريقة التي تريد إنشاء المسار بها.
  4. اختَر حفظ الإعدادات.

بسبب التخزين المؤقت على البوابة، قد لا تظهر صفحات النماذج مباشرةً بعد نشرها. إذا لزم الأمر، يمكنك محو ذاكرة التخزين المؤقت لملف HTML في "مستندات Google الذكية" يدويًا من خلال اتّباع الإجراء التالي:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر الضبط > Smart Docs في قائمة إدارة Drupal.
  3. انقر على إعادة إنشاء ذاكرات التخزين المؤقت لنموذج "مستندات Google".

إلغاء نشر عقدة

يمكنك إلغاء نشر عقدة منشورة في أي وقت. يؤدي إلغاء نشر أي عقدة إلى عدم ظهورها لمستخدمي البوابة.

لإلغاء نشر عقدة:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد إلغاء نشره، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. اختَر النسخة السابقة من النموذج للعقدة التي تريد إلغاء نشرها.
  5. اختَر العُقد في النسخة السابقة لإلغاء نشرها.
  6. اختَر العُقد إلغاء النشر من القائمة المنسدلة خيارات التحديث.
  7. انقر على تعديل.

عرض نسخة سابقة من نموذج

يمكنك إنشاء نسخة جديدة من نموذج عن طريق استيراد ملف WADL جديد أو مواصفات OpenAPI إلى نموذج حالي، أو من خلال إنشاء نسخة جديدة يدويًا. بعد إنشاء النسخة الجديدة، يمكنك عرض النسخة السابقة ونشرها، وهي تحل محل عُقد Drupal المنشورة حاليًا.

يمكنك عرض العُقد ونشرها من نُسخ متعددة في الوقت نفسه. ويعني ذلك أنّه إذا كان لديك خمس مراجعات للنموذج، يمكنك نشر العُقد من جميع المراجعات أو جميعها. مع ذلك، يؤدي نشر واجهة برمجة تطبيقات في نموذج مماثل لعقدة منشورة من نموذج آخر إلى إلغاء نشر الإصدار القديم من واجهة برمجة التطبيقات واستبداله بالنسخة الحديثة من واجهة برمجة التطبيقات التي تم نشرها مؤخرًا.

للاطّلاع على النسخة السابقة من أحد النماذج:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > "المستندات الذكية" في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تحديثه، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. حدد نسخة النموذج التي تريد عرضها.
  5. اعرض العُقد وانشرها كما هو موضّح أعلاه.

تعديل عقدة

بعد عرض عقدة، يمكنك تعديلها باستخدام محرر Drupal. على سبيل المثال، يمكنك تعديل فعل HTTP ووصف واجهة برمجة التطبيقات، أو إضافة طلب بحث أو مَعلمة عنوان جديدة إلى واجهة برمجة التطبيقات. يمكنك تعديل العُقد التي تم إنشاؤها من ملف WADL أو مواصفات OpenAPI، أو العُقد التي تم إنشاؤها يدويًا.

يمكنك أيضًا تحرير ملف WADL الأصلي أو OpenAPI Specification. عند الانتهاء من التعديل، يجب استيراد ملف WADL أو مواصفات OpenAPI إلى النموذج كنسخة جديدة، ثم عرض التغييرات ونشرها كما هو موضّح أعلاه.

لتعديل عقدة باستخدام محرِّر Drupal:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. تصفَّح للوصول إلى عقدة Drupal المقابلة لمستندات واجهة برمجة التطبيقات التي تريد تعديلها.
  3. اختَر تعديل لاستخدام محرِّر Drupal.
  4. بعد إكمال التعديلات، انقر على تعديل الطريقة.

بدلاً من ذلك، يمكنك تعديل العُقدة من نموذج Smart Docs:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تحديثه، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. حدد نسخة النموذج التي تريد نشرها.
  5. اختر تعديل الطريقة في القائمة المنسدلة العمليات للطريقة التي تريد تعديلها.

لحذف عقدة:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تحديثه، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. حدد نسخة النموذج التي تريد نشرها.
  5. اختَر حذف الطريقة في القائمة المنسدلة العمليات للطريقة.
    تنبيه: يؤدي حذف العُقدة إلى إزالة واجهة برمجة التطبيقات أيضًا من النموذج. إذا كنت تريد فقط إلغاء نشر واجهة برمجة التطبيقات كي تكون مخفية عن مستخدمي البوابة، ولكنك لا تريد حذفها من النموذج، عليك إلغاء نشر العُقدة كما هو موضّح أعلاه.

وتحتوي البوابة على تقرير مضمَّن يعرض معلومات حول أي عقدة يعرضها نموذج Smart Docs والتي لم تعُد تشير إلى طرق صالحة للنموذج. يمكنك الوصول إلى التقرير من خلال اختيار التقارير في قائمة Drupal ثم اختيار التقرير باسم حالة عقدة Smart Docs.

تصدير نموذج واستيراده

تتيح لك Smart Docs تصدير نموذج حالي إلى ملف. على سبيل المثال، يمكنك تعريف بيئة إنتاج وبيئة مرحلية. ويمكنك بعد ذلك إجراء جميع تعديلات "مستندات Google الذكية" في بيئة التقسيم. عندما تكون جاهزًا لإصدار واجهات برمجة التطبيقات، يمكنك تصدير النموذج المرحلي واستيراده إلى نموذج الإنتاج.

يؤدي استيراد نموذج إلى إنشاء نسخة جديدة من النموذج. تحاول ميزة "المستندات الذكية" مطابقة واجهات برمجة التطبيقات الحالية في النموذج مع واجهات برمجة التطبيقات التي تم استيرادها. في حال رصدت ميزة "المستندات الذكية" مطابقة، تعمل عملية الاستيراد على تعديل عقدة Drupal المقابلة لواجهة برمجة التطبيقات الحالية. إذا لم تكتشف أداة Smart Docs أي تطابق، ستنشئ عملية الاستيراد عقدة Drupal جديدة لواجهة برمجة التطبيقات.

على سبيل المثال، لديك POST API تتوافق مع عقدة Drupal ذات المعرف 91. بعد ذلك، يتم استيراد نموذج وترصد ميزة "المستندات الذكية" أي تطابق بين POST API في النموذج الذي تم استيراده وPOST API الحالية. سيؤدي إجراء أي تعديلات على POST API إلى تعديل عقدة Drupal رقم 91. إذا لم ترصد أداة Smart Docs أي مطابقة، ستنشئ عقدة Drupal جديدة بمعرّف جديد.

ويُجري Drupal عملية المطابقة باستخدام الخصائص التالية لواجهة برمجة التطبيقات:

  • internalName: اسم النموذج الداخلي
  • httpMethod: هو أسلوب HTTP لواجهة برمجة التطبيقات، مثل: GET أو PUT أو POST أو DELETE.
  • resourcePath: مسار الموارد
  • مَعلمات طلب البحث: أي مَعلمات طلب بحث تستخدمها واجهة برمجة التطبيقات.

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

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

  • revisionNumber
  • createdTime
  • modifiedTime
  • apiRevisionId
  • resourceId

لتصدير نموذج:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > "المستندات الذكية" في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تصديره، اختَر تصدير ضمن العمليات.
  4. اختَر نوع ملف التصدير بتنسيق Smart Docs JSON.
  5. انقر على تصدير.
  6. سيُطلب منك حفظ الملف على القرص أو فتحه في أحد برامج التحرير.

لاستيراد نموذج:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > "المستندات الذكية" في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد استيراده، اختَر استيراد ضمن العمليات.
  4. حدِّد Smart Docs JSON في القائمة المنسدلة اختيار التنسيق.
  5. اختَر ملف أو عنوان URL في نوع التحميل:
    1. إذا اخترت ملف، انتقِل إلى ملف JSON.
    2. في حال اختيار عنوان URL، حدِّد عنوان URL لملف JSON لـ Smartالمستندات.
  6. انقر على استيراد لاستيراده إلى النموذج.
  7. ستتم إعادة توجيهك إلى صفحة معلومات النموذج حيث يمكنك عرض النموذج. تجدر الإشارة إلى أنّ عملية الاستيراد تُنشئ نسخة جديدة من النموذج.
  8. اعرض العُقد ونشرها.

تعديل نموذج "مستندات Google"

يحدِّد نموذج Smart Docs كيفية ظهور عُقد Drupal على الشاشة. ويمكن أن يستخدم كل نموذج من نماذج "مستندات Google الذكية" النموذج التلقائي نفسه أو يمكنك تخصيص النموذج المستخدَم في نموذج فردي.

يتضمن نموذج Smart Docs ملف نموذج تم ترميزه كملف Handlebars .hbr وملفات CSS وملفات JavaScript. وباستخدام الأشرطة، يتم تحديد جزء كبير من المحتوى استنادًا إلى تعبيرات المقبضين المضمّنة، مثل &123;&123;body}}. يتم توفير قائمة بتعبيرات الشريط المقبض الحالية في تعليق أعلى الملف. وللحصول على معلومات عن استخدام الأشرطة لتخصيص النماذج، يمكنك الاطّلاع على http://handlebarsjs.com.

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

تحميل ملف نموذج Smart Docs

يمكنك تحميل ملف نموذج Smartdocs مخصّص، كملف Handlebars. ، بتنسيق hbr. لاستخدامه كنموذج تلقائي عند إنشاء نماذج جديدة أو استيراد واجهات برمجة تطبيقات جديدة إلى نموذج حالي.

إذا أردت استخدام ملف نموذج Smart Docs التلقائي كنقطة بداية عند إنشاء ملف نموذج Smartالمستندات المخصص لك، يمكنك تنزيل نسخة من: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr

لتحميل ملف نموذج Smart Docs:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر التهيئة > مستندات ذكية في قائمة إدارة Drupal.
  3. وسِّع منطقة الإعدادات المتقدمة في الصفحة.
  4. ضمن "تحميل نموذج طريقة مخصصة"، انقر على اختيار ملف، وانتقل إلى ملف Handlebars .hbr.
  5. انقر على تحميل.
  6. انقر على حفظ الضبط.

استعادة ملف نموذج Smart Docs التلقائي

يمكنك استعادة الملف التلقائي لنموذج "مستندات Google" الذكية. بعد استعادة الملف، سيتم استخدام ملف نموذج Smartالمستندات التلقائية عند إنشاء نماذج جديدة أو استيراد واجهات برمجة تطبيقات جديدة إلى نموذج حالي.

لاستعادة الملف التلقائي لنموذج "مستندات Google":

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر التهيئة > مستندات ذكية في قائمة إدارة Drupal.
  3. وسِّع منطقة الإعدادات المتقدمة في الصفحة.
  4. ضمن "تحميل نموذج طريقة مخصّصة"، انقر على إزالة بجوار ملف نموذج "مستندات Google" المخصّصة.
  5. انقر على حفظ الضبط.

تعديل نموذج Smartالمستندات لنموذج فردي

يمكنك تعديل النموذج المستخدم لنموذج فردي.

لتعديل النموذج الخاص بنموذج فردي:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختَر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج الذي تريد تعديله، اختَر الإعدادات ضمن العمليات.
  4. في منطقة "نموذج الطريقة"، عدِّل النموذج حسب الحاجة.
  5. انقر على حفظ النموذج.
  6. تصفَّح للوصول إلى عقدة Drupal. من المفترض أن تظهر لك تغييرات النموذج على الصفحة.

ضبط نوع مصادقة "المستندات الذكية"

يمكن أن تكون واجهات برمجة التطبيقات المحدّدة في Smartالمستندات إما مفتوحة، ما يعني عدم الحاجة إلى استخدام بيانات اعتماد للمصادقة للوصول إليها أو تأمينها. تتطلّب واجهة برمجة التطبيقات الآمنة إدخال بيانات الاعتماد عند الاتصال بواجهة برمجة التطبيقات.

للحصول على واجهة برمجة تطبيقات آمنة، يتوافق تطبيق SmartDocuments مع الأنواع التالية من المصادقة:

  • المصادقة الأساسية: يجب إدخال بيانات اعتماد المصادقة الأساسية كاسم مستخدم وكلمة مرور. إذا لم تحدّد استخدام OAuth كنوع بيانات الاعتماد، سيتم ضبط واجهة برمجة التطبيقات تلقائيًا على استخدام المصادقة الأساسية.
  • OAuth 2.0: يصادق مقدِّم الخدمة التابع لجهة خارجية على بيانات اعتماد المستخدم، ويضمن أن يكون للمستخدم تفويضًا لواجهة برمجة التطبيقات، ثم يصدر رمز دخول. عند تقديم طلب في "مستندات Google الذكية" إلى واجهة برمجة تطبيقات محمية، تنشئ أداة Smart Docs الطلب وترسله إلى مقدِّم الخدمة. بعد ذلك، يتحقّق مقدّم الخدمة من الرمز المميّز ويضمن عدم انتهاء صلاحيته.
  • الرمز المميّز المخصّص: تمرير قيمة رمز مميز ليكون عنوان أو مَعلمة طلب بحث لكل طلب

بالنسبة إلى كل نوع من أنواع المصادقة، يمكنك إنشاء نظام أمان يحدّد خصائص المصادقة. على سبيل المثال، بالنسبة إلى مصادقة الرمز المميّز المخصّص، يحدّد نظام الأمان كيفية تمرير الرمز المميّز (العنوان ومَعلمة طلب البحث ومَعلمة النص) واسم الرمز المميّز.

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

في ملف WADL، يمكنك تحديد ما إذا كانت واجهة برمجة التطبيقات تتطلّب المصادقة باستخدام علامة Apigee: <apigee:authentication>، كما هو موضّح أدناه:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method> 

إذا كانت واجهة برمجة التطبيقات مفتوحة، اضبط السمة مطلوبة على false.

تجدر الإشارة إلى أنّه لا يمكنك تحديد نوع المصادقة في ملف WADL. ويمكنك إجراء ذلك من خلال تعديل العقدة في Drupal. لمزيد من المعلومات حول ملفات WADL، يُرجى الاطّلاع على مرجع WADL.

في صفحة واجهة برمجة التطبيقات في Drupal، يضيف تطبيق Smart Docs الزر التالي للسماح للمستخدمين بتحديد بيانات اعتماد المصادقة الأساسية:

في حال عدَّلت العُقدة لضبط نوع المصادقة على OAuth، ستُضيف ميزة "المستندات الذكية" الزر التالي إلى الصفحة:

بالنسبة إلى الرمز المميّز المخصّص، تضيف SmartDocuments ما يلي:

ضبط المصادقة الأساسية

إذا كنت تستخدم المصادقة الأساسية مع واجهة برمجة التطبيقات، ما عليك سوى تحديد العلامة <apigee:authentication> في ملف WADL الذي تستخدمه لإنشاء النموذج.

لتطبيق المصادقة الأساسية على طرق تم إنشاؤها من مصدر آخر غير ملف WADL:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج المطلوب، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. بالنسبة إلى النسخة السابقة من النموذج التي تريد تعديلها، اختَر إعدادات الأمان ضمن العمليات.
  5. اختَر إضافة نظام أمان.
  6. حدِّد اسم نظام الأمان.
  7. اختر أساسي باعتباره النوع.
  8. اختَر إرسال.
  9. لكل طريقة في النموذج، عدِّل الطريقة لضبط نظام الأمان الخاص بها على المخطط الأساسي.
    1. اختر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
    2. بالنسبة إلى النموذج المطلوب، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
    3. بالنسبة إلى مراجعة النموذج التي تريد تعديلها، اختَر تفاصيل المراجعة ضمن العمليات.
    4. اختَر تعديل الطريقة لواجهة برمجة التطبيقات التي تريد تعديلها.
    5. اختر نظام الأمان لواجهة برمجة التطبيقات.
    6. احفظ واجهة برمجة التطبيقات.

ضبط مصادقة OAuth 2.0

يمكنك ضبط نموذج لاستخدام OAuth 2.0 في Smart Docs، بدلاً من المصادقة الأساسية التلقائية. عند ضبط بروتوكول OAuth في مكانَين، هما:

  1. يمكنك إنشاء مخطط أمان لكل نسخة سابقة من النموذج ضمن إعدادات الأمان للنسخة السابقة.
  2. حدِّد معرّف العميل وسر العميل لجميع النُسخ السابقة من النموذج ضمن الإعدادات للنموذج.

لتفعيل OAuth:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج المطلوب، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. بالنسبة إلى نسخة النموذج التي تريد تعديلها، اختَر إعدادات الأمان ضمن العمليات.
  5. اختَر إضافة نظام أمان.
  6. حدِّد اسم نظام الأمان.
  7. اختَر OAuth 2.0 بصفته النوع.
  8. اضبط نوع المنح.
  9. أدخِل القيم في حقول عنوان URL للتفويض. يتم استخدام عنوان URL للتفويض للحصول على رمز الدخول.
  10. اضبط فعل التفويض على أنّه GET أو POST.
  11. أدخِل عنوان URL لرمز الدخول. عنوان URL لرمز الدخول هو عنوان URL المستخدَم لاستبدال رمز الطلب برمز الدخول.
  12. أدخِل اسم مَعلمة رمز الدخول.
  13. استخدِم In لتحديد كيفية تمرير الرمز المميّز: العنوان أو طلب البحث أو النص الأساسي.
  14. اضبط نطاقات OAuth.
  15. اختَر إرسال.
  16. اختر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  17. بالنسبة إلى النموذج، اختَر الإعدادات في القائمة المنسدلة العمليات.
  18. أدخِل القيم في معرّف العميل وسر العميل.
  19. اختَر حفظ إعدادات مصادقة النماذج.
  20. لكل طريقة في النموذج، عدِّل الطريقة لضبط نظام الأمان الخاص بها على نظام أمان OAuth.
    1. اختر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
    2. بالنسبة إلى النموذج المطلوب، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
    3. بالنسبة إلى مراجعة النموذج التي تريد تعديلها، اختَر تفاصيل المراجعة ضمن العمليات.
    4. اختَر تعديل الطريقة لواجهة برمجة التطبيقات التي تريد تعديلها.
    5. اختر نظام الأمان لواجهة برمجة التطبيقات.
    6. احفظ واجهة برمجة التطبيقات.

ضبط مصادقة الرمز المميّز المخصّص

يمكنك ضبط نموذج لاستخدام مصادقة مخصّصة مع رمز مميّز.

لتفعيل الرموز المميّزة المخصّصة:

  1. سجّل الدخول إلى المنصة كمستخدم لديه امتيازات المشرف أو امتيازات إنشاء المحتوى.
  2. اختر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
  3. بالنسبة إلى النموذج المطلوب، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
  4. بالنسبة إلى النسخة السابقة من النموذج التي تريد تعديلها، اختَر إعدادات الأمان ضمن العمليات.
  5. اختَر إضافة نظام أمان.
  6. حدِّد اسم نظام الأمان.
  7. اختَر Apikey باعتباره النوع.
  8. اضبط اسم المَعلمة التي تتضمّن الرمز المميّز.
  9. استخدِم In لتحديد كيفية تمرير الرمز المميّز: العنوان أو طلب البحث أو النص الأساسي.
  10. اختَر إرسال.
  11. بالنسبة إلى كل طريقة في النموذج، عدِّل الطريقة لضبط نظام الأمان الخاص بها على مخطط الرمز المميّز.
    1. اختر المحتوى > المستندات الذكية في قائمة إدارة Drupal.
    2. بالنسبة إلى النموذج المطلوب، اختَر مراجعات واجهة برمجة التطبيقات ضمن "العمليات".
    3. بالنسبة إلى مراجعة النموذج التي تريد تعديلها، اختَر تفاصيل المراجعة ضمن العمليات.
    4. اختَر تعديل الطريقة لواجهة برمجة التطبيقات التي تريد تعديلها.
    5. اختر نظام الأمان لواجهة برمجة التطبيقات.
    6. احفظ واجهة برمجة التطبيقات.

حذف نموذج

عند حذف نموذج (المحتوى > المستندات الذكية وحذف في حقل العمليات في Drupal)، يتم حذف النموذج من مؤسسة Edge. ويعني ذلك أنّه إذا كانت بوابات أخرى تشير إلى النموذج، لم يعُد النموذج متوفرًا. لمزيد من المعلومات، يمكنك الاطّلاع على لمحة عن نماذج SmartDoc ونماذجها.