仅 DataPower API Gateway

创建 GraphQL 代理 API

在线编辑

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

关于本任务

您可以使用 API Designer UI 应用程序或使用基于浏览器的 API Manager UI 来完成此任务。

要完成此任务，您必须要分配到具有 Api-Drafts:Edit、Settings:View 和 App:View 许可权的角色。 缺省情况下，预先提供的开发者角色具有这些许可权；如果为您分配了定制角色，那么必须具有这些许可权。 有关更多信息，请参阅 创建定制角色。

GraphQL 通过 REST API 提供以下特别优势：

  • 应用程序客户机只能请求它需要的数据。 例如，在检索银行账户记录时，只请求每个账户的账号和当前余额，而不会请求客户名称和地址详细信息。 通过 REST API 请求，后端 REST 服务必须为不同的数据子集提供单独的端点，或者应用程序客户机必须检索完整的记录，然后丢弃不需要的数据。
  • 应用程序客户机可以在单个请求中检索多个相关资源。 例如，客户的银行账户记录可能包含引用客户持有的其他金融产品的数组。 如果应用程序客户机想要检索特定客户的银行账户详细信息，以及此客户的其他金融产品的详细信息，那么通过利用 REST API，客户机首先将检索银行账户详细信息，然后再对其他每个产品发出单独的请求。 GraphQL API 可设计为允许客户机在单个请求中检索所有这些信息。

但是，这种灵活性会为速率限制带来挑战，因为两个看似很相似的请求可能会返回截然不同的数据量，而需要多个 REST API 请求（每个都计入速率限制）的项可能只需要单个 GraphQL API 请求。 因此，重要的是实施速率限制控制措施，以反映检索的数据量。 API Connect 通过在 GraphQL API 定义中提供配置一系列设置的能力来扩展 GraphQL 标准，这些设置用于计算 GraphQL 请求的复杂性以及计入速率限制的关联成本。

过程

要创建 GraphQL API 代理定义，请完成以下步骤：
  1. 在导航窗格中，单击 API UI 导航窗格中的 "开发" 图标 “开发 ”，然后单击 “添加 ”> “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 的请求头中。
    • 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 定义。

下一步

使用 GraphQL 模式编辑器来查看并处理与该模式相关的任何警告，并配置一系列用于计算 GraphQL 请求的复杂度以及计入速率限制的相关成本的设置；有关详细信息，请参阅 《使用 GraphQL 模式编辑器 》。