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

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

# استيراد مكتبة كود بايثون
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))

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

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

import os

import urllib.request

import ssl

import json

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

cato_api_key = os.getenv("CATO_API_KEY")

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

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

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

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

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

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

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

بعد ذلك يتم إنشاء قاموس يحدد رأسين 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()

تحول السطران التاليان من الكود القاموس بايثون الذي يحتوي على استدعاء واجهة برمجة التطبيقات الخاصة بـ 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 حقل بدي يحتوي على مستند 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