تكوين محلل GraphQL

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

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

حاليا، تدعم APIM أدوات الحل التي يمكنها الوصول إلى مصادر البيانات التالية:

• مصدر البيانات المستند إلى HTTP (REST أو SOAP API)
• قاعدة بيانات Cosmos DB
• قاعدة بيانات Azure SQL

الأشياء التي يجب معرفتها

• الحل هو مورد يحتوي على تعريف نهج يتم استدعاؤه فقط عند تنفيذ نوع عنصر مطابق وحقل في المخطط.
• يحل كل محلل البيانات لحقل واحد. لحل البيانات لحقول متعددة، قم بتكوين محلل منفصل لكل منها.
• يتم تقييم النهج ذات نطاق الحل بعد أي inbound نهج و backend في مسار تنفيذ النهج. لا يرثون النهج من نطاقات أخرى. لمزيد من المعلومات، راجع النهج في APIM.
• يمكنك تكوين نهج نطاق واجهة برمجة التطبيقات لواجهة برمجة تطبيقات GraphQL، بغض النظر عن النهج ذات النطاق المحدد للمحلل. على سبيل المثال، أضف نهج validate-graphql-request إلى inbound النطاق للتحقق من صحة الطلب قبل استدعاء محلل. تكوين نهج نطاق واجهة برمجة التطبيقات في علامة التبويب نهج واجهة برمجة التطبيقات لواجهة برمجة التطبيقات.
• لدعم أنواع الواجهة والاتحاد في محللات GraphQL، يجب أن تحتوي استجابة الواجهة الخلفية إما على __typename الحقل بالفعل، أو أن يتم تغييرها باستخدام نهج مجموعة النص الأساسي لتضمين __typename.

المتطلبات الأساسية

• مثيل APIM موجود. أنشئ واحد إذا لم تكن قد قمت بذلك بالفعل.
• استيراد واجهة برمجة تطبيقات GraphQL تمريرية أو اصطناعية.

إنشاء محلل

تنشئ الخطوات التالية محلل باستخدام مصدر بيانات يستند إلى HTTP. الخطوات العامة مشابهة لأي محلل يستخدم مصدر بيانات معتمدا.

1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.

2. في القائمة اليسرى، حدد واجهات برمجة التطبيقات ثم اسم واجهة برمجة تطبيقات GraphQL.

3. في علامة التبويب مخطط ، راجع المخطط لحقل في نوع كائن حيث تريد تكوين محلل.

   1. حدد حقلا، ثم في الهامش الأيسر، مرر المؤشر.

   2. حدد + إضافة محلل.

      

4. في صفحة إنشاء محلل :

   1. قم بتحديث خاصية الاسم إذا كنت تريد ذلك، وأدخل وصفا اختياريا، وتأكد من تحديدات النوع وحقل أو حدثهما.
   2. حدد مصدر بيانات محلل البيانات. في هذا المثال، حدد HTTP API.

5. في محرر نهج الحل، قم بتحديث النهج http-data-source بعناصر تابعة للسيناريو الخاص بك.

   1. تحديث العنصر المطلوب http-request مع نهج لتحويل عملية GraphQL إلى طلب HTTP.

   2. أضف عنصرا http-response اختياريا، وأضف نهج تابعة لتحويل استجابة HTTP للمحلل. http-response إذا لم يتم تحديد العنصر، يتم إرجاع الاستجابة كسلسلة أولية.

   3. حدد إنشاء.

      

   يتم إرفاق محلل بالحقل ويظهر في علامة التبويب محللات .

   

إدارة أدوات الحل

سرد أدوات الحل لواجهة برمجة تطبيقات GraphQL وإدارتها في علامة التبويب محللات واجهة برمجة التطبيقات.

في علامة التبويب Resolvers :

• يشير العمود المرتبط إلى ما إذا كان قد تم تكوين محلل لحقل موجود حاليا في مخطط GraphQL. إذا لم يكن محلل مرتبطا، فلا يمكن استدعاؤه.

• في قائمة السياق (...) لمحلل، ابحث عن أوامر لنسخ محلل أو تحريره أو حذفه. استنساخ محلل مدرج لإنشاء محلل مشابه بسرعة يستهدف نوعا وحقل مختلفين.

• يمكنك إنشاء محلل جديد عن طريق تحديد + Create.

تحرير محلل واختباره

عند تحرير محلل واحد، يتم فتح صفحة تحرير محلل . يمكنك:

• تحديث نهج الحل ومصدر البيانات اختياريا. يؤدي تغيير مصدر البيانات إلى الكتابة فوق نهج الحل الحالي.

• تغيير النوع للحقل الذي يستهدفه محلل.

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

  

سياق GraphQL

• يختلف سياق طلب الحل واستجابته (إذا تم تحديده) عن سياق طلب واجهة برمجة تطبيقات البوابة الأصلية:
  • context.GraphQL يتم تعيين الخصائص إلى الوسيطات (Arguments) والكائن الأصل (Parent) لتنفيذ الحل الحالي.
  • يحتوي سياق الطلب على وسيطات يتم تمريرها في استعلام GraphQL كنصه الأساسي.
  • سياق الاستجابة هو الاستجابة من الاستدعاء المستقل الذي أجراه الحل، وليس سياق الاستجابة الكاملة لطلب البوابة. context يتم زيادة المتغير الذي يتم تمريره عبر مسار الطلب والاستجابة مع سياق GraphQL عند استخدامه مع محلل GraphQL.

سياق. GraphQL.parent

يتم تعيين context.GraphQL.parent إلى العنصر الأصل لتنفيذ المحلل الحالي. ضع في اعتبارك المخطط الجزئي التالي:

type Comment {
    id: ID!
    owner: string!
    content: string!
}

type Blog {
    id: ID!
    title: string!
    content: string!
    comments: [Comment]!
    comment(id: ID!): Comment
}

type Query {
    getBlog(): [Blog]!
    getBlog(id: ID!): Blog
}

أيضاً، ضع في اعتبارك استعلام GraphQL لجميع المعلومات لمدونة معينة:

query {
    getBlog(id: 1) {
        title
        content
        comments {
            id
            owner
            content
        }
    }
}

إذا قمت بتعيين محلل للحقل comments في Blog النوع، فسترغب في فهم معرف المدونة الذي يجب استخدامه. يمكنك الحصول على معرف المدونة باستخدام context.GraphQL.Parent["id"] كما هو موضح في الحلل التالي:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/blog/{context.GraphQL.Parent["id"]}")
        </set-url>
    </http-request>
</http-data-source>

سياق. GraphQL.Arguments

تتم إضافة وسيطات استعلام GraphQL ذات معلمات إلى context.GraphQL.Arguments. على سبيل المثال، ضع في اعتبارك الاستعلامين التاليين:

query($id: Int) {
    getComment(id: $id) {
        content
    }
}

query {
    getComment(id: 2) {
        content
    }
}

هذان الاستعلامان هما طريقتان لاستدعاء المحلل getComment. يرسل GraphQL حمولة JSON التالية:

{
    "query": "query($id: Int) { getComment(id: $id) { content } }",
    "variables": { "id": 2 }
}

{
    "query": "query { getComment(id: 2) { content } }"
}

يمكنك تعريف المحلل كما يلي:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/comment/{context.GraphQL.Arguments["id"]}")</set-url>
    </http-request>
</http-data-source>

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

لمزيد من الأمثلة على محلل، راجع:

• نهج محلل GraphQL

• نماذج واجهات برمجة التطبيقات لإدارة واجهة برمجة تطبيقات Azure