使用 GraphiQL IDE

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

注意

GraphiQL 包含在 AEM 的所有环境中(但只有在配置端点时才可访问/显示)。

在以前的版本中,安装 GraphiQL IDE 时需要软件包。 如果您已安装此软件,现可将其移除。

注意

在使用 GraphiQL IDE 之前,您必须在配置浏览器配置您的端点

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

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

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

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

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

选择您的端点

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

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

创建并持久新查询

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

注意

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

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

  • 使用鼠标悬停显示有关元素的其他信息
  • 提供语法突出显示、自动完成、自动建议等功能
注意

GraphQL 查询通常以{字符开头。

#开头的行会被忽略。

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

正在更新您的持久查询

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

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

正在运行查询

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

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

  • 点击/点按​“执行查询”​图标
  • 使用键盘组合Control-Enter

查询变量

GraphiQL IDE 还允许您管理查询变量

例如:

GraphQL 变量

管理保留查询的缓存

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

使用 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. 选择​保存​来保留更改。

正在发布持久查询

一旦从列表(左面板)中选择了持久查询,您就可以使用​发布​和​取消发布​操作。 这会将它们激活到您的发布环境(例如,dev-publish),以便您的应用程序在测试时轻松访问。

注意

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

复制 URL 以直接访问查询

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

例如:

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

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

GraphiQL – 复制 URL

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

GraphiQL – 复制 URL

正在删除持久查询

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

正在生产环境中安装您的持久查询

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

键盘快捷键

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

  • 美化查询:Shift-Control-P
  • 合并查询:Shift-Control-M
  • 执行查询:Control-Enter
  • 自动完成:Control-Space
注意

在一些键盘上,该Control键被标记为Ctrl

在此页面上