使用 GraphQL

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

GraphQL 政策可以将 GraphQL 请求载荷解析为消息流变量，并且/或者根据 GraphQL 架构验证请求。

The GraphQL policy can parse GraphQL payloads into message flow variables, verify GraphQL requests against a schema, or both.

You can use the GraphQL policy to:

• Ensure that your APIs only process requests that conform to the schema you provide.
• Impose restrictions on the payload by setting a maximum on the number of fragments allowed.
• Associate GraphQL with API products.
• Leverage the Oauth2, VerifyAPIKey, and Quota policy features, just as in REST.

GraphQL supports the following types of payloads:

• POST of graphQL payloads with Content-Type : application/graphql
• POST of graphQL payloads with Content-Type: applcation/json
• GET of graphQL payloads where the payload is a query parameter

Note: For application/json payloads of the form

{
"query": "...",
"operationName": "...",
"variables": { "myVariable": "someValue", ... }
}

Apigee currently ignores the optional operationName and variables fields.

如需查看 GraphQL 政策选项的快速摘要，请参阅下面的 GraphQL 选项。

如需详细了解 GraphQL，请参阅 GraphQL.org。

示例

以下示例展示了如何将 GraphQL 架构上传到 Apigee，并使用它来验证包含 GraphQL 内容的请求。

注意：根据架构验证载荷通常是一项费用较高的操作，我们建议您谨慎选择执行架构验证。架构验证操作可能会占用大量 CPU 资源，尤其是在载荷和架构很复杂的情况下，并且可能会导致明显的延迟。

注意：每个政策只能提供一个架构。如果您需要添加多个架构，请向您的代理添加多个 GraphQL 政策。

注意：仅适用于经典版代理编辑器：

• 只有在添加 GraphQL 政策时，才能上传 GraphQL 架构文件。您无法在代理编辑器的资源窗格中上传该文件。
• 上传 GraphQL 架构文件后，您将无法在代理编辑器中查看或修改该文件。

这些限制不适用于新版代理编辑器。

创建架构文件

如需运行该示例，请先创建一个包含以下内容的 GraphQL 架构文件：

type Query {
  allPersons(last: Int): [Person!]!
}

type Mutation {
  createPerson(name: String!, age: Int!): Person!
}

type Subscription {
  newPerson: Person!
}

type Person {
  name: String!
  sex: String!
  age: Int!
  posts: [Post!]!
}

type Post {
  title: String!
  author: Person!
}

以您要使用的名称保存该文件，并在其后附加扩展名 .graphql。

在 Apigee 界面中添加 GraphQL 政策

注意：Apigee 引入了新版代理编辑器，可让您更轻松地管理代理。

下文前两个标签页中的说明介绍了如何使用新版代理编辑器或经典版代理编辑器。

新版代理编辑器

首先，按如下方式创建 GraphQL 政策：

1. 登录 Apigee 界面。
2. 在导航栏中，依次选择开发 > API 代理。
3. 在代理列表中，选择要为其使用 GraphQL 政策的 API 代理。
4. 点击DEVELOP标签页。
5. 在左侧窗格中，点击政策文件夹旁边的 + 按钮。

6. 在创建政策对话框中，点击选择政策类型 (Select policy type) 字段，向下滚动到中介，然后选择 GraphQL。

   

   输入显示名称和名称。

   接下来，按如下方式选择 GraphQL 架构文件：

   1. 点击架构文件字段。此时会显示以下选项：
      • 无架构。如果您选择此选项，Apigee 将不会使用架构来验证请求。
      • 导入 GraphQL 架构 (.graphql)

   2. 选择导入 GraphQL 架构 (.graphql)。此时会显示以下内容：

      

   3. 点击选择文件，然后选择您之前创建的架构文件（必须具有扩展名 .graphql）。该文件会显示在架构名称中字段。

      
7. 点击创建以创建该政策。

现在您已创建了 GraphQL 政策，接下来可以将其附加到 PreFlow 中的步骤：

1. 在左侧窗格中，依次选择“代理端点”(Proxy Endpoints) > 默认 > PreFlow：

   

2. 点击可视化编辑器右下角PreFlow窗格中 PreFlow 旁边的 + 按钮：

   

3. 在 Add policy step（添加政策步骤）对话框中，选择 GQL- 政策。
   注意：此示例为 GraphQL 政策使用默认名称 GQL。您可以在 XML 的 DisplayName 元素中更改政策名称，方法是在 GQL- 后面添加描述性词组。请参阅更改政策名称。
4. 点击添加以附加该政策。
5. 点击保存，保存当前修订版本以及您所做的更改。
6. 如需部署更改，请点击概览标签页，然后选择部署。

如需了解您可以为 GraphQL 政策设置的选项，请参阅下面的 GraphQL 选项。

经典版代理编辑器

1. 登录 Apigee 界面。
2. 在导航栏中，依次选择开发 > API 代理。
3. 在代理列表中，选择要为其使用 GraphQL 政策的 API 代理。
4. 点击DEVELOP标签页。

5. 在流：PreFlow 窗格中，点击添加步骤按钮。

   

6. 在添加步骤窗格中，向下滚动到中介部分的底部，然后选择 GraphQL。

   

   添加步骤窗格将显示以下选项：

   • 显示名：政策的显示名。
   • 名称：政策的内部名称。
   • 架构文件：用于上传包含 GraphQL 架构的文件的选项，Apigee 将使用该架构来验证包含 GraphQL 内容的请求。

   要使用架构，请执行以下操作：

   1. 点击架构文件字段。此时会显示以下选项：
      • 无架构。如果您选择此选项，Apigee 将不会使用架构来验证请求。
      • 导入 GraphQL 架构 (.graphql)

   2. 选择导入 GraphQL 架构 (.graphql)。此时会显示以下内容：

      

   3. 点击选择文件，然后选择您之前创建的架构文件（必须具有扩展名 .graphql）。该文件会显示在架构名称字段中。

      

7. 点击添加。流：PreFlow 窗格现在如下所示：

   

   如需了解您可以为 GraphQL 政策设置的选项，请参阅下面的 GraphQL 选项。在此示例中，请保持这些选项不变。

8. 如需部署代理，请点击概览标签页，然后选择部署。

   

现在，您可以使用以下 curl 命令测试 GraphQL 政策：

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query query_name {allPersons {name}}' -k

其中 PROXY_BASEPATH 是代理基本路径，HOST_NAME 是代理的名称（包括最新修订版本号）。运行该命令时，Apigee 会根据架构验证请求并返回以下输出。

{
  "query query_name {allPersons {name}}": "",
  "id": 101
}

下面是另一个请求示例：

curl --location --request POST 'https://PROXY_BASEPATH/HOST_NAME' --data-raw 'query ilovegql {DEADBEEF}' -k

这一次请求验证失败，并显示以下错误消息。

{"fault":{"faultstring":"steps.graphQL.SchemaValidationFailed","detail":{"errorcode":"steps.graphQL.SchemaValidationFailed"}}}

GraphQL 选项

GraphPolicy 具有以下选项：

• OperationType：操作类型。选项包括：
  • query：REST GET 操作的 GraphQL 等效项。
  • mutation：REST PUT 操作的 GraphQL 等效项。
  • query_mutation：同时 query 和 mutation。
• MaxDepth：查询的最大深度（以树状表示时）。借助 MaxDepth，您可以阻止载荷中的深度查询，这样 Apigee 就不需要创建非常大量的流变量来保存这些值。不过，无论 MaxDepth 的值为何，载荷都会按原样发送。
• MaxCount：载荷中可以存在的片段数上限。您可以利用此元素来防止客户的 GraphQL 后端服务器执行高度复杂的查询，从而强制客户端将逻辑拆分为较小的载荷。
• Action：以下 GraphQL 操作之一：
  • parseApigee 会将 GraphQL 载荷解析为流变量。您随后可以在 JavaCallout 等政策中使用流变量的内容。请注意，parse 还会验证载荷。
  • verify：Apigee 将验证 GraphQL 载荷是否符合上传到代理的架构。您可以使用 verify 来确保不会收到不符合您架构的请求。这样可以在后端节省宝贵的 CPU 时间。
  • parse_verify：解析并验证载荷。
• ResourceURL：Apigee 用于验证 GraphQL 请求的 GraphQL 架构文件的路径。

如需详细了解这些选项，请参阅 GraphQL 政策参考页面。