使用 GraphiQL IDE graphiql-ide

标准 GraphiQL IDE 的实施可与 Adobe Experience Manager (AEM) as a Cloud Service 的 GraphQL API 一起使用。

NOTE
GraphiQL 包含在 AEM 的所有环境中(但只有在配置端点时才可访问/显示)。
在以前的版本中,安装 GraphiQL IDE 时需要软件包。如果您已安装此软件,现可将其移除。
NOTE
在使用 GraphiQL IDE 之前,您必须在配置浏览器配置您的端点

GraphiQL 工具让您测试和调试 GraphQL 查询,方法是:

  • 选择适用于您要用于查询的 Sites 配置的​ 端点
  • 直接输入新查询
  • 创建并访问​ 持久查询
  • 运行查询以立即查看结果
  • 管理​ 查询变量
  • 保存并管理​ 持久查询
  • 将​ 持久查询 ​发布到您的​ 发布 ​或​ 预览 ​服务,或对其进行取消发布;例如,到/从 dev-publish
  • 请参阅之前查询的​ 历史记录
  • 使用​ 文档资源管理器 ​访问文档;帮助您学习和理解可用的方法。

您可以通过以下任一方式访问查询编辑器:

  • 工具 > 常规 > GraphQL 查询编辑器
  • 直接;例如,http://localhost:4502/aem/graphiql.html

GraphiQL 接口

您可以在系统上使用 GraphiQL,以便您的客户端应用程序可以使用 GET 请求来请求查询,并发布查询。对于生产使用,您可以将查询移动到生产环境。最初是移至生产作者环境,以供通过查询来验证新撰写的内容,最后移至生产发布环境,以供实时使用。

选择您的端点 selecting-endpoint

第一步,您需要选择您想用于查询的​ 端点。该端点适用于您要用于查询的 Sites 配置。

这可以从右上角的下拉列表中获得。

创建并持久新查询 creating-new-query

您可以在编辑器中输入新查询,该编辑器位于左中面板的 GraphiQL 徽标正下方。

NOTE
如果您已经选择了一个持久查询,并显示在编辑器面板中,请选择+(在​ 持久查询 ​旁边)清空编辑器,为新查询做好准备。

只要开始输入,编辑器还会:

  • 使用鼠标悬停显示有关元素的其他信息
  • 提供语法突出显示、自动完成、自动建议等功能
NOTE
GraphQL 查询通常以{字符开头。
#开头的行会被忽略。

使用​ 另存为 ​来保存新查询。

正在更新您的持久查询 updating-persisted-query

从​ 持久查询 ​面板(最左边)的列表中选择要更新的查询。

查询会显示在编辑器面板中。进行任何需要的更改,然后使用​ 保存 ​将更新提交到持久查询。

正在运行查询 running-queries

您可以立即运行新查询,或者加载并运行持久查询。要加载持久查询,请从列表中选择它,查询会显示在编辑器面板中。

在两种情况下,编辑器面板中显示的查询都是在以下情况下运行的查询:

  • 选择 执行查询 图标
  • 使用键盘组合Control-Enter

查询变量 query-variables

GraphiQL IDE 还让您管理查询变量

例如:

GraphQL 变量

管理保留查询的缓存 managing-cache

建议使用持久查询,因为它们可以缓存在 Dispatcher 和 CDN 层,最终提高请求客户端应用程序的性能。默认情况下,AEM 将根据默认生存时间 (TTL) 使内容投放网络 (CDN) 缓存失效。

NOTE
Dispatcher 上的自定义重写规则可能会覆盖来自 AEM 发布的默认值。
如果您根据位置匹配模式从Dispatcher发送基于TTL的缓存控制标头,则可能需要排除 /graphql/execute.json/* 从匹配项中。

使用 GraphQL,您可以配置 HTTP 缓存标头,以控制单个持久查询的这些参数。

  1. 标头 ​选项可通过持久查询名称右侧的三个垂直点访问(最左侧面板):

    持久查询 HTTP 缓存标头

  2. 选择此项将打开 缓存配置 对话框:

    持久查询 HTTP 缓存标头设置

  3. 选择相应的参数,然后根据需要调整值:

    • cache-controlmax-age
      缓存可以将此内容存储指定的秒数。通常为浏览器 TTL(生存时间)。
    • surrogate-controls-maxage
      与 max-age 相同,但特别适用于代理缓存。
    • surrogate-controlstale-while-revalidate
      缓存可能会在缓存响应过期后继续为其提供服务,最长可达指定的秒数。
    • surrogate-controlstale-if-error
      在发生源错误的情况下,缓存可以继续为缓存响应提供服务,最长可达指定的秒数。
  4. 选择​ 保存 ​来保留更改。

发布和预览持久查询 publishing-previewing-persisted-queries

一旦从列表(左面板)中选择了持久查询,您就可以使用​ 发布 ​操作。

这将会激活对您选择的环境的查询。您可以选择您的​ 发布 ​环境(例如,dev-publish),或者您的​ 预览 ​环境,以便您的应用程序在测试时轻松访问。

GraphiQL - 发布持久查询

NOTE
持久查询缓存Time To Live {"cache-control":"parameter":value} 定义的默认值为 2 小时(7200 秒)。

正在取消发布持久查询 unpublishing-persisted-queries

与发布时一样,一旦从列表(左面板)中选择了持久查询,您就可以使用​ 取消发布 ​操作。

这将停用您选择的环境中的查询;即您的​ 发布 ​环境,或您的​ 预览 ​环境。

NOTE
您还应确保已对客户端应用程序进行了必要的更改,以避免出现潜在问题。

复制 URL 以直接访问查询 copy-url

“复制 URL” ​选项让您通过复制用于直接访问持久查询并查看结果的 URL 来模拟查询。然后可以将其用于测试;例如,通过在浏览器中访问:

例如:

http://localhost:4502/graphql/execute.json/global/article-list-01

通过在浏览器中使用此 URL,可以确认结果:

GraphiQL – 复制 URL

“复制 URL” ​选项可通过持久查询名称右侧的三个垂直点访问(最左侧面板):

GraphiQL – 复制 URL

正在删除持久查询 deleting-persisted-queries

“删除” ​选项也可通过持久查询名称右侧的三个垂直点访问(最左侧面板):

正在生产环境中安装您的持久查询 installing-persisted-query-production

在使用 GraphiQL 开发和测试您的持久查询之后,最终目标是将其转移到生产环境中,供应用程序使用。

键盘快捷键 keyboard-shortcuts

有多种键盘快捷键可供直接访问 IDE 中的操作图标:

  • 美化查询:Shift-Control-P
  • 合并查询:Shift-Control-M
  • 执行查询:Control-Enter
  • 自动完成:Control-Space
NOTE
在一些键盘上,该Control键被标记为Ctrl
recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab