创建 GraphQL 代理 API

GraphQL 是 API 查询语言，与 REST API 请求相比，它使应用程序客户机能够更好地控制在 API 请求中检索的数据。 IBM® API Connect 使您能够创建用于代理后端 GraphQL 服务器的 GraphQL API 代理定义，并定义速率限制控件以反映请求 GraphQL API 从服务器返回的数据量。

要创建 GraphQL API 代理定义，请完成以下步骤：

1. 在导航窗格中，单击 开发，然后单击 添加 > API。
   这样会显示选择 API 类型屏幕。
2. 选择OpenAPI 2.0。
3. 选择 从现有 GraphQL 服务 (GraphQL 代理)。
4. 单击下一步。 在信息部分中指定 API 摘要。 您可以在创建 API 之后进行优化。
   • 标题可以包含特殊字符，但是应保持简短，以便于在用户界面中显示。
   • 将自动输入 名称 。 名称 字段中的值是用于在 developer toolkit CLI 命令中标识 API 的单个字符串。 要查看用于管理草稿 API 的 CLI 命令，请参阅 工具箱 CLI 参考文档。
   • 版本 对应于 API 的 OpenAPI 定义的 info.version 属性值。 建议使用 version.release.modification 版本编号方案，例如，1.0.0。
   • 基本路径是 API 的 URL 段，并且不包含主机名或者路径或操作的任何其他段。 基本路径不能包含特殊字符，并且必须以 / 字符开头，即使该字符在其他情况下为空也是如此。
   • 可选的描述有助于识别 API。
5. 在 GraphQL Server 部分中，指定以下值:
   • GraphQL 服务器 URL：此 URL 用于针对后端 GraphQL API 的请求。 将从指定的 URL 自动导入 GraphQL 模式。
   • 模式名称：此处输入的名称用于标识从导入的 GraphQL 模式创建的模式定义。 此字段已预先填充了在 GraphQL 服务器 URL 字段中输入的值的主机名部分，但是您可以进行更改。
6. 单击下一步。 如果存在指示与导入的模式相关的任何警告，那么现在可以通过单击查看来查看这些警告。
   您可以在创建 GraphQL 代理 API 后酌情处理这些警告。
7. 在 操作和路径 部分中，选择要包含的操作和路径。

   已选择 /graphql 的操作路径，您无法更改此设置; 这是应用程序客户机请求调用 GraphQL API 的 API Connect 的路径。

   有关支持向 /graphql/cost 端点发送请求的机制的详细信息，请参阅 GraphQL 端点支持的请求机制。

   您还可以选择 graphql/cost 操作路径；此路径支持应用程序客户机在生成实际请求之前获取 GraphQL API 的请求成本详细信息。 在生产环境中，您尤其应该仔细考虑提供此路径的资源影响。 有关启用成本端点的完整详细信息，请参阅 为 GraphQL API 启用成本端点。

   要构成完整的 API 路径，这些路径段将附加到您在步骤 4中指定的 basepath 。

   要允许应用程序客户机针对此 GraphQL 代理 API 发送自省请求，请选择支持缺省自省。 有关完整详细信息，请参阅 支持 GraphQL API 的自省。

   要允许用户从 GraphiQL 编辑器测试 GraphQL 代理 API，请选择启用 GraphiQL 编辑器。 有关完整详细信息，请参阅 对 GraphQL API 启用 GraphiQL 编辑器。

   注: graphql/cost， 支持缺省自省和 启用 GraphiQL 编辑器 选项，每个选项都会自动在 API 组合件中生成必须手动创建的策略配置 (如果您禁用此选项并稍后决定需要此选项)。
8. （可选）您可以通过从本地文件系统上载模式来替换从 GraphQL 服务器 URL 导入的 GraphQL 模式。 单击替换；然后，您可以拖放文件，或者单击指示的位置以从本地文件系统中选择文件。 完成后单击 上载 。
   注：

   • 必须以 GraphQL 模式定义语言 (SDL) 编写模式。 有关更多信息，请参阅 GraphQL 文档 ( https://graphql.org/) 中的 类型语言 。
   • 如果从本地文件上载模式，并且该本地文件先前曾通过 URL 上载模式，那么在 API 的 OpenAPI 源中存储并随后显示在用户界面中的模式 URL 设置将保留先前指定的 URL 值，而不是指示文件位置。
9. 单击下一步。 在安全部分中，配置您需要的 API 安全性。
   • 使用客户机标识进行保护 - 选择此选项可要求应用程序提供客户机标识（API 密钥）。 这将导致 X-IBM-Client-Id 参数包含在 API 的请求头中。 有关 IBM API Connect中的安全性选项的信息，请参阅 配置 API 安全性。
   • CORS － 选择此选项来为 API 启用跨源资源共享 (CORS) 支持。 这将允许从其他域访问您的 API。
     注：

     • CORS 支持仅在 DataPower® API Gateway上可用。
     • 启用 CORS 时，API 网关会运行 cors 预流策略以处理针对 API 发出的所有 CORS 请求。
     • 启用 CORS 并收到预检请求时，仅执行以下 API 操作：
       • cors 预流策略配置相应的响应头。
       • 将设置响应头。
     • 收到预检请求时，request.attributes.isCORSPreflight 标志将设置为 true。
     • 对于所有预检请求，始终跳过 security 和 client-identification 预流策略，无论是否启用 CORS 都是如此。
10. 可选: 如果要立即使用 API 进行进一步开发和测试，请选择 激活 API 。
    注：

    • 选择 激活 API 选项时， API Connect 会自动完成以下操作:
      • 创建草稿产品，将 API 添加到该产品，并将该产品发布到沙箱目录以便可以调用该 API。 产品标题为 api_title 自动产品。 此产品在开发视图中不可见，您无法直接删除。 但是，如果删除 API ，那么会将草稿产品与 API 一起删除; 请参阅 删除 API 定义。 该产品在它发布至的任何目录中可见。 如果要从目录中除去产品，那么必须单独执行此操作; 请参阅 从目录中除去产品
      • 为产品预订沙箱测试应用程序，以便立即在测试环境中对 API 进行测试。 有关测试 API 的信息，请参阅 测试 API。
    • 如果在 "沙箱" 目录中针对 "阶段" ， "发布" 或 "替换" 操作启用了生命周期核准，那么不能使用 激活 API 选项。 如果启用了任何此类生命周期核准，那么为了能够使用 激活 API 选项，必须将其禁用; 有关生命周期核准设置的信息，请参阅 创建和配置目录。
    • 要使用 激活 API 选项，必须为您分配具有 Product:Manage 和 Subscription:Manage 许可权的角色。 缺省情况下，预先提供的开发者角色具有这些许可权；如果为您分配了定制角色，那么必须具有这些许可权。 有关更多信息，请参阅 创建定制角色。
11. 单击 下一步 以创建 API 定义。

    “摘要”面板会在创建定义时显示消息，并强制执行选定的安全选项。

    如果您选择激活API ，向导将为您填充一个API端点 URL ，您可以在测试中使用。 如果同时选中了使用客户机标识进行保护，那么此向导还会显示可使用的客户机标识和客户机密钥。

12. 单击 下一步 以创建 API 定义。

    “汇总”面板将在定义创建好后显示消息，并实施所选的安全性选项和速率限制。

13. 选择以下某个选项：
    • 要进一步配置 API，请单击编辑 API。 有关详细信息，请参阅 编辑 API 定义。
    • 如果此时不想要进一步配置 API，请单击面包屑跟踪中的开发链接，以返回到欢迎页面；随后即可立即继续处理其他任务。 有关以后如何配置 API 的详细信息，请参阅 编辑 API 定义。