解析器的 Azure SQL 資料來源

發行項
03/28/2024

適用於：開發人員 |基本 |基本 v2 |標準 |標準 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 資料庫的連線。	Yes
include-fragment	在原則定義中插入原則片段。如果有多個片段，請新增其他 `include-fragment` 元素。	No
request	指定解析器的 T-SQL 要求和選擇性參數。	Yes
response	選擇性指定子原則以設定 Azure SQL 資料庫的回應。如果未指定，則會以 JSON 的形式從 Azure SQL 傳回回應。	No

connection-info 元素

注意

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

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

connection-string 屬性

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

要求屬性

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

要求元素

注意

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

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

參數屬性

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

response 元素

注意

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

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

使用方式

原則範圍：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 資料庫資源。
選取 [查詢編輯器 (預覽)]。
使用 Active Directory 驗證登入。

執行下列 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 解析程式

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