مصدر بيانات Azure SQL لمحلل

ينطبق على: المطور | أساسي | الإصدار 2 الأساسي | قياسي | الإصدار 2 القياسي | Premium | Premium v2

sql-data-source يقوم نهج الحل بتكوين طلب Transact-SQL (T-SQL) إلى قاعدة بيانات Azure SQL واستجابة اختيارية لحل البيانات لنوع العنصر وحقل في مخطط GraphQL. يجب استيراد المخطط إلى API Management كواجهة برمجة تطبيقات GraphQL.

إشعار

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

إشعار

تعيين عناصر النهج والعناصر التابعة بالترتيب الوارد في بيان النهج. تعلم كيفية إعداد نُهج APIM أو تعديلها.

نهج السياسة

<sql-data-source> 
    <connection-info>
        <connection-string use-managed-identity="true | false">
            Azure SQL connection string
        </connection-string>
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <authentication-certificate>...authentication-certificate policy configuration...</authentication-certificate>     
    </connection-info>
    <include-fragment>...include-fragment policy configuration...</include-fragment>
    <request single-result="true | false">
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <set-body>...set-body policy configuration...</set-body>
        <sql-statement>T-SQL query</sql-statement>
        <parameters>
            <parameter sql-type="parameter type" name="Query parameter name in @ notation">
                "Query parameter value or expression"
            </parameter>
            <!-- if there are multiple parameters, then add additional parameter elements -->
        </parameters>
    </request>
    <response>
        <include-fragment>...include-fragment policy configuration...</include-fragment>
        <set-body>...set-body policy configuration...</set-body>
        <publish-event>...publish-event policy configuration...</publish-event>
    </response>
</sql-data-source> 

عناصر

اسم	‏‏الوصف	مطلوب
معلومات الاتصال	تحديد الاتصال بقاعدة بيانات Azure SQL.	‏‏نعم‬
تضمين-جزء	إدراج جزء نهج في تعريف النهج. إذا كانت هناك أجزاء متعددة، فأضف عناصر إضافية include-fragment .	لا
طلب	تحديد طلب T-SQL الخاص بالمحلل والمعلمات الاختيارية.	‏‏نعم‬
استجابه	يحدد اختياريا النهج التابعة لتكوين الاستجابة من قاعدة بيانات Azure SQL. إذا لم يتم تحديدها، يتم إرجاع الاستجابة من Azure SQL ك JSON.	لا

عناصر معلومات الاتصال

إشعار

باستثناء الحالات التي تمت ملاحظتها، يمكن تحديد كل عنصر تابع مرة واحدة على الأكثر. حدد العناصر بالترتيب المدرج.

العنصر	‏‏الوصف	مطلوب
سلسلة الاتصال	يحدد سلسلة الاتصال Azure SQL. يستخدم سلسلة الاتصال إما مصادقة SQL (اسم المستخدم وكلمة المرور) أو مصادقة Microsoft Entra إذا تم تكوين هوية مدارة لإدارة واجهة برمجة التطبيقات.	‏‏نعم‬
تضمين-جزء	إدراج جزء نهج في تعريف النهج. إذا كانت هناك أجزاء متعددة، فأضف عناصر إضافية include-fragment .	لا
شهادة المصادقة	يصادق باستخدام شهادة عميل في طلب SQL الخاص بالمحلل.	لا

سمات سلسلة الاتصال

السمة	‏‏الوصف	مطلوب	افتراضي
استخدام الهوية المدارة	منطقي. يحدد ما إذا كان يجب استخدام الهوية المدارة المعينة من قبل النظام لمثيل API Management للاتصال بقاعدة بيانات Azure SQL بدلا من اسم مستخدم وكلمة مرور في سلسلة الاتصال. يتم السماح بتعبيرات النهج. يجب تكوين الهوية للوصول إلى قاعدة بيانات Azure SQL. توصي Microsoft بهذا الخيار كطريقة مصادقة أكثر أمانا.	لا	false

سمة الطلب

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

عناصر الطلب

إشعار

يمكن تحديد كل عنصر تابع مرة واحدة على الأكثر. حدد العناصر بالترتيب المدرج.

العنصر	‏‏الوصف	مطلوب
تضمين-جزء	إدراج جزء نهج في تعريف النهج.	لا
تعيين النص الأساسي	تعيين النص الأساسي في طلب SQL الخاص بالمحلل.	لا
عبارة sql	عبارة T-SQL للطلب إلى قاعدة بيانات Azure SQL. قد تتضمن عبارة SQL العديد من العبارات الفرعية المستقلة مثل UPDATE وDELETE و SELECT التي سيتم تنفيذها بالتسلسل. يتم إرجاع النتائج من البيانات الفرعية النهائية.	‏‏نعم‬
البارامترات	قائمة بمعلمات SQL، في parameter العناصر الفرعية، للطلب.	لا

سمات المعلمة

السمة	‏‏الوصف	مطلوب	افتراضي
الاسم	السلسلة. اسم معلمة SQL.	‏‏نعم‬	غير متوفر
نوع sql	السلسلة. نوع بيانات معلمة SQL.	لا	غير متوفر

عناصر الاستجابة

إشعار

يمكن تحديد كل عنصر تابع مرة واحدة على الأكثر. حدد العناصر بالترتيب المدرج.

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

الاستخدام

• نطاقات النهج: محلل GraphQL
• البوابات: الكلاسيكية، الإصدار 2

ملاحظات الاستخدام

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

تكوين تكامل الهوية المدارة مع Azure SQL

نوصي بشدة بتكوين هوية مدارة يعينها نظام إدارة واجهة برمجة التطبيقات للوصول إلى Azure SQL بدلا من تكوين مصادقة SQL باستخدام اسم المستخدم وكلمة المرور. للحصول على الخلفية، راجع تكوين مصادقة Microsoft Entra وإدارتها باستخدام Azure SQL.

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

• تمكين هوية مدارة معينة بواسطة النظام في مثيل API Management.

تمكين الوصول إلى معرف Microsoft Entra

تمكين مصادقة Microsoft Entra إلى قاعدة بيانات SQL عن طريق تعيين مستخدم Microsoft Entra كمسؤول الخادم.

1. في المدخل، انتقل إلى خادم Azure SQL.
2. حدد معرف Microsoft Entra.
3. حدد تعيين المسؤول وحدد نفسك أو مجموعة تنتمي إليها.
4. حدد حفظ.

تعيين الأدوار

1. في المدخل، انتقل إلى مورد قاعدة بيانات Azure SQL.

2. حدد محرر الاستعلام (معاينة).

3. تسجيل الدخول باستخدام مصادقة Microsoft Entra.

4. تنفيذ البرنامج النصي SQL التالي. استبدل <identity-name> باسم مثيل APIM الخاص بك.

   CREATE USER [<identity-name>] FROM EXTERNAL PROVIDER;
   ALTER ROLE db_datareader ADD MEMBER [<identity-name>];
   ALTER ROLE db_datawriter ADD MEMBER [<identity-name>];
   ALTER ROLE db_ddladmin ADD MEMBER [<identity-name>];
   GO
   

الأمثلة

مثال لمخطط بسيط

الأمثلة في هذا القسم هي أدوات الحل لمخطط GraphQL التالي:

type Family {
  id: Int!
  name: String!
}

type Person {
  id: Int!
  name: String!
}

type PersonQueryResult {
  items: [Person]  
}

type Query {
  familyById(familyId: Int!): Family
  familyMembers(familyId: Int!): PersonQueryResult
}

type Mutation {
  createFamily(familyId: Int!, familyName: String!): Family
}

محلل لاستعلام GraphQL باستخدام طلب T-SQL أحادي النتيجة

يحل المثال التالي استعلام GraphQL عن طريق إجراء طلب T-SQL أحادي النتيجة إلى قاعدة بيانات Azure SQL الخلفية. يستخدم سلسلة الاتصال مصادقة SQL مع اسم المستخدم وكلمة المرور ويتم توفيرها باستخدام قيمة مسماة. يتم إرجاع الاستجابة ككائن JSON واحد يمثل صفا واحدا.

<sql-data-source>
    <connection-info>
        <connection-string>
            {{my-connection-string}}
        </connection-string>
    </connection-info>
    <request single-result="true">
        <sql-statement>
            SELECT 
                f.[Id] AS [id]
                f.[Name] AS [name]
            WHERE @familyId = f.[Id] 
        </sql-statement> 
        <parameters> 
            <parameter name="@familyId">       
                @(context.GraphQL.Arguments["id"])
            </parameter> 
        </parameters> 
    </request>
    <response />
</sql-data-source>

محلل لاستعلام GraphQL مع استجابة استعلام متعددة الصفوف المحولة

يحل المثال التالي استعلام GraphQL باستخدام استعلام T-SQL إلى قاعدة بيانات Azure SQL. يستخدم الاتصال بقاعدة البيانات الهوية المدارة المعينة من قبل النظام لمثيل APIM. يجب تكوين الهوية للوصول إلى قاعدة بيانات Azure SQL.

يتم الوصول إلى معلمة الاستعلام باستخدام context.GraphQL.Arguments متغير السياق. يتم تحويل استجابة الاستعلام متعدد الصفوف باستخدام النهج set-body مع قالب سائل.

<sql-data-source> 
    <connection-info>
        <connection-string use-managed-identity="true">
            Server=tcp:{your_server_name}.database.windows.net,1433;Initial Catalog={your_database_name}; 
        </connection-string>
    </connection-info> 
    <request> 
        <sql-statement> 
            SELECT 
                p.[Id] AS [Id] 
                p.[FirstName] AS [FirstName] 
                p.[LastName] AS [LastName] 
            FROM [Person] p 
            JOIN [Family] f ON p.[FamilyId] = f.[Id] 
            WHERE @familyId = f.[Id] 
        </sql-statement> 
        <parameters> 
            <parameter name="@familyId">       
                @(context.GraphQL.Arguments["id"])
            </parameter> 
        </parameters> 
    </request> 
    <response> 
        <set-body template="liquid"> 
            { 
                "items": [ 
                    {% JSONArray For person in body.items %} 
                        "id": "{{ person.id }}" 
                        "name": "{{ person.firstName }} + "" "" + {{body.lastName}}" 
                    {% endJSONArrayFor %} 
                ] 
            } 
        </set-body> 
  </response> 
</sql-data-source>

محلل لتعديل GraphQL

يحل المثال التالي طفرة GraphQL باستخدام عبارة T-SQL INSERT لإدراج صف في قاعدة بيانات Azure SQL. يستخدم الاتصال بقاعدة البيانات الهوية المدارة المعينة من قبل النظام لمثيل APIM. يجب تكوين الهوية للوصول إلى قاعدة بيانات Azure SQL.

<sql-data-source> 
    <connection-info>
        <connection-string use-managed-identity="true">
            Server=tcp:{your_server_name}.database.windows.net,1433;Initial Catalog={your_database_name};</connection-string>
    </connection-info> 
    <request single-result="true"> 
        <sql-statement> 
                INSERT INTO [dbo].[Family]
                       ([Id]
                       ,[Name])
                VALUES
                       (@familyId
                       , @familyName)

                SELECT
                    f.[Id] AS [id],
                    f.[Name] AS [name]
                FROM [Family] f
                WHERE @familyId = f.[Id]
        </sql-statement> 
        <parameters> 
            <parameter name="@familyId">       
                @(context.GraphQL.Arguments["id"])
            </parameter>
            <parameter name="@familyName">       
                @(context.GraphQL.Arguments["name"])
            </parameter> 
        </parameters> 
    </request>    
</sql-data-source>

النهج ذات الصلة

• محللات GraphQL

المحتوى ذو الصلة

لمزيد من المعلومات حول العمل مع النُهج، راجع:

• البرنامج التعليمي: تحويل واجهة برمجة التطبيقات الخاصة بك وحمايتها
• Policy reference لقائمة كاملة من بيانات النُهج وإعداداتها
• تعبيرات النهج
• تعيين النهج أو تحريرها
• إعادة استخدام التكوينات الخاصة بالنهج
• مستودع القصاصات البرمجية للنهج
• مستودع ملعب النهج
• مجموعة أدوات نهج إدارة واجهة برمجة تطبيقات Azure
• الحصول على مساعدة Copilot لإنشاء النهج وشرحها واستكشاف الأخطاء وإصلاحها