解析程序的 Azure SQL 数据源
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 解析程序。
- 仅当解析架构中匹配的操作类型中的单个字段时,才会调用此策略。
配置与 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>
相关策略
后续步骤
有关使用策略的详细信息,请参阅:
- 教程:转换和保护 API
- 策略参考,其中提供了策略语句及其设置的完整列表
- 策略表达式
- 设置或编辑策略
- 策略示例