解析器的 Azure SQL 資料來源

2025-06-19

適用於：開發人員 |基本 |基本 v2 |標準 |標準 v2 |Premium |進階 v2

sql-data-source 解析器原則會設定對 Azure SQL 資料庫的 Transact-SQL (T-SQL) 要求和選擇性回應，以解析 GraphQL 結構描述中物件類型和欄位的資料。您必須將這個結構描述匯入 API 管理作為 GraphQL API。

注意

此原則處於預覽狀態。目前，API 管理的取用層不支援此原則。

注意

請依照原則陳述式中提供的順序，來設定原則的元素和子元素。深入了解如何設定或編輯 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>

元素

名稱	描述	必要
connection-info	指定與 Azure SQL 資料庫的連線。	是的
include-fragment	在原則定義中插入原則片段。如果有多個片段，請新增其他 `include-fragment` 元素。	否
請求	指定解析器的 T-SQL 要求和選擇性參數。	是的
回應	選擇性指定子原則以設定 Azure SQL 資料庫的回應。如果未指定，則會以 JSON 的形式從 Azure SQL 傳回回應。	否

connection-info 元素

注意

除非有註明，否則每個子項目最多只能指定一次。依序指定元素。

元素	描述	必要
connection-string	指定 Azure SQL 連接字串。如果已設定 API 管理受控識別，連接字串會使用 SQL 驗證 (使用者名稱和密碼) 或 Microsoft Entra 驗證。	是的
include-fragment	在原則定義中插入原則片段。如果有多個片段，請新增其他 `include-fragment` 元素。	否
authentication-certificate	使用解析器 SQL 要求中的用戶端憑證進行驗證。	否

connection-string 屬性

屬性	描述	必要	預設
use-managed-identity	布林值。指定是否使用 API 管理執行個體的系統指派的受控識別來連接到 Azure SQL 資料庫，而不是連接字串中的使用者名稱和密碼。允許使用原則運算式。必須設定身分識別才能存取 Azure SQL 資料庫。 Microsoft建議此選項為最安全的驗證方法。	否	`false`

要求屬性

屬性	描述	必要	預設
單一結果	布林值。指定查詢的回應是否應該最多傳回一行資料列。允許使用原則運算式。	否	`false`

要求元素

注意

每個子項目最多可以指定一次。依序指定元素。

元素	描述	必要
include-fragment	在原則定義中插入原則片段。	否
set-body	設定解析器的 SQL 要求中的本文。	否
sql-statement	Azure SQL 資料庫要求的 T-SQL 陳述式。 SQL 陳述式可能包含多個獨立子陳述式，例如 UPDATE、DELETE 和 SELECT，這些子陳述式會依序執行。結果會從最終子陳述式傳回。	是的
參數	適用於要求的 SQL 參數清單 (於 `parameter` 子元素中)。	否

參數屬性

屬性	描述	必要	預設
NAME	字串。 SQL 參數的名稱。	是的	N/A
sql-type	字串。 SQL 參數的資料類型。	否	N/A

response 元素

注意

每個子項目最多可以指定一次。依序指定元素。

名稱	描述	必要
include-fragment	在原則定義中插入原則片段。	否
set-body	設定解析器回應中的本文。	否
publish-event	將事件發佈到 GraphQL API 結構描述中指定的一或多個訂用帳戶。	否

使用方式

原則範圍：GraphQL 解析器
閘道： 傳統、v2

使用量注意事項

若要使用這個原則設定及管理解析器，請參閱設定 GraphQL 解析器。
只有在結構描述的相符作業類型中解析單一欄位時，才會叫用此原則。

設定受控識別與 Azure SQL 的整合

強烈建議您設定 API 管理系統指派的受控識別來存取 Azure SQL，而不是使用使用者名稱和密碼設定 SQL 驗證。如需背景，請參閱使用 Azure SQL 設定及管理 Microsoft Entra 驗證。

必要條件

在 API 管理執行個體中啟用系統指派的受控識別。

啟用 Microsoft Entra ID 存取

透過將 Microsoft Entra 使用者指派為伺服器管理員，啟用對 SQL 資料庫的 Microsoft Entra 驗證。

在入口網站中，移至 Azure SQL 伺服器。
選取 [Microsoft Entra ID]。
選取 [設定系統管理員]，然後選取您自己或您所屬的群組。
選取 [儲存]。

指派角色

在入口網站中，移至您的 Azure SQL 資料庫資源。
選取 [查詢編輯器 (預覽)]。
使用 Microsoft Entra 驗證登入。

執行下列 SQL 指令碼。將 <identity-name> 取代為 API 管理執行個體的名稱。

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
}

使用單一結果 T-SQL 要求的 GraphQL 查詢解析器

下列範例會藉由對後端 Azure SQL 資料庫提出單一結果 T-SQL 要求來解析 GraphQL 查詢。連接字串會使用具有使用者名稱和密碼的 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 查詢解析器

下列範例會使用 Azure SQL 資料庫的 T-SQL 查詢來解析 GraphQL 查詢。資料庫的連線會使用 API 管理執行個體的系統指派的受控識別。必須設定身分識別才能存取 Azure SQL 資料庫。

查詢參數是使用 context.GraphQL.Arguments 內容變數來存取。多資料列查詢回應會使用具有 Liquid 範本的 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 變動的解析器

下列範例會使用 T-SQL INSERT 陳述式，在 Azure SQL 資料庫中插入一行資料列來解決 GraphQL 變動。資料庫的連線會使用 API 管理執行個體的系統指派的受控識別。必須設定身分識別才能存取 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 解析器

如需使用原則的詳細資訊，請參閱：

共用方式為