解析程序的 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 对象。 客户类型是 RegisteredCustomerGuestCustomer 类型的联合。

示例架构

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>

后续步骤

有关使用策略的详细信息,请参阅: