ما هو Cato API

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

نظرة عامة

Cato API هو واجهة الأتمتة الأساسية للتكامل السلس مع Cato Cloud. استخدم Cato APIs لإعداد تدفقات عمل تشغيلية فعّالة مثل النشر والتكوين، بالإضافة إلى مراقبة الحالة الشاملة، والإحصائيات وجمع البيانات، والتحليلات لتبسيط إدارة الشبكة والأمان لديك.

نقطة نهاية ومخطط Cato API

عنوان URL لنقطة نهاية ومخطط API خاص بالموقع الذي تستضيف فيه مثيل Cato Management Application (CMA). يمكن أن يكون هناك قيمة <prefix> تُضاف إلى عنوان URL لحساب CMA الخاص بك وإلى نقطة النهاية والمخطط الخاص بـ API.

عنوان URL لنقطة نهاية API في الصيغة، https://api.<prefix>.catonetworks.com/api/v1/graphql2.

عنوان URL لمخطط API في الصيغة، https://api.<prefix>.catonetworks.com/api/schema.

عناوين URL لنقطة نهاية API

  • إذا لم يكن هناك بادئة (cc.catonetworks.com)، فاستخدم عنوان URL التالي: https://api.catonetworks.com/api/v1/graphql2

  • إذا كان هناك بادئة (مثل cc.us1.catonetworks.com)، فستستخدم عنوان URL التالي (قم بتعديل البادئة لمواقع مختلفة): https://api.us1.catonetworks.com/api/v1/graphql2

عناوين URL لمخطط API

  • إذا لم يكن هناك بادئة (cc.catonetworks.com)، فاستخدم عنوان URL التالي: https://api.catonetworks.com/api/schema

  • إذا كان هناك بادئة (مثل cc.us1.catonetworks.com)، فستستخدم عنوان URL التالي (قم بتعديل البادئة لمواقع مختلفة): https://api.us1.catonetworks.com/api/schema

توثيق مخطط API

Cato APIs مبنية على GraphQL، مما يوفر واجهة تفاعلية متوافقة تمامًا مع أدوات عملاء RESTful API. كما يوفر GraphQL المرونة اللازمة للاستفسار عن البيانات التي تحتاجها بالضبط، مما يقلل من الجلب الزائد ويحسن الكفاءة.

يتوفر توثيق Cato API في مرجع Cato Networks GraphQL API الذي يحتوي على:

  • تعريف وتوثيق المخطط

  • أمثلة على استدعاءات API والاستجابات النموذجية المقابلة

  • نقطة نهاية GraphQL API مع ساحة لعب تفاعلية لاستكشاف واختبار API

دورة حياة API

يصف هذا القسم مراحل دورة الحياة المختلفة بناءً على مستوى نضوج وتوافر API محدد.

يتم إصدار كل API جديد في البداية في مرحلة Beta. الانتقال من Beta إلى GA يعتمد على المراجعة الداخلية والنظر للتحقق من أن API مستقر وجاهز للإنتاج. عادةً ما يستغرق الانتقال من Beta إلى GA حوالي عام واحد.

تنبيه

ملاحظة: يشير وصف دورة الحياة أدناه فقط إلى API الرسمي Cato كما هو محدد في مرجع Cato Networks GraphQL API. لا يغطي أي أدوات إضافية وأمثلة قد يتم تقديمها كمرجع.

على سبيل المثال، لا يغطي الأمثلة مفتوحة المصدر والأدوات المتاحة في حساب Cato على GitHub. تُقدم هذه الموارد كما هي بدون ضمان أو التزام بالتطوير المستمر أو الصيانة أو الدعم.

مستويات نضج API

إنها مستويات نضج API كجزء من مرحلة دورة الحياة:

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

  • GA (الإصدار العام): APIs في GA مستقرة وجاهزة للإنتاج وتأتي مع دعم طويل الأمد والتزامات بالتوافق العكسي. تغييرات كسر مخطط API نادرة وتُعلن مسبقًا بشكل جيد لتوفير وقت كافٍ لتعديلات كود العميل.

    النقطة الوسطى المتبقية لبيانات الترجمة الاحتفاظ بها بالنمط. في بعض الحالات، داخل واجهة برمجة تطبيقات GA، يمكن وضع علامة على الحقول الفردية والأنواع والمدخلات على أنها بيتا.

مستويات توفر API

هذه هي مستويات توفر APIs كجزء من مرحلة دورة الحياة:

  • EA (التوفر المبكر): APIs في EA متاحة لمجموعة محدودة من المستخدمين للاختبار وتقديم الملاحظات قبل الإصدار الأوسع. قد يتطلب الوصول موافقة خاصة أو شروطاً معينة.

  • التوزيع التدريجي: اتباع أفضل الممارسات الصناعية القياسية للخدمات القائمة على السحابة، يتم توزيع Cato APIs تدريجياً لضمان الاستقرار ومراقبة الأداء، مع توسيع التوفر لجميع الحسابات بمرور الوقت.

    APIs التي لم يتم وضع علامة عليها بأنها EA أو Gradual Rollout تُعتبر منشورة بالكامل ومتاحة لجميع المستخدمين.

ملخص تسميات API

يلخص هذا القسم التسميات المستخدمة لـ APIs في التوثيق بناءً على مستويات النضج والتوفر.

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

  • EA

    • متاح فقط للعملاء الذين ينضمون إلى برنامج EA الخاص بـ Cato، للانضمام، يرجى الاتصال بنا عبر ea@catonetworks.com

  • بيتا

    • قد تكون هناك تغييرات على المخطط

    • إعلان محدود للتغييرات الكاسرة، قد يكون قصيرًا يصل إلى أسبوعين

    • APIs بيتا تدعم الوظائف الكاملة

  • التوزيع

    • هذه APIs من نوع GA يتم توزيعها تدريجياً على جميع الحسابات على مدى بضعة أسابيع

    • قد يؤدي استدعاء API في حالة توزيع إلى رسالة خطأ لأن ذلك API غير متوفر بعد لحسابك

التغييرات المحتملة لكسر المخطط

يناقش هذا القسم عندما تقوم Cato بإجراء تغييرات على مخطط API GraphQL التي يمكن أن تؤثر على السلوك والنتائج لاستدعاءات API.

ما هو التغيير المحتمل لكسر المخطط في GraphQL؟

يحدث تغيير محتمل لكسر المخطط في GraphQL عندما تتطلب تعديلات على API من التطبيقات العميلة تحديث استفساراتهم أو منطقها للحفاظ على الوظائف. تشمل الأمثلة:

  • إزالة حقل، نوع، أو وسيطة.

  • إعادة تسمية الحقول أو الأنواع أو الوسيطات.

  • تعديل القيم الافتراضية للوسيطات بطريقة تغير النتائج المتوقعة للاستفسارات أو التحولات.

  • تغيير نوع أو سلوك الحقل بطريقة تؤثر على التوافق. على سبيل المثال، تغيير نوع الحقل (مثل من Int إلى String) أو تعديل إمكانية التحول للوسيط (مثل من قابل للتحول إلى غير قابل للتحول).

الإعلان عن إدارة التغييرات المحتملة لكسر المخطط

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

قد تحدث هذه التغييرات بشكل متكرر أكثر بالنسبة لـ Beta APIs لكن نادرة بالنسبة لـ GA APIs.

APIs المتقادمة

يحدد API أو حقل معلمة متقادمة أن استخدامها لم يعد موصى به، وتوجد بدائل أفضل. يوصى بتحديث النصوص والعمليات لعدم استخدام APIs والحقل المتقادم لضمان السلوك الوظيفي المتوقع.

الإبلاغ عن APIs نهاية الحياة

إذا كان من المخطط إزالة أو استبدال API أو حقل، فسيتم المرور عبر عملية نهاية الحياة (EoL). تشتمل هذه العملية على الخطوات التالية:

  1. وضع علامة على API أو الحقل كمتقادمة

    1. يتم وضع علامة API أو الحقل المخطط للإزالة كـ متقادمة في مرجع Cato Networks GraphQL API.

    2. يُرفق هذا الوصف برسالة، تشير إلى API أو حقل بديل إذا كان ذلك مطبقًا، وتاريخ EoL المخطط له.

  2. إخطارات نهاية الحياة

    1. يتم تحديث المقالة Cato API التغييرات المحتملة لنهاية الحياة والكسر بتاريخ محدد سيتم فيه تحديث المخطط بهذا التغيير.

    2. الفترة الزمنية بين الإخطار وتغييرات المخطط كالتالي:

      • API GA: على الأقل 3 أشهر مقدماً وعموماً 6 أشهر مقدماً

      • API Beta: عادةً قبل أسبوعين

    3. خلال الفترة الزمنية بين الإخطار بنهاية الحياة وتاريخ نهاية الحياة، من المتوقع أن يقوم العملاء بتحديث كود العميل للتكيف مع تغييرات مخطط GraphQL.

التغييرات غير الكاسرة لمخطط الرسم البياني

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

يتضمن مرجع GraphQL API من Cato Networks دائماً المخطط الكامل المدعوم والمحدث ل GraphQL.

هل كان هذا المقال مفيداً؟

0 من 0 وجدوا هذا مفيداً

لا توجد تعليقات