文档AEMAEM 教程AEM Headless 教程

探索GraphQL API explore-graphql-apis

Last update: Sun Jul 14 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

创建对象：

  • 初学者
  • 开发人员

AEM的GraphQL API提供了一种强大的查询语言，用于将内容片段的数据公开给下游应用程序。 内容片段模型定义内容片段使用的数据架构。 每当创建或更新内容片段模型时，都会翻译架构并将其添加到组成GraphQL API的“图形”。

在本章中，让我们探索一些常见的GraphQL查询，以使用名为GraphiQL的IDE收集内容。 GraphiQL IDE允许您快速测试和优化返回的查询和数据。 它还提供对文档的轻松访问，使其能够轻松地学习和了解有哪些方法可用。

先决条件 prerequisites

这是一个多部分教程，并假定已完成创作内容片段中概述的步骤。

目标 objectives

  • 了解如何使用GraphiQL工具通过GraphQL语法构建查询。
  • 了解如何查询内容片段的列表和单个内容片段。
  • 了解如何过滤和请求特定数据属性。
  • 了解如何连接多个内容片段模型的查询
  • 了解如何持久GraphQL查询。

启用 GraphQL 端点 enable-graphql-endpoint

必须配置GraphQL端点才能为内容片段启用GraphQL API查询。

  1. 从AEM开始屏幕中，导航到​ 工具 > 常规 > GraphQL。

    导航到GraphQL端点

  2. 点按右上角的​ 创建，在生成的对话框中，输入以下值：

    • 名称*：我的项目终结点。
    • 使用由以下对象提供的GraphQL架构…… *： 我的项目

    创建GraphQL终结点

    点按​ 创建 ​以保存终结点。

    基于项目配置创建的GraphQL端点仅启用对属于该项目的模型的查询。 在这种情况下，只能使用对​ 人员 ​和​ 团队 ​模型的查询。

    note note
    NOTE
    还可以创建全局端点以启用跨多个配置的模型查询。 使用此选项时应当谨慎，因为它可能会使环境面临更多安全漏洞，并增加管理AEM的整体复杂性。

  3. 此时，您应会看到环境中启用了一个GraphQL端点。

    已启用graphql端点

使用 GraphiQL IDE

GraphiQL工具使开发人员能够针对当前AEM环境中的内容创建和测试查询。 GraphiQL工具还使用户能够​ 保留或保存 ​查询，以供生产设置中的客户端应用程序使用。

接下来，使用内置的GraphiQL IDE来探索AEM的GraphQL API的强大功能。

  1. 从AEM开始屏幕中，导航到​ 工具 > 常规 > GraphQL查询编辑器。

    导航到GraphiQL IDE

    note note
    NOTE
    在中，可能未内置旧版AEM GraphiQL IDE。 可以按照这些说明手动安装。

  2. 在右上角，确保终结点设置为​ 我的项目终结点。

    设置GraphQL终结点

这会将所有查询的范围设定为在​ 我的项目 ​项目中所创建的模型。

查询内容片段列表 query-list-cf

常见要求是查询多个内容片段。

  1. 将以下查询粘贴到主面板中（替换注释列表）：

    code language-graphql 
    query allTeams {
  teamList {
    items {
      _path
      title
    }
  }
}

  2. 按顶部菜单中的​ 播放 ​按钮执行查询。 您应该会看到上一章内容片段的结果：

    人员列表结果

  3. 将光标置于title文本下方并输入​ CTRL+空格键 ​以触发代码提示。 将shortname和description添加到查询。

    使用隐藏的代码更新查询

  4. 按​ 播放 ​按钮再次执行查询，您应该会看到结果包含shortname和description的其他属性。

    短名称和描述结果

    shortname是一个简单的属性，description是一个多行文本字段，GraphQL API允许我们为结果（如html、markdown、json或plaintext）选择各种格式。

查询嵌套片段

接下来，尝试查询正在检索嵌套片段，请记住​ 团队 ​模型引用了​ 人员 ​模型。

  1. 更新查询以包含teamMembers属性。 记住，这是人员模型的​ 片段引用 ​字段。 可返回人员模型的属性：

    code language-graphql 
    query allTeams {
    teamList {
        items {
            _path
            title
            shortName
            description {
                plaintext
            }
            teamMembers {
                fullName
                occupation
            }
        }
    }
}

    JSON响应：

    code language-json 
    {
    "data": {
        "teamList": {
        "items": [
            {
            "_path": "/content/dam/my-project/en/team-alpha",
            "title": "Team Alpha",
            "shortName": "team-alpha",
            "description": {
                "plaintext": "This is a description of Team Alpha!"
            },
            "teamMembers": [
                {
                "fullName": "John Doe",
                "occupation": [
                    "Artist",
                    "Influencer"
                ]
                },
                {
                "fullName": "Alison Smith",
                "occupation": [
                    "Photographer"
                ]
                }
              ]
        }
        ]
        }
    }
}

    能够针对嵌套片段进行查询是AEM GraphQL API的强大功能。 在这个简单的示例中，嵌套只有两层深。 然而，有可能进一步巢状化碎片。 例如，如果有一个​ Address ​模型与​ 人员 ​关联，则可以在单个查询中返回来自所有三个模型的数据。

筛选内容片段列表 filter-list-cf

接下来，我们看一下如何能够根据属性值将结果过滤为内容片段的子集。

  1. 在GraphiQL UI中输入以下查询：

    code language-graphql 
    query personByName($name:String!){
  personList(
    filter:{
      fullName:{
        _expressions:[{
          value:$name
          _operator:EQUALS
        }]
      }
    }
  ){
    items{
      _path
      fullName
      occupation
    }
  }
}

    上述查询对系统中的所有人员片段执行搜索。 添加到查询开头的筛选器对name字段和变量字符串$name执行比较。

  2. 在​ 查询变量 ​面板中输入以下内容：

    code language-json 
    {"name": "John Doe"}

  3. 执行查询，应仅返回​ 人 ​内容片段，其值为John Doe。

    使用查询变量进行筛选

    有许多其他选项可用于筛选和创建复杂查询，请参阅学习将GraphQL与AEM结合使用 — 示例内容和查询。

  4. 增强上述查询以获取配置文件图片

    code language-graphql 
    query personByName($name:String!){
  personList(
    filter:{
      fullName:{
        _expressions:[{
          value:$name
          _operator:EQUALS
        }]
      }
    }
  ){
    items{
      _path
      fullName
      occupation
      profilePicture{
        ... on ImageRef{
          _path
          _authorUrl
          _publishUrl
          height
          width

        }
      }
    }
  }
}

    profilePicture是内容引用，它应为图像，因此使用内置ImageRef对象。 这允许我们请求有关所引用图像的附加数据，如width和height。

查询单个内容片段 query-single-cf

也可以直接查询单个内容片段。 AEM中的内容以分层方式存储，片段的唯一标识符基于片段的路径。

  1. 在GraphiQL编辑器中输入以下查询：

    code language-graphql 
    query personByPath($path: String!) {
    personByPath(_path: $path) {
        item {
        fullName
        occupation
        }
    }
}

  2. 为​ 查询变量 ​输入以下内容：

    code language-json 
    {"path": "/content/dam/my-project/en/alison-smith"}

  3. 执行查询并观察是否返回了单个结果。

持久查询 persist-queries

一旦开发人员对查询和从查询返回的结果数据感到满意，下一步就是将查询存储或保留到AEM。 持久查询是向客户端应用程序公开GraphQL API的首选机制。 持久查询后，可以使用GET请求来请求它，并缓存到Dispatcher和CDN层。 持久查询的性能要好得多。 除了性能优势之外，持久查询还可以确保不会意外向客户端应用程序显示额外数据。 有关持久查询的更多详细信息见此处。

接下来，保留两个简单查询，它们将在下一章中使用。

  1. 在GraphiQL IDE中输入以下查询：

    code language-graphql 
    query allTeams {
    teamList {
        items {
            _path
            title
            shortName
            description {
                plaintext
            }
            teamMembers {
                fullName
                occupation
            }
        }
    }
}

    验证查询是否有效。

  2. 接下来，点按​ 另存为，并输入all-teams作为​ 查询名称。

    查询应显示在左边栏中的​ 持久查询 ​下。

    所有团队持久查询

  3. 接下来，点按永久查询旁边的省略号​ …，然后点按​ 复制URL ​以将路径复制到剪贴板。

    复制持久查询URL

  4. 打开新选项卡并将复制的路径粘贴到浏览器中：

    code language-plain 
    https://$YOUR-AEMasCS-INSTANCEID$.adobeaemcloud.com/graphql/execute.json/my-project/all-teams

    它应该类似于上述路径。 您应会看到查询返回的JSON结果。

    划分上述URL：

    table 0-row-2 1-row-2 2-row-2 3-row-2
    名称 描述
    /graphql/execute.json 持久查询端点
    /my-project /conf/my-project的项目配置
    /all-teams 持久查询的名称

  5. 返回GraphiQL IDE并使用加号按钮​ + ​保留NEW查询

    code language-graphql 
    query personByName($name: String!) {
  personList(
    filter: {
      fullName:{
        _expressions: [{
          value: $name
          _operator:EQUALS
        }]
      }
    }){
    items {
      _path
      fullName
      occupation
      biographyText {
        json
      }
      profilePicture {
        ... on ImageRef {
          _path
          _authorUrl
          _publishUrl
          width
          height
        }
      }
    }
  }
}

  6. 将查询另存为： person-by-name。

  7. 您应该保存两个持久查询：

    最终持久查询

Publish GraphQL端点和持久查询

审核和验证后，发布GraphQL Endpoint和Persisted Queries

  1. 从AEM开始屏幕中，导航到​ 工具 > 常规 > GraphQL。

  2. 点按​ 我的项目端点 ​旁边的复选框，然后点按​ Publish

    Publish GraphQL端点

  3. 从AEM开始屏幕中，导航到​ 工具 > 常规 > GraphQL查询编辑器

  4. 点按“持久查询”面板中的​ 所有团队 ​查询，然后点按​ Publish

    Publish持久查询

  5. 对person-by-name查询重复上述步骤

解决方案文件 solution-files

下载在最后三章中创建的内容、模型和持久查询： basic-tutorial-solution.content.zip

其他资源

要了解有关GraphQL查询的更多信息，请访问学习将GraphQL与AEM结合使用 — 示例内容和查询。

恭喜！ congratulations

恭喜，您已创建并执行多个GraphQL查询！

后续步骤 next-steps

在下一章构建React应用程序中，您将探索外部应用程序如何查询AEM的GraphQL端点并使用这两个持久查询。 此外，还向您介绍了在GraphQL查询执行期间进行的一些基本错误处理。

安装GraphiQL工具（可选） install-graphiql

在中，某些版本的AEM (6.X.X)需要手动安装GraphiQL IDE工具，请使用此处🔗中的说明。

recommendation-more-help
e25b6834-e87f-4ff3-ba56-4cd16cdfdec4