解析程序的 HTTP 数据源
适用于:所有 API 管理层级
http-data-source
解析程序策略会配置 HTTP 请求,并可以配置 HTTP 响应以解析 GraphQL 架构中对象类型和字段的数据。 该架构必须作为 GraphQL API 导入到 API 管理。
注意
按照策略声明中提供的顺序设置策略的元素和子元素。 详细了解如何设置或编辑 API 管理策略。
策略语句
<http-data-source>
<http-request>
<get-authorization-context>...get-authorization-context policy configuration...</get-authorization-context>
<set-backend-service>...set-backend-service policy configuration...</set-backend-service>
<set-method>...set-method policy configuration...</set-method>
<set-url>URL</set-url>
<include-fragment>...include-fragment policy configuration...</include-fragment>
<set-header>...set-header policy configuration...</set-header>
<set-body>...set-body policy configuration...</set-body>
<authentication-certificate>...authentication-certificate policy configuration...</authentication-certificate>
</http-request>
<backend>
<forward-request>...forward-request policy configuration...</forward-request>
<http-response>
<set-body>...set-body policy configuration...</set-body>
<xml-to-json>...xml-to-json policy configuration...</xml-to-json>
<find-and-replace>...find-and-replace policy configuration...</find-and-replace>
<publish-event>...publish-event policy configuration...</publish-event>
<include-fragment>...include-fragment policy configuration...</include-fragment>
</http-response>
</http-data-source>
元素
名称 | 说明 | 必须 |
---|---|---|
http-request | 指定用于配置解析程序的 HTTP 请求的 URL 和子策略。 | 是 |
后端 | 如果指定了解析程序的 HTTP 请求,则可以选择将其转发到后端服务。 | 否 |
http-response | (可选)指定用于配置解析程序的 HTTP 响应的子策略。 如果未指定此项,响应将作为原始字符串返回。 | 否 |
http-request 元素
注意
除非另有说明,否则每个子元素最多可以指定一次。 按列出的顺序指定元素。
元素 | 说明 | 必需 |
---|---|---|
get-authorization-context | 获取解析程序的 HTTP 请求的授权上下文。 | 否 |
set-backend-service | 将解析程序的 HTTP 请求重定向到指定的后端。 | 否 |
include-fragment | 在策略定义中插入策略片段。 如果有多个片段,则添加其他 include-fragment 元素。 |
否 |
set-method | 设置解析程序的 HTTP 请求的方法。 | 是 |
set-url | 设置解析程序的 HTTP 请求的 URL。 | 是 |
set-header | 设置解析程序的 HTTP 请求中的标头。 如果存在多个标头,则添加其他 header 元素。 |
否 |
set-body | 设置解析程序的 HTTP 请求中的正文。 | 否 |
authentication-certificate | 使用解析程序的 HTTP 请求中的客户端证书进行身份验证。 | 否 |
后端元素
元素 | 说明 | 必需 |
---|---|---|
forward-request | 将解析程序的 HTTP 请求转发到已配置的后端服务。 | 否 |
http-response 元素
注意
除非另有说明,否则每个子元素最多可以指定一次。 按列出的顺序指定元素。
名称 | 说明 | 必需 |
---|---|---|
set-body | 设置解析程序的 HTTP 响应中的正文。 | 否 |
xml-to-json | 将解析程序的 HTTP 响应从 XML 转换为 JSON。 | 否 |
find-and-replace | 在解析程序的 HTTP 响应中查找 substring,并将其替换为其他 substring。 | 否 |
publish-event | 将事件发布到 GraphQL API 架构中指定的一个或多个订阅。 | 否 |
include-fragment | 在策略定义中插入策略片段。 如果有多个片段,则添加其他 include-fragment 元素。 |
否 |
使用情况
使用注意事项
- 若要使用此策略配置和管理解析程序,请参阅配置 GraphQL 解析程序。
- 仅当解析架构中匹配的 GraphQL 操作类型中的单个字段时,才会调用此策略。
示例
GraphQL 查询的解析程序
以下示例通过对后端数据源进行 HTTP GET
调用来解析查询。
示例架构
type Query {
users: [User]
}
type User {
id: String!
name: String!
}
示例策略
<http-data-source>
<http-request>
<set-method>GET</set-method>
<set-url>https://data.contoso.com/get/users</set-url>
</http-request>
</http-data-source>
使用 liquid 模板返回一个列表的 GraqhQL 查询的解析程序
以下示例使用一个允许在 set-body 策略中使用的 liquid 模板,在对查询的 HTTP 响应中返回一个列表。 它还将来自 REST API 的响应中的 username
字段重命名为 GraphQL 响应中的 name
。
示例架构
type Query {
users: [User]
}
type User {
id: String!
name: String!
}
示例策略
<http-data-source>
<http-request>
<set-method>GET</set-method>
<set-url>https://data.contoso.com/users</set-url>
</http-request>
<http-response>
<set-body template="liquid">
[
{% JSONArrayFor elem in body %}
{
"name": "{{elem.username}}"
}
{% endJSONArrayFor %}
]
</set-body>
</http-response>
</http-data-source>
GraphQL 变更的解析程序
以下示例通过向 HTTP 数据源发出 POST
请求来解析一个插入数据的变更。 HTTP 请求的 set-body
策略中的策略表达式修改 name
参数,该参数在 GraphQL 查询中作为其正文传递。 发送的正文类似于以下 JSON:
{
"name": "the-provided-name"
}
示例架构
type Query {
users: [User]
}
type Mutation {
makeUser(name: String!): User
}
type User {
id: String!
name: String!
}
示例策略
<http-data-source>
<http-request>
<set-method>POST</set-method>
<set-url>https://data.contoso.com/user/create </set-url>
<set-header name="Content-Type" exists-action="override">
<value>application/json</value>
</set-header>
<set-body>@{
var args = context.GraphQL.Arguments;
JObject jsonObject = new JObject();
jsonObject.Add("name", args["name"])
return jsonObject.ToString();
}</set-body>
</http-request>
</http-data-source>
GraphQL 联合类型的解析程序
以下示例通过对后端数据源进行 HTTP GET
调用来解析 orderById
查询,并返回包含客户 ID 和类型的 JSON 对象。 客户类型是 RegisteredCustomer
和 GuestCustomer
类型的联合。
示例架构
type Query {
orderById(orderId: Int): Order
}
type Order {
customerId: Int!
orderId: Int!
customer: Customer
}
enum AccountType {
Registered
Guest
}
union Customer = RegisteredCustomer | GuestCustomer
type RegisteredCustomer {
accountType: AccountType!
customerId: Int!
customerGuid: String!
firstName: String!
lastName: String!
isActive: Boolean!
}
type GuestCustomer {
accountType: AccountType!
firstName: String!
lastName: String!
}
示例策略
在本示例中,我们模拟了来自外部源的客户结果,并在 set-body
策略中对提取的结果进行了硬编码。 __typename
字段用于确定客户的类型。
<http-data-source>
<http-request>
<set-method>GET</set-method>
<set-url>https://data.contoso.com/orders/</set-url>
</http-request>
<http-response>
<set-body>{"customerId": 12345, "accountType": "Registered", "__typename": "RegisteredCustomer" }
</set-body>
</http-response>
</http-data-source>
相关策略
后续步骤
有关使用策略的详细信息,请参阅:
- 教程:转换和保护 API
- 策略参考,其中提供了策略语句及其设置的完整列表
- 策略表达式
- 设置或编辑策略
- 策略示例