شرح برنامج بايثون الخاص بـ Cato API

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

# تحميل مكتبة بايثون
import os
import urllib.request
import ssl
import json

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

# إنشاء الطلب الرسومي الذي سيتم إرساله
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)

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

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

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

import os

import urllib.request

import ssl

import json

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

cato_api_key = os.getenv("CATO_API_KEY")

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

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

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

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

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

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

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

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

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

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

unverified_ctx = ssl._create_unverified_context()

تحول السطران التاليان من الكود القاموس البايثوني المحتوي على اتصال Cato API إلى سلسلة وتشفير تلك السلسلة إلى بايت.  الخطوة الثانية مطلوبة للسماح بنقل السلسلة عبر الشبكة.

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

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

طلب = 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 الخاصة به والتي تُعيد كائن بايتات.  يتم تحويل كائن البايت هذا إلى كائن سلسلة عن طريق استدعاء الطريقة decode الخاصة بكائن البايت.

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

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

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

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

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

get_total_admin_result = json.loads(json_response)

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

total = get_total_admins_result['data']['get_total_admins']['total']
print('إجمالي عدد المسؤولين المحددين لحسابك هو: {}'.format(total)) 

سيظهر الإخراج بهذا الشكل:

إجمالي عدد المسؤولين المحددين لحسابك هو: 4