شرح سكربت بايثون لواجهة برمجة التطبيقات (API) الخاصة بـ Cato

تقدم هذه المقالة واجهة برمجة التطبيقات (API) الخاصة بـ Cato وتحلل تطبيق بايثون نموذجي.

المقدمة

تم تنفيذ واجهة برمجة التطبيقات الخاصة بـ Cato وفقًا لـ مواصفات GraphQL. على الرغم من أن GraphQL مصمم لتقديم واجهات برمجة تطبيقات سهلة الاستخدام، إلا أن تعلم استخدام أي تقنية جديدة لا يزال يتطلب استثمارًا من المطور. الهدف من هذا المستند هو تقليل مستوى هذا الاستثمار والتجول في تطبيق بايثون صغير ينفذ استدعاء واجهة برمجة التطبيقات adminsالخاصة بـ Cato ويعيد ببساطة عدد المدراء الذين تم تعريفهم لحساب. أثناء القيام بذلك، يتم تقديم العناصر الأكثر أهمية في تطبيق واجهة برمجة التطبيقات Cato GraphQL للقارئ.

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

توضيح لتطبيق واجهة برمجة التطبيقات Cato أساسي

التطبيق المقدم هنا مكتوب بلغة بايثون ويستخدم استدعاء واجهة برمجة التطبيقات adminsالخاصة بـ Cato لاسترجاع العدد الإجمالي للمدراء المعرّفين لحساب. تم اختيار لغة بايثون واستدعاء واجهة برمجة التطبيقات adminsالخاصة بـ Cato لأن:

بايثون هي لغة شائعة للغاية وسهلة القراءة والفهم
يمكن استخدام استدعاء واجهة برمجة التطبيقات adminsلإنشاء مثال بسيط جدًا لاستدعاء واجهة Cato GraphQL API.

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

تنويه:
ملاحظة: لا ترتبط واجهة برمجة التطبيقات API الخاصة بـ Cato بأي لغة برمجة محددة. من الممكن تنفيذ تطبيق باستخدام أي لغة يمكنها استخدام وظيفة HTTP POST ومعالجة مستندات JSON.

نظرة عامة على البرنامج النموذجي

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

# استيراد مكتبة كود بايثون
import os
import urllib.request
import ssl
import json

# الحصول على مفتاح واجهة برمجة التطبيقات (API) الخاص بـ Cato من متغير بيئة
cato_api_key = os.getenv("CATO_API_KEY")

# إنشاء طلب GraphQL ليتم إرساله
get_total_admins = '''{
    admins (accountID: 12345) {
        total        
    }
}'''
graphql_query = {'query': get_total_admins}

# بناء طلب http
cato_api_url = "https://api.catonetworks.com/api/v1/graphql2"
headers = {'x-api-key': cato_api_key,
           'Content-Type':'application/json'}
unverified_ctx = ssl._create_unverified_context()
json_post = json.dumps(graphql_query)
json_post_encoded = json_post.encode()
request = urllib.request.Request(url=cato_api_url, data=json_post_encoded, headers=headers)

# إرسال الاستعلام وتحويل الاستجابة إلى قاموس بايثون
response = urllib.request.urlopen(request, context=unverified_ctx, timeout=30)
json_response_encoded = response.read()
json_response = json_response_encoded.decode()
get_admins_total_result = json.loads(json_response)

# استخراج العدد الإجمالي من البيانات المعادة وطباعته
 total = get_admins_total_result['data']['admins']['total']
print('العدد الإجمالي للمدراء المعرفين في حسابك هو: {}'.format(total))

مهم!
تم تزويد هذا البرنامج كعرض توضيحي لكيفية الوصول إلى واجهة برمجة التطبيقات API الخاصة بـ Cato باستخدام بايثون. ليست إصدارًا رسميًا من Cato وتم توفيره بدون أي ضمانات للدعم. يقتصر التعامل مع الأخطاء على الحد الأدنى المطلوب لعمل السكربت مع واجهة برمجة التطبيقات، وقد لا يكون كافياً لبيئة الإنتاج.

يجب إرسال جميع الأسئلة أو الملاحظات إلى api@catonetworks.com

يُظهر الرسم البياني المقدم أدناه تسلسل الأحداث التي تحدث عند تشغيل البرنامج:

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

استيراد كود مكتبة بايثون

أحد الأسباب لاستخدام بايثون في البرنامج النموذجي هو توفر مجموعة غنية من المكتبات. توفر هذه المكتبات وظائف وكائنات يمكنها التعامل مع مجموعة واسعة من المهام. سنقوم الآن بمراجعة كل مكتبة مستوردة وتقديم ملاحظات لشرح سبب الحاجة إليها.

import os

يوفر مكتبة os وظيفة تسمح للكود بالوصول إلى البيانات الموجودة في متغيرات بيئة نظام التشغيل.
```
import urllib.request
```
يعرّف وحدة request من مكتبة urllib فئة Request التي تنشئ كائنات يمكنها معالجة الاتصال بالخوادم البعيدة التي يتم الوصول إليها عبر عنوان URL.
سيجعل هذا من الممكن إرسال طلب واجهة برمجة التطبيقات الخاصة بـ Cato إلى خادم Cato API GraphQL.
```
import ssl
```
مكتبة ssl مطلوبة لإنشاء سياق غير موثوق به للطلبات المرسلة إلى خادم Cato API GraphQL.
```
import json
```
تحتوي هذه المكتبة على وظائف ستجعل من الممكن تحويل قاموس بايثون إلى سلسلة JSON وبالعكس.
تُسهّل هذه القدرة على التحويل بين التنسيقين المختلفين كتابة الأكواد التي يمكنها العمل مع مستندات JSON.

الحصول على مفتاح واجهة برمجة التطبيقات الخاصة بـ Cato

يستخدم هذا السطر من الكود دالة مكتبة getenv لقراءة مفتاح واجهة برمجة التطبيقات من متغير بيئة وتعيينها إلى متغير.

cato_api_key = os.getenv("CATO_API_KEY")

يتوقع خادم Cato API GraphQL استلام هذا المفتاح في رأس HTTP. لا يتم توفير المفتاح في مستند JSON لأن مواصفات GraphQL لا تتضمن التفويض كجزء من المعيار. تضمين التفويض في مستند JSON سيكون انتهاكًا للمواصفات. يتم إنشاء مفتاح واجهة برمجة التطبيقات API الخاصة بـ Cato من خلال تطبيق إدارة Cato. لمزيد من المعلومات حول إنشاء مفتاح API، انظر إنشاء مفاتيح API لواجهة برمجة التطبيقات الخاصة بـ Cato.

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

إنشاء طلب GraphQL لإرساله

تقوم أسطر الكود التالية بإنشاء دليل Python يحتوي على زوج مفتاح/قيمة واحد. يتم بناء قيمة الإدخال باستخدام سلسلة بايثون متعددة الأسطر تحدد الاستعلام الذي سيتم إرساله إلى الخادم GraphQL.

get_total_admins = '''{
    admins (accountID: 12345) {
        total    
    }
}'''
graphql_query = {'query': get_total_admins}

سيقوم خادم Cato GraphQL بتفسير هذه السلسلة على أنها: تنفيذ الدالة get_total_admins، وتمرير وسيطين إليها (accountID وtype) وإرجاع فقط عدد العناصر الإجمالي. أو بشكل أكثر مباشرة، "إرجاع العدد الإجمالي للعناصر من المدراء المعرّفين لحساب مثال رقم 12345". يوضح هذا المثال المحدد لاستدعاء واجهة برمجة التطبيقات adminsالخاصة بـ Cato مزايا مهمة لواجهة برمجة التطبيقات GraphQL.

يعيد الخادم فقط البيانات التي طلبها التطبيق.

والحقيقة هي، أن استدعاء واجهة برمجة التطبيقات adminsيمكن أن يعيد الكثير من البيانات. على سبيل المثال، من الممكن لتطبيق أن يطلب أن يعيد adminsتفاصيل حول كل إدارة. ومع ذلك، فإن هذا التطبيق يحتاج فقط إلى معرفة العدد الإجمالي للمدراء. هذا الطابع الخاص بـ GraphQL يتجنب ما يسمى بالتحميل الزائد ويمكن أن يبسط بشكل كبير الأكواد اللازمة لتنفيذ التطبيق.

بناء طلب HTTP

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

cato_api_url = "https://api.catonetworks.com/api/v1/graphql2"

ملحوظة:
ملاحظة: تستخدم واجهة برمجة التطبيقات GraphQL عنوان URL واحد لجميع استدعاءات API. يتم توفير تفاصيل الاستدعاء، مثل الوسيطات، في مستند JSON. وهذا على النقيض من REST API التي ستستخدم عنوان URL مختلف لكل استدعاء API وتمرير الوسيطات إلى الاستدعاء بإضافتها إلى عنوان URL. يُعتبر استخدام عنوان URL واحد غير مشوش بالوسيطة هو ميزة أخرى لـ GraphQL API.

بعد ذلك يتم إنشاء قاموس يحدد رأسين HTTP. تُستخدم هذه الرؤوس من قبل كائن الطلب لبناء طلب POST HTTP الذي سيقبله خادم GraphQL. بدون هذه الرؤوس سيتم رفض طلبات POST HTTP من قبل الخادم.

headers = {'x-api-key': cato_api_key,           
           'Content-Type':'application/json'}

يُنشئ السطر التالي من الكود كائن سياق SSL. يستخدم بايثون هذا الكائن لتحديد كيفية تشفير طلبات HTTP و إرسالها باستخدام أمان طبقة النقل (TLS). هنا نقوم بإنشاء كائن سياق SSL لا يتحقق من الشهادات. تم ذلك لتجنب أخطاء الشهادات في الشبكات الخاضعة للتفتيش TLS الأعلى.

unverified_ctx = ssl._create_unverified_context()

مهم!
استخدام كائن سياق SSL غير موثوق به يعني أنه لن يتم إجراء أي تحقق للتأكد من صحة الشهادات. توصي Cato Networks بعدم استخدام مثل هذا النهج في الإنتاج. تفاصيل كيفية تعزيز الأمان تتجاوز نطاق هذا المستند.

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

json_post = json.dumps(graphql_query)
json_post_encoded = json_post.encode()

وأخيرا يتم إنشاء كائن الطلب والبرنامج جاهز الآن لإرسال استدعاء get_total_admins إلى الخادم.

request = urllib.request.Request(url=cato_api_url, data=json_post_encoded, headers=headers)

إرسال الاستعلام ومعالجة الاستجابة

هنا يرسل البرنامج الطلب إلى الخادم GraphQL عن طريق استدعاء دالة urlopen من مكتبة urllib. استدعاء هذه الوظيفة سيؤدي إلى العودة بكائن HTTPResponse.

response = urllib.request.urlopen(request, context=unverified_ctx, timeout=30)

تحذير!
يمكن أن يؤدي استدعاء دالة urlopenإلى توليد خطأ. على سبيل المثال، يمكن أن يرفض الخادم GraphQL الطلب بسبب خطأ في بناء الجملة أو قد تؤدي مشاكل في الشبكة إلى انتهاء الوقت المحدد (أي لا يوجد استجابة بعد 30 ثانية). لم يتم معالجة هذه الأخطاء هنا.

يتضمن الكائن المُعاد بواسطة الدالة urlopen حقل بدي يحتوي على مستند JSON المُعاد من الخادم. يمكن استخراج ذلك من الكائن بتنفيذ دالة readله والتي تعيد كائن البايتات. بعد ذلك يتم تحويل كائن البايتات إلى كائن سلسلة من خلال استدعاء دالة فك الترميز لكائن البايتات.

json_response_encoded = response.read()
json_response = json_response_encoded.decode()

تحتوي هذه السلسلة المفككة على مستند JSON سيبدو كالآتي:

{    
    "data" : {
         "admins" : {
              "total": 4
         }
    }
}

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

يستخدم السطر الأخير من التعليمات البرمجية في هذا القسم من البرنامج دالة المكتبة json 'loads' لتحويل سلسلة JSON المُرجعة إلى قاموس متداخل في بايثون.

get_total_admin_result = json.loads(json_response)

استخراج الإجمالي من البيانات المُرجعة وطباعتها

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

total = get_total_admins_result['data']['get_total_admins']['total']
print('The total number of admins defined for your account is: {}'.format(total))

سيبدو الناتج كالتالي:

The total number of admins defined for your account is: 4

الملخص

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

إنشاء استدعاء Cato API وإضافته إلى مستند JSON
الحصول على مفتاح Cato API
إنشاء رؤوس HTTP تحتوي على مفتاح Cato API وتحدد تنسيق البيانات (JSON) للبيانات المُرسلة

إرسال مستند JSON (مرمز بالبايتات) إلى خادم Cato GraphQl API باستخدام أمر HTTP POST مُشفر بتقنية TLS
تحويل كائن الاستجابة الذي أرجعه الخادم إلى مستند JSON
تحويل مستند JSON إلى تنسيق يمكن استخدامه بواسطة البرنامج