المحتويات

المقدمة

المتطلبات الأساسية

المتطلبات

المكونات المستخدمة

معلومات أساسية

طلب واجهة برمجة التطبيقات والاستجابة

التكوين

CMS 2.9 والإصدارات الأحدث

تكوين كائن API

تعديل كائن API تم إنشاؤه بالفعل

حذف كائن API من قائمة API

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

HTTP POST

HTTP GET

HTTP PUT

حذف HTTP

عملاء واجهة برمجة التطبيقات

ملصق

ساعي البريد

التحقق من الصحة

استكشاف الأخطاء وإصلاحها

المقدمة

يصف هذا المستند وظائف API الأساسية الأربع (واجهة برنامج التطبيق) GET، POST، PUT، Delete المستخدمة على CMS (خادم الاجتماعات من Cisco). اعتبارا من CMS 2.9، تحتوي واجهة المستخدم الرسومية (GUI) الخاصة بإدارة الويب على قائمة واجهة برمجة تطبيقات (API) متوفرة ضمن قائمة التكوين. يراجع هذا وثيقة أن قائمة جديد ويصف أيضا إثنان مختلف API أداة: الملصق والبريد وكيفية إستخدامهم ل CMS تشكيل.

المتطلبات الأساسية

المتطلبات

لا توجد متطلبات خاصة لهذا المستند.

المكونات المستخدمة

لا يقتصر هذا المستند على إصدارات برامج ومكونات مادية معينة.

يمكن إستخدام المعلومات الواردة في هذا المستند مع CMS 2.9 والإصدارات الأحدث أو مع عملاء واجهة برمجة التطبيقات (API) المختلفة مثل Postman أو Poster. يتم وصف هذه الأدوات الخاصة بالجهات الخارجية في قسم عملاء واجهة برمجة التطبيقات (API) في الوثيقة.

تم إنشاء المعلومات الواردة في هذا المستند من الأجهزة الموجودة في بيئة معملية خاصة. بدأت جميع الأجهزة المُستخدمة في هذا المستند بتكوين ممسوح (افتراضي). إذا كانت شبكتك مباشرة، فتأكد من فهمك للتأثير المحتمل لأي أمر.

معلومات أساسية

واجهة برمجة التطبيقات ل CMS هي طريقة مرنة للغاية لتكوين العديد من مميزاتها. هناك العديد من ميزات واجهة برمجة التطبيقات (API) كثيرة جدا لحفظ أو تغطية هنا، لذلك تأكد من الرجوع إلى الوثائق المرجعية لواجهة برمجة التطبيقات (API) الحالية. اعتبارا من وقت هذه الكتابة، تكون أدلة مرجع واجهة برمجة التطبيقات الحالية متاحة هنا.

طلب واجهة برمجة التطبيقات والاستجابة

اتصال واجهة برمجة التطبيقات (API) هي علاقة طلب-إستجابة بين العملاء والخوادم. يقوم العميل بطلب من الخادم. بعد معالجة الطلب (إكمال إجراء أو رفض القيام بذلك) يتم إرجاع رد.

والطلبات الأربعة المبينة في هذه المقالة هي:

1. GET - إسترداد المعلومات الموجودة

2. POST - إنشاء معلومات جديدة

3. PUT - يعدل المعلومات الموجودة

4. حذف - يحذف المعلومات الموجودة.

هذه هي طلبات واجهة برمجة التطبيقات الأساسية المستخدمة لتكوين CMS.

الاستجابة الأكثر شيوعا هي 200 OK. الاستجابات الأخرى هي 4xx و 5xx، وهي استجابات الخطأ.

التكوين

CMS 2.9 والإصدارات الأحدث

قام CMS 2.9 بتقديم قائمة واجهة برمجة تطبيقات جديدة تجعل من السهل جدا على المسؤولين تعديل الإعدادات وضبط إعدادات الضبط في CMS.  عند إستخدام القائمة، يتم عرض كافة المعلمات المتوفرة، مما يجعل من السهل والسريع تغيير الإعدادات وتمكين الميزات الجديدة.

تكوين كائن API

بمجرد أن تكون في قائمة API، يمكنك تصفية كائنات API إلى ما تريد تحريره/إنشائه ثم انقر السهم الأسود الموجود بجوار الكائن لعمل تلك التغييرات. يوضح هذا المثال كيفية البحث عن CallLegProfile وإنشاء CallLegProfile جديد.

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

تعديل كائن API تم إنشاؤه بالفعل

عندما تقوم بتغيير الإعدادات في كائن ما، سترى زر التعديل في الأسفل. هذا هو نفس PUT من أدوات الطرف الثالث.

حذف كائن API من قائمة API

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

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

يتم شرح الطلبات الأساسية الأربعة من خلال مثال تكوين.

HTTP POST

الخطوة 1. أستخدم POST لإنشاء كائن.

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

يحتوي القسم 6-2 على معلومات عن كيفية إنشاء مساحة مشتركة وتعديلها.

الجملة الأولى تقول أنه لإنشاء مسافة، تحتاج إلى إرسال منشور إلى /coSpaces. بعد ذلك، يقول أن معرف المساحة سيكون في رأس موقع ال 200 موافق. عظيم، أنت الآن تعرف كيف تنشئ فضاء. أنت فقط أرسلت POST إلى https://<WebAdminIP>/API/V1/CoSpaces.

حدد محددات POST.

في القسم 6.2 من التوثيق ترى جدولا يسرد كافة المعلمات التي يمكنك إستخدامها.

على سبيل المثال: إنشاء مساحة باستخدام اسم APITest وجزء مستخدم URI من APITestURI

نوع المحتوى هو التطبيق/x-www-form-urlencoded والمحتوى هو name=APITest&uri=APITestURI

عند إضافة هذه المعلمات يكون الطلب مكتملا، كما هو موضح في الصورة.

POST https://<WebAdminIP>/api/v1/coSpaces HTTP/1.1

Host: <WebAdminIP>

Content-Type: application/x-www-form-urlencoded

Content-Length: 27

Authorization: Basic YWRtaW46QzFzYzBDMXNjMA==

Connection: keep-alive

name=APITest&uri=APITestURI

تعرض الصورة إستجابة للطلب السابق.

HTTP/1.1 200 OK

Server: Apache

X-Frame-Options: DENY

Strict-Transport-Security: max-age=31536000; includeSubDomains

Location: /api/v1/coSpaces/70ca0ed7-4e50-428c-b9ab-4e68faeb86ae

Vary: Accept-Encoding

Content-Encoding: gzip

Keep-Alive: timeout=5, max=100

Connection: Keep-Alive

Transfer-Encoding: chunked

لاحظ رأس الموقع في الاستجابة.

Location: /api/v1/coSpaces/70ca0ed7-4e50-428c-b9ab-4e68faeb86ae

70ca0ed7-4e50-428c-b9ab-4e68faeb86ae هو معرف المساحة المنشأة حديثا. يكون المعرف مفيدا عندما تحتاج إلى إنشاء طلبات واجهة برمجة تطبيقات مستقبلية تستهدف نفس المساحة.

يمكن رؤية المساحة في WebAdmin ل CMS. انتقل إلى التكوين > المسافات.

تلخص الصورة مادة نشر الطلب.

HTTP GET

الخطوة 2. بعد إنشاء المساحة، اسحب التكوين الخاص بها.

أستخدم أسلوب HTTP GET لهذا الغرض.

أستخدم معرف المساحة التي تم إنشاؤها من رأس الموقع. عنوان URL هو https://<WebAdminIP>/api/v1/coSpaces/70ca0ed7-4e50-428c-b9ab-4e68faeb86ae.  تنفيذ GET على هذه الصفحة.

مثال على طلب GET:

GET https://<WebAdminIP>/api/v1/coSpaces/70ca0ed7-4e50-428c-b9ab-4e68faeb86ae HTTP/1.1

Host: <WebAdminIP>

User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Accept-Language: en-US,en;q=0.5

Accept-Encoding: gzip, deflate, br

Cookie: session=logout

Authorization: Basic YWRtaW46QzFzYzBDMXNjMA==

Connection: keep-alive

إستجابة لطلب GET:

HTTP/1.1 200 OK

Server: Apache

X-Frame-Options: DENY

Strict-Transport-Security: max-age=31536000; includeSubDomains

Content-Type: text/xml

Vary: Accept-Encoding

Content-Length: 159

Keep-Alive: timeout=5, max=100

Connection: Keep-Alive

<?xml version="1.0"?><coSpace id="70ca0ed7-4e50-428c-b9ab-4e68faeb86ae"><name>APITest</name><autoGenerated>false</autoGenerated><uri>apitesturi</uri></coSpace>

ملاحظة: الاستجابة هي تكوين XML مرمز للمساحة.

تلخص الصورة GET للطلب.

HTTP PUT

الخطوة 3. قم بإجراء تغيير على المساحة (إذا لزم الأمر).

يوضح هذا المثال كيفية تعديل المساحة التي تم إنشاؤها. تخيل أن هناك جزء مستخدم ثانوي يحتاج إلى إضافته إلى المساحة.

ارجع إلى مستند واجهة برمجة التطبيقات (API). وهو يخبر المعلمة المطلوبة لاستخدام: secondaryUri.

إضافة URI من ASDF. اكتب طلبا يبدو مماثلا للطلب الذي تم إنشاؤه ل POST.

مثال على طلب PUT:

PUT https://172.18.105.244/api/v1/coSpaces/70ca0ed7-4e50-428c-b9ab-4e68faeb86ae HTTP/1.1

Host: 172.18.105.244

User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Accept-Language: en-US,en;q=0.5

Accept-Encoding: gzip, deflate, br

Content-Type: application/x-www-form-urlencoded

Content-Length: 17

Cookie: session=b810c447daaeab6cdc6e019c

Authorization: Basic YWRtaW46QzFzYzBDMXNjMA==

Connection: keep-alive

secondaryUri=asdf

إستجابة لطلب PUT:

HTTP/1.1 200 OK

Date: Tue, 12 Apr 2016 19:11:02 GMT

Server: Apache

X-Frame-Options: DENY

Strict-Transport-Security: max-age=31536000; includeSubDomains

Vary: Accept-Encoding

Keep-Alive: timeout=5, max=100

Connection: Keep-Alive

Content-Length: 0

يمكن رؤية التغييرات في WebAdmin ل CMS. انتقل إلى التكوين > المسافات.

ومن خلال GET:

<?xml version="1.0"?><coSpace id="70ca0ed7-4e50-428c-b9ab-4e68faeb86ae"><name>APITest</name><autoGenerated>false</autoGenerated><uri>apitesturi</uri><secondaryUri>asdf</secondaryUri></coSpace>

تلخص الصورة وضع الطلب.

حذف HTTP

الخطوة 4. احذف المساحة (إذا لزم الأمر).

أسلوب الحذف مماثل لأسلوب GET.

مثال على طلب الحذف:

DELETE https://172.18.105.244/api/v1/coSpaces/70ca0ed7-4e50-428c-b9ab-4e68faeb86ae HTTP/1.1

Host: 172.18.105.244

User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Accept-Language: en-US,en;q=0.5

Accept-Encoding: gzip, deflate, br

Cookie: session=4d13c7ebe739b662dc6e019c

Authorization: Basic YWRtaW46QzFzYzBDMXNjMA==

Connection: keep-alive

إستجابة ل DELETErequest:

HTTP/1.1 200 OK

Date: Tue, 12 Apr 2016 19:16:37 GMT

Server: Apache

X-Frame-Options: DENY

Strict-Transport-Security: max-age=31536000; includeSubDomains

Vary: Accept-Encoding

Keep-Alive: timeout=5, max=100

Connection: Keep-Alive

Content-Length: 0

يمكن رؤية التغييرات في WebAdmin ل CMS. انتقل إلى التكوين > المسافات.

ومن خلال GET:

<?xml version="1.0"?><failureDetails><coSpaceDoesNotExist /></failureDetails>

تلخص الصورة حذف الطلب.

عملاء واجهة برمجة التطبيقات

ملصق

المربع الأعلى في المشهد الرئيسي هو المكان الذي تقوم فيه بإدخال عنوان الربط الخاص بالطلبات.

حقول مصادقة المستخدم هي حيث تقوم بإدخال اسم المستخدم وكلمة المرور في هذا الترتيب. ثم، إذا كنت تقوم ب GET أو حذف، أختر الأزرار المقابلة. على سبيل المثال: انقر على GET وتظهر قائمة منبثقة مع إستجابتك. بالنسبة إلى DELETE، تأكد من تحديد DELETE وانقر فوق الزر الأخضر.

بالنسبة ل POST وPUT، يلزم إضافة المحتوى. حدد علامة التبويب معلمات وقم بإضافة الأسماء والقيم للمعلمات الخاصة بك. ثم، ارجع إلى زر "المحتوى المراد إرساله" واختر النص الرئيسي من المعلمات.

إرسال مادة النشر و/أو وضع.

ساعي البريد

في Postman، في أعلى اليسار، أختر الطريقة التي تريد إستخدامها من المربع المنسدل وأدخل عنوان URL الخاص بالطلب.

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

إذا كان طلبك هو POST/PUT، انتقل إلى علامة التبويب "النص"، واختر x-www-form-urlencoded، وأدخل المعلمات والقيم الخاصة بك. عند انتهائك، أختر إرسال.

التحقق من الصحة

يتم شرح أسلوب التحقق في كل طلب.

استكشاف الأخطاء وإصلاحها

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