配置 GraphQL 解析程序

项目
05/13/2024

适用于：所有 API 管理层级

配置解析程序以检索或设置 GraphQL 架构中所指定对象类型中的 GraphQL 字段的数据。该架构必须作为 GraphQL API 导入到 API 管理。

目前，API 管理支持可以访问以下数据源的解析程序：

使用须知

解析程序是一种包含策略定义的资源，只有在执行架构中匹配的对象类型和字段时才会调用。
每个解析程序都解析单个字段的数据。若要解析多个字段的数据，请为每个字段配置单独的解析程序。
在策略执行管道中的任何 inbound 和 backend 策略之后评估解析程序范围的策略。它们不会从其他范围继承策略。有关详细信息，请参阅 API 管理中的策略。
可以独立于解析器范围的策略，为 GraphQL API 配置 API 范围的策略。例如，将 validate-graphql-request 策略添加到 inbound 范围，以在调用解析程序之前验证请求。在 API 的“API 策略”选项卡上配置 API 范围的策略。
若要支持 GraphQL 解析器中的接口和联合类型，后端响应必须已包含 __typename 字段，或者使用 set-body 策略更改该响应以包含 __typename。

先决条件

现有的 API 管理实例。如果还没有实例，请创建一个。
导入直通或合成 GraphQL API。

创建解决程序

以下步骤使用基于 HTTP 的数据源创建解析程序。对于使用支持的数据源的任何解析程序，常规步骤均类似。

在 Azure 门户，导航到 API 管理实例。
在左侧菜单中，选择“API”，然后选择 GraphQL API 的名称。
在“架构”选项卡上，查看（要在其中配置解析程序的）对象类型中字段的架构。
1. 选择一个字段，然后在左边距中悬停指针。
2. 选择“+ 添加解析程序”。
在“创建解析程序”页上：
1. 根据需要更新“名称”属性，可选择输入“说明”，并确认或更新“类型”和“字段”选择。
2. 选择解析程序的“数据源”。对于此示例，请选择“HTTP API”。
在解析程序策略编辑器中，使用适合你的情况的子元素更新 http-data-source 策略。
1. 使用可将 GraphQL 操作转换为 HTTP 请求的策略更新所需的 http-request 元素。
2. 可选择添加 http-response 元素，并添加子策略来转换解析程序的 HTTP 响应。如果未指定 http-response 元素，响应将作为原始字符串返回。
3. 选择“创建” 。
解析程序将附加到该字段并显示在“解析程序”选项卡上。

管理解析程序

在 API 的“解析程序”选项卡上列出和管理 GraphQL API 的解析程序。

在“解析程序”选项卡上：

“已链接”列指示是否为当前位于 GraphQL 架构中的字段配置了解析程序。如果未链接解析程序，则无法对其进行调用。
在解析程序的上下文菜单 (...) 中，找到用于“克隆”、“编辑”或“删除”解析程序的命令。克隆列出的解析程序，以快速创建面向不同类型和字段的类似解析程序。
可以通过选择“+ 创建”来创建新的解析程序。

编辑和测试解析程序

编辑单个解析程序时，将打开“编辑解析程序”页。你可以：

更新解析程序策略和数据源（可选）。更改数据源会覆盖当前解析程序策略。
更改解析程序的目标类型和字段。
测试和调试解析程序的配置。编辑解析程序策略时，选择“运行测试”以检查数据源的输出，可以根据架构进行验证。如果发生错误，响应将包含故障排除信息。

GraphQL 上下文

解析程序请求和响应（如果指定）的上下文不同于原始网关 API 请求的上下文：
- context.GraphQL 属性设置为当前解析程序执行的参数 (Arguments) 和父对象 (Parent)。
- 解析程序的请求上下文包含作为其正文在 GraphQL 查询中传递的参数。
- 解析程序的响应上下文是解析程序发出的独立调用的响应，而不是网关请求的完整响应的上下文。将通过请求和响应管道传递的 context 变量与 GraphQL 解析程序结合使用时，将为该变量填充 GraphQL 上下文。

context.GraphQL.parent

context.GraphQL.parent 设置为当前解析程序执行的父对象。考虑以下部分架构：

type Comment {
    id: ID!
    owner: string!
    content: string!
}

type Blog {
    id: ID!
    title: string!
    content: string!
    comments: [Comment]!
    comment(id: ID!): Comment
}

type Query {
    getBlog(): [Blog]!
    getBlog(id: ID!): Blog
}

另请考虑针对特定博客的所有信息运行 GraphQL 查询：

query {
    getBlog(id: 1) {
        title
        content
        comments {
            id
            owner
            content
        }
    }
}

如果为 Blog 类型中的 comments 字段设置解析程序，则需要了解要使用的博客 ID。可以使用 context.GraphQL.Parent["id"] 获取博客的 ID，如以下解析程序所示：

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/blog/{context.GraphQL.Parent["id"]}")
        </set-url>
    </http-request>
</http-data-source>

context.GraphQL.Arguments

参数化 GraphQL 查询的参数将添加到 context.GraphQL.Arguments 中。例如，考虑以下两个查询：

query($id: Int) {
    getComment(id: $id) {
        content
    }
}

query {
    getComment(id: 2) {
        content
    }
}

这些查询是调用 getComment 解析程序的两种方式。 GraphQL 发送以下 JSON 有效负载：

{
    "query": "query($id: Int) { getComment(id: $id) { content } }",
    "variables": { "id": 2 }
}

{
    "query": "query { getComment(id: 2) { content } }"
}

可按如下所示定义解析程序：

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>@($"https://data.contoso.com/api/comment/{context.GraphQL.Arguments["id"]}")</set-url>
    </http-request>
</http-data-source>

后续步骤

有关更多解析程序示例，请参阅：

通过