解析程序的 Azure SQL 数据源

项目
01/08/2024

sql-data-source 解析程序策略配置一个针对 Azure SQL 数据库的 Transact-SQL (T-SQL) 请求和一个可选的响应来解析 GraphQL 架构中对象类型和字段的数据。该架构必须作为 GraphQL API 导入到 API 管理。

注意

此策略为预览版。目前，API 管理的消耗层不支持该策略。

注意

按照策略声明中提供的顺序设置策略的元素和子元素。详细了解如何设置或编辑 API 管理策略。

策略语句

<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 请求和可选参数。	是
response	（可选）指定子策略以配置来自 Azure SQL 数据库的响应。如果未指定，将从 Azure SQL 返回 JSON 格式的响应。	否

connection-info 元素

注意

除非另有说明，否则每个子元素最多可以指定一次。按列出的顺序指定元素。

元素	说明	必需
connection-string	指定 Azure SQL 连接字符串。连接字符串使用 SQL 身份验证（用户名和密码）或 Microsoft Entra 身份验证（如果配置了 API 管理托管标识）。	是
include-fragment	在策略定义中插入策略片段。如果有多个片段，则添加其他 `include-fragment` 元素。	否
authentication-certificate	使用解析程序的 SQL 请求中的客户端证书进行身份验证。	否

connection-string 属性

Attribute	说明	需要	默认
use-managed-identity	布尔值。指定是否使用 API 管理实例的系统分配的托管标识代替连接字符串中的用户名和密码，来连接到 Azure SQL 数据库。允许使用策略表达式。必须配置该标识才能访问 Azure SQL 数据库。	否	`false`

请求属性

Attribute	说明	需要	默认
single-result	布尔值。指定对查询的响应是否应最多返回一行。允许使用策略表达式。	否	`false`

请求元素

注意

每个子元素最多只能被指定一次。按列出的顺序指定元素。

元素	说明	必需
include-fragment	在策略定义中插入策略片段。	否
set-body	设置解析程序的 SQL 请求中的正文。	否
sql-statement	针对 Azure SQL 数据库的请求的 T-SQL 语句。该 SQL 语句可能包含多个要按顺序执行的独立子语句，例如 UPDATE、DELETE 和 SELECT。结果是从最终子语句返回的。	是
parameters	该请求的 SQL 参数（在 `parameter` 子元素中）的列表。	否

parameter 特性

Attribute	说明	需要	默认
name	字符串。 SQL 参数的名称。	是	空值
sql-type	字符串。 SQL 参数的数据类型。	否	空值

response 元素

注意

每个子元素最多只能被指定一次。按列出的顺序指定元素。

名称	说明	必需
include-fragment	在策略定义中插入策略片段。	否
set-body	设置解析程序的响应中的正文。	否
publish-event	将事件发布到 GraphQL API 架构中指定的一个或多个订阅。	否

使用情况

策略范围：GraphQL 解析程序
网关：专用

使用注意事项

若要使用此策略配置和管理解析程序，请参阅配置 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.chinacloudapi.cn,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.chinacloudapi.cn,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 解析程序策略

后续步骤

有关使用策略的详细信息，请参阅：

教程：转换和保护 API
策略参考，其中提供了策略语句及其设置的完整列表
策略表达式
设置或编辑策略
策略示例