نظرة عامة على واجهات برمجة تطبيقات GraphQL في Azure API Management

ينطبق على: جميع مستويات إدارة واجهة برمجة التطبيقات

يمكنك استخدام APIM لإدارة واجهات برمجة تطبيقات GraphQL - واجهات برمجة التطبيقات استنادا إلى لغة استعلام GraphQL. يوفر GraphQL وصفا كاملا ومفهوما للبيانات في واجهة برمجة التطبيقات، ما يمنح العملاء القدرة على استرداد البيانات التي يحتاجون إليها بكفاءة. تعرف على المزيد حول GraphQL

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

Pass-through GraphQL	GraphQL صناعية
▪️ واجهة برمجة التطبيقات التمريرية إلى نقطة نهاية خدمة GraphQL الموجودة ▪️ دعم استعلامات GraphQL والطفرات والاشتراكات	▪️ واجهة برمجة التطبيقات استنادا إلى مخطط GraphQL مخصص ▪️ دعم استعلامات GraphQL والطفرات والاشتراكات ▪️ تكوين أدوات الحل المخصصة، على سبيل المثال، إلى مصادر بيانات HTTP ▪️ تطوير مخططات GraphQL والعملاء المستندين إلى GraphQL أثناء استهلاك البيانات من واجهات برمجة التطبيقات القديمة

التوافر

• يتم دعم واجهات برمجة تطبيقات GraphQL في جميع مستويات خدمة APIM
• واجهات برمجة تطبيقات GraphQL الاصطناعية غير مدعومة حاليا في مساحات عمل APIM
• دعم اشتراكات GraphQL في واجهات برمجة تطبيقات GraphQL الاصطناعية قيد المعاينة حاليا ولا يتوفر في مستوى الاستهلاك

ما هو GraphQL؟

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

تحل مواصفات GraphQL بشكل صريح المشكلات الشائعة التي تواجهها تطبيقات الويب للعميل التي تعتمد على واجهات برمجة تطبيقات REST:

• قد يستغرق الأمر عددا كبيرا من الطلبات لتلبية احتياجات البيانات لصفحة واحدة
• غالبا ما تقوم واجهات برمجة تطبيقات REST بإرجاع بيانات أكثر مما تحتاج إليه الصفحة التي يتم عرضها
• يحتاج تطبيق العميل إلى الاستقصاء للحصول على معلومات جديدة

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

المخطط والأنواع

في API Management، أضف واجهة برمجة تطبيقات GraphQL من مخطط GraphQL، إما استردادها من نقطة نهاية واجهة برمجة تطبيقات GraphQL الخلفية أو تحميلها من قبلك. يصف مخطط GraphQL ما يلي:

• أنواع كائنات البيانات والحقول التي يمكن للعملاء طلبها من واجهة برمجة تطبيقات GraphQL
• أنواع العمليات المسموح بها على البيانات، مثل الاستعلامات
• أنواع أخرى، مثل الاتحادات والواجهات، التي توفر مرونة إضافية والتحكم في البيانات

على سبيل المثال، قد يبدو مخطط GraphQL الأساسي لبيانات المستخدم والاستعلام لجميع المستخدمين كما يلي:

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

أنواع العمليات

تدعم APIM أنواع العمليات التالية في مخططات GraphQL. لمزيد من المعلومات حول أنواع العمليات هذه، راجع مواصفات GraphQL.

• الاستعلام - إحضار البيانات، على GET غرار عملية في REST

• الطفرة - تعديل البيانات من جانب الخادم، على غرار عملية PUT أو PATCH في REST

• الاشتراك - تمكين إعلام العملاء المشتركين في الوقت الفعلي بالتغييرات على البيانات على خدمة GraphQL

  على سبيل المثال، عند تعديل البيانات عبر طفرة GraphQL، يمكن إعلام العملاء المشتركين تلقائيا بالتغيير.

  هام

  تدعم APIM الاشتراكات التي يتم تنفيذها باستخدام بروتوكول graphql-ws WebSocket. الاستعلامات والطفرات غير مدعومة عبر WebSocket.

أنواع أخرى

تدعم APIM أنواع الاتحاد والواجهة في مخططات GraphQL.

أدوات الحل

تهتم أدوات الحل بتعيين مخطط GraphQL إلى بيانات الواجهة الخلفية، وإنتاج البيانات لكل حقل في نوع عنصر. قد يكون مصدر البيانات واجهة برمجة تطبيقات أو قاعدة بيانات أو خدمة أخرى. على سبيل المثال، ستكون دالة محلل مسؤولة عن إرجاع البيانات للاستعلام users في المثال السابق.

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

تدعم APIM حاليا أدوات الحل استنادا إلى مصادر بيانات HTTP API وCosmos DB وAzure SQL لإرجاع البيانات للحاويات في مخطط GraphQL. يتم تكوين كل محلل باستخدام نهج مخصص للاتصال بمصدر البيانات واسترداد البيانات:

Data source	نهج محلل
مصدر البيانات المستند إلى HTTP (REST أو SOAP API)	مصدر بيانات http
قاعدة بيانات COSMOS DB	مصدر بيانات cosmosdb
Azure SQL Database	مصدر بيانات sql

على سبيل المثال، قد يتم تعيين محلل يستند إلى واجهة برمجة تطبيقات HTTP للاستعلام السابق users إلى GET عملية في واجهة برمجة تطبيقات REST الخلفية:

<http-data-source>
	<http-request>
		<set-method>GET</set-method>
		<set-url>https://myapi.contoso.com/api/users</set-url>
	</http-request>
</http-data-source>

لمزيد من المعلومات حول إعداد محلل، راجع تكوين محلل GraphQL.

إدارة واجهات برمجة تطبيقات GraphQL

• تأمين واجهات برمجة تطبيقات GraphQL من خلال تطبيق سياسات التحكم في الوصول الحالية ونهج مصادقة GraphQL للتأمين والحماية من الهجمات الخاصة بـ GraphQL.
• استكشف مخطط GraphQL وقم بتشغيل استعلامات الاختبار مقابل واجهات برمجة تطبيقات GraphQL في مداخل Azure والمطور.

الخطوات التالية

• استيراد واجهة برمجة تطبيقات GraphQL
• استيراد مخطط GraphQL وإعداد محللات الحقول