共用方式為

解析器的 Azure SQL 資料來源

  • 發行項

適用於：開發人員 | 基本 | 基本 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 解析器。
  • 只有在結構描述的相符作業類型中解析單一欄位時，才會叫用此原則。

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

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

必要條件

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

啟用 Microsoft Entra ID 存取

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

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

指派角色

  1. 在入口網站中，移至您的 Azure SQL 資料庫資源。

  2. 選取 [查詢編輯器 (預覽)]。

  3. 使用 Active Directory 驗證登入。

  4. 執行下列 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>

相關內容

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