文档AEMAEM 教程AEM Headless 教程

探索AEM GraphQL API

Last update: Fri Jan 26 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

创建对象：

  • Intermediate
  • Developer

AEM中的GraphQL API允许您向下游应用程序公开内容片段数据。 在基本教程中 多步骤GraphQL教程中，您已使用GraphiQL Explorer来测试和优化GraphQL查询。

在本章中，您使用GraphiQL Explorer定义更高级的查询，以收集您在中创建的内容片段的数据 上一章.

前提条件 prerequisites

本文档是多部分教程的一部分。 在继续本章之前，请确保已完成前几章。

目标 objectives

在本章中，您将学习如何：

  • 使用查询变量筛选包含引用的内容片段列表
  • 筛选片段引用中的内容
  • 从多行文本字段查询内联内容和片段引用
  • 使用指令查询
  • 查询JSON对象内容类型

使用GraphiQL资源管理器

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

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

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

    导航到GraphiQL IDE

IMPORTANT
在中，某些版本的AEM (6.X.X) GraphiQL Explorer （又称GraphiQL IDE）工具需要手动安装，请遵循 说明（从此处）.

  1. 在右上角，确保将“端点”设置为 WKND共享端点. 更改 端点 此处的下拉列表值显示现有的 持久查询 左上角。

    设置GraphQL端点

这会将所有查询的范围限定于在 WKND已共享 项目。

使用查询变量筛选内容片段列表

在上一个 多步骤GraphQL教程，您已定义并使用基本的持久查询来获取内容片段数据。 在这里，您可以展开此知识，并通过将变量传递给持久查询来筛选内容片段数据。

在开发客户端应用程序时，通常需要根据动态参数筛选内容片段。 AEM GraphQL API允许您在查询中将这些参数作为变量传递，以避免在运行时在客户端构建字符串。 有关GraphQL变量的更多信息，请参阅 GraphQL文档.

在本例中，查询所有具有特定技能的讲师。

  1. 在GraphiQL IDE中，将以下查询粘贴到左侧面板中：

    code language-graphql 
    query listPersonBySkill ($skillFilter: String!){
  personList(
    _locale: "en"
    filter: {skills: {_expressions: [{value: $skillFilter}]}}
  ) {
    items {
      fullName
      contactInfo {
        phone
        email
      }
      profilePicture {
        ... on ImageRef {
          _path
        }
      }
      biography {
        plaintext
      }
      instructorExperienceLevel
      skills
    }
  }
}

    此 listPersonBySkill 上述查询接受一个变量(skillFilter)为必填项 String. 此查询对所有人员内容片段执行搜索，并根据 skills 字段和传入的字符串 skillFilter.

    此 listPersonBySkill 包括 contactInfo 属性，是对前几章中定义的联系信息模型的片段引用。 “联系信息”模型包含 phone 和 email 字段。 查询中必须至少存在其中一个字段，才能正确执行。

    code language-graphql 
    contactInfo {
        phone
        email
      }

  2. 接下来，让我们定义 skillFilter 让所有熟练滑雪的讲师参加。 将以下JSON字符串粘贴到GraphiQL IDE的“查询变量”面板中：

    code language-json 
    {
    "skillFilter": "Skiing"
}

  3. 执行查询。 结果应类似于以下内容：

    code language-json 
    {
  "data": {
    "personList": {
      "items": [
        {
          "fullName": "Stacey Roswells",
          "contactInfo": {
            "phone": "209-888-0011",
            "email": "sroswells@wknd.com"
          },
          "profilePicture": {
            "_path": "/content/dam/wknd-shared/en/contributors/stacey-roswells.jpg"
          },
          "biography": {
            "plaintext": "Stacey Roswells is an accomplished rock climber and alpine adventurer. Born in Baltimore, Maryland, Stacey is the youngest of six children. Stacey's father was a lieutenant colonel in the US Navy and mother was a modern dance instructor. Stacey's family moved frequently with father's duty assignments and took the first pictures when father was stationed in Thailand. This is also where Stacey learned to rock climb."
          },
          "instructorExperienceLevel": "Advanced",
          "skills": [
            "Rock Climbing",
            "Skiing",
            "Backpacking"
          ]
        }
      ]
    }
  }
}

按 播放 按钮来执行查询。 您应该会看到上一章内容片段的结果：

按技能列出的人员结果

筛选片段引用中的内容

AEM GraphQL API允许您查询嵌套的内容片段。 在上一章中，您为冒险内容片段添加了三个新片段引用： location， instructorTeam、和 administrator. 现在，让我们为具有特定名称的任何管理员筛选所有冒险。

CAUTION
仅允许一个模型作为此查询的引用，才能正确执行。

  1. 在GraphiQL IDE中，将以下查询粘贴到左侧面板中：

    code language-graphql 
    query getAdventureAdministratorDetailsByAdministratorName ($name: String!){
  adventureList(
  _locale: "en"
    filter: {administrator: {fullName: {_expressions: [{value: $name}]}}}
  ) {
    items {
      title
      administrator {
        fullName
        contactInfo {
          phone
          email
        }
        administratorDetails {
          json
        }
      }
    }
  }
}

  2. 接下来，将以下JSON字符串粘贴到“查询变量”面板中：

    code language-json 
    {
    "name": "Jacob Wester"
}

    此 getAdventureAdministratorDetailsByAdministratorName 查询过滤所有冒险的任何 administrator 之 fullName “Jacob Wester”，返回来自两个嵌套内容片段的信息：冒险和讲师。

  3. 执行查询。 结果应类似于以下内容：

    code language-json 
    {
  "data": {
    "adventureList": {
      "items": [
        {
          "title": "Yosemite Backpacking",
          "administrator": {
            "fullName": "Jacob Wester",
            "contactInfo": {
              "phone": "209-888-0000",
              "email": "jwester@wknd.com"
            },
            "administratorDetails": {
              "json": [
                {
                  "nodeType": "paragraph",
                  "content": [
                    {
                      "nodeType": "text",
                      "value": "Jacob Wester has been coordinating backpacking adventures for three years."
                    }
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

从多行文本字段中查询内联引用 query-rte-reference

AEM GraphQL API允许您在多行文本字段中查询内容和片段引用。 在上一章中，您将两个引用类型添加到 描述 Yosemite团队内容片段的字段。 现在，让我们检索这些引用。

  1. 在GraphiQL IDE中，将以下查询粘贴到左侧面板中：

    code language-graphql 
    query getTeamByAdventurePath ($fragmentPath: String!){
  adventureByPath (_path: $fragmentPath) {
    item {
      instructorTeam {
        _metadata {
          stringMetadata {
            name
            value
          }
      }
        teamFoundingDate
        description {
          plaintext
        }
      }
    }
    _references {
      ... on ImageRef {
        __typename
        _path
      }
      ... on LocationModel {
        __typename
        _path
        name
        address {
          streetAddress
          city
          zipCode
          country
        }
        contactInfo {
          phone
          email
        }
      }
    }
  }
}

    此 getTeamByAdventurePath 查询按路径筛选所有冒险并返回以下内容的数据： instructorTeam 特定冒险的片段引用。

    _references 是系统生成的字段，用于显示引用，包括插入到多行文本字段中的引用。

    此 getTeamByAdventurePath 查询检索多个引用。 首先，它使用内置 ImageRef 要检索的对象 _path 和 __typename 作为内容引用插入到多行文本字段中的图像的数量。 接下来，它使用 LocationModel 以检索插入到同一字段中的位置内容片段的数据。

    该查询还包括 _metadata 字段。 这允许您检索团队内容片段的名称，并稍后在WKND应用程序中显示它。

  2. 接下来，将以下JSON字符串粘贴到“查询变量”面板中，以获取Yosemite背包冒险：

    code language-json 
    {
    "fragmentPath": "/content/dam/wknd-shared/en/adventures/yosemite-backpacking/yosemite-backpacking"
}

  3. 执行查询。 结果应类似于以下内容：

    code language-json 
    {
  "data": {
    "adventureByPath": {
      "item": {
        "instructorTeam": {
          "_metadata": {
            "stringMetadata": [
              {
                "name": "title",
                "value": "Yosemite Team"
              },
              {
                "name": "description",
                "value": ""
              }
            ]
          },
          "teamFoundingDate": "2016-05-24",
          "description": {
            "plaintext": "\n\nThe team of professional adventurers and hiking instructors working in Yosemite National Park.\n\nYosemite Valley Lodge"
          }
        }
      },
      "_references": [
        {
          "__typename": "LocationModel",
          "_path": "/content/dam/wknd-shared/en/adventures/locations/yosemite-valley-lodge/yosemite-valley-lodge",
          "name": "Yosemite Valley Lodge",
          "address": {
            "streetAddress": "9006 Yosemite Lodge Drive",
            "city": "Yosemite National Park",
            "zipCode": "95389",
            "country": "United States"
          },
          "contactInfo": {
            "phone": "209-992-0000",
            "email": "yosemitelodge@wknd.com"
          }
        },
        {
          "__typename": "ImageRef",
          "_path": "/content/dam/wknd-shared/en/adventures/teams/yosemite-team/team-yosemite-logo.png"
        }
      ]
    }
  }
}

    此 _references 字段显示徽标图像以及插入到中的Yosemite Valley Lodge内容片段 描述 字段。

使用指令查询

有时，在开发客户端应用程序时，您需要有条件地更改查询的结构。 在这种情况下，AEM GraphQL API允许您使用GraphQL指令，以便根据提供的条件更改查询的行为。 有关GraphQL指令的更多信息，请参阅 GraphQL文档.

在 上一节您已了解如何在多行文本字段中查询内联引用。 内容检索自 description 归档于 plaintext 格式。 接下来，我们展开该查询并使用指令有条件地检索 description 在 json 格式化。

  1. 在GraphiQL IDE中，将以下查询粘贴到左侧面板中：

    code language-graphql 
    query getTeamByAdventurePath ($fragmentPath: String!, $includeJson: Boolean!){
  adventureByPath(_path: $fragmentPath) {
    item {
      instructorTeam {
        _metadata{
          stringMetadata{
            name
            value
          }
        }
        teamFoundingDate
        description {
          plaintext
          json @include(if: $includeJson)
        }
      }
    }
    _references {
      ... on ImageRef {
        __typename
        _path
      }
      ... on LocationModel {
        __typename
        _path
        name
        address {
          streetAddress
          city
          zipCode
          country
        }
        contactInfo {
          phone
          email
        }
      }
    }
  }
}

    上述查询接受另一个变量(includeJson)为必填项 Boolean，也称为查询的指令。 指令可用于有条件地包含来自以下各项的数据： description 中的字段 json 基于传入的布尔值的格式 includeJson.

  2. 接下来，将以下JSON字符串粘贴到“查询变量”面板中：

    code language-json 
    {
  "fragmentPath": "/content/dam/wknd-shared/en/adventures/yosemite-backpacking/yosemite-backpacking",
  "includeJson": false
}

  3. 执行查询。 您应会获得与上一部分相同的结果 如何在多行文本字段中查询内联引用.

  4. 更新 includeJson 指示给 true 并再次执行查询。 结果应类似于以下内容：

    code language-json 
    {
  "data": {
    "adventureByPath": {
      "item": {
        "instructorTeam": {
          "_metadata": {
            "stringMetadata": [
              {
                "name": "title",
                "value": "Yosemite Team"
              },
              {
                "name": "description",
                "value": ""
              }
            ]
          },
          "teamFoundingDate": "2016-05-24",
          "description": {
            "plaintext": "\n\nThe team of professional adventurers and hiking instructors working in Yosemite National Park.\n\nYosemite Valley Lodge",
            "json": [
              {
                "nodeType": "paragraph",
                "content": [
                  {
                    "nodeType": "reference",
                    "data": {
                      "path": "/content/dam/wknd-shared/en/adventures/teams/yosemite-team/team-yosemite-logo.png",
                      "mimetype": "image/png"
                    }
                  }
                ]
              },
              {
                "nodeType": "paragraph",
                "content": [
                  {
                    "nodeType": "text",
                    "value": "The team of professional adventurers and hiking instructors working in Yosemite National Park."
                  }
                ]
              },
              {
                "nodeType": "paragraph",
                "content": [
                  {
                    "nodeType": "reference",
                    "data": {
                      "href": "/content/dam/wknd-shared/en/adventures/locations/yosemite-valley-lodge/yosemite-valley-lodge",
                      "type": "fragment"
                    },
                    "value": "Yosemite Valley Lodge"
                  }
                ]
              }
            ]
          }
        }
      },
      "_references": [
        {
          "__typename": "LocationModel",
          "_path": "/content/dam/wknd-shared/en/adventures/locations/yosemite-valley-lodge/yosemite-valley-lodge",
          "name": "Yosemite Valley Lodge",
          "address": {
            "streetAddress": "9006 Yosemite Lodge Drive",
            "city": "Yosemite National Park",
            "zipCode": "95389",
            "country": "United States"
          },
          "contactInfo": {
            "phone": "209-992-0000",
            "email": "yosemitelodge@wknd.com"
          }
        },
        {
          "__typename": "ImageRef",
          "_path": "/content/dam/wknd-shared/en/adventures/teams/yosemite-team/team-yosemite-logo.png"
        }
      ]
    }
  }
}

查询JSON对象内容类型

请记住，在关于创作内容片段的上一章中，您添加了一个JSON对象到 按季节显示天气 字段。 现在，让我们在位置内容片段中检索该数据。

  1. 在GraphiQL IDE中，将以下查询粘贴到左侧面板中：

    code language-graphql 
    query getLocationDetailsByLocationPath ($fragmentPath: String!) {
  locationByPath(_path: $fragmentPath) {
    item {
      name
      description {
        json
      }
      contactInfo {
        phone
        email
      }
      locationImage {
        ... on ImageRef {
          _path
        }
      }
      weatherBySeason
      address {
        streetAddress
        city
        state
        zipCode
        country
      }
    }
  }
}

  2. 接下来，将以下JSON字符串粘贴到“查询变量”面板中：

    code language-json 
    {
  "fragmentPath": "/content/dam/wknd-shared/en/adventures/locations/yosemite-national-park/yosemite-national-park"
}

  3. 执行查询。 结果应类似于以下内容：

    code language-json 
    {
  "data": {
    "locationByPath": {
      "item": {
        "name": "Yosemite National Park",
        "description": {
          "json": [
            {
              "nodeType": "paragraph",
              "content": [
                {
                  "nodeType": "text",
                  "value": "Yosemite National Park is in California's Sierra Nevada mountains. It's famous for its gorgeous waterfalls, giant sequoia trees, and iconic views of El Capitan and Half Dome cliffs."
                }
              ]
            },
            {
              "nodeType": "paragraph",
              "content": [
                {
                  "nodeType": "text",
                  "value": "Hiking and camping are the best ways to experience Yosemite. Numerous trails provide endless opportunities for adventure and exploration."
                }
              ]
            }
          ]
        },
        "contactInfo": {
          "phone": "209-999-0000",
          "email": "yosemite@wknd.com"
        },
        "locationImage": {
          "_path": "/content/dam/wknd-shared/en/adventures/locations/yosemite-national-park/yosemite-national-park.jpeg"
        },
        "weatherBySeason": {
          "summer": "81 / 89°F",
          "fall": "56 / 83°F",
          "winter": "46 / 51°F",
          "spring": "57 / 71°F"
        },
        "address": {
          "streetAddress": "9010 Curry Village Drive",
          "city": "Yosemite Valley",
          "state": "CA",
          "zipCode": "95389",
          "country": "United States"
        }
      }
    }
  }
}

    此 weatherBySeason 字段包含在上一章添加的JSON对象。

一次查询所有内容

到目前为止，已执行多个查询来说明AEM GraphQL API的功能。

同一数据只能通过单个查询进行检索，此查询稍后在客户端应用程序中用于检索其他信息，例如位置、团队名称、冒险的团队成员：

query getAdventureDetailsBySlug($slug: String!) {
  adventureList(filter: {slug: {_expressions: [{value: $slug}]}}) {
    items {
      _path
      title
      activity
      adventureType
      price
      tripLength
      groupSize
      difficulty
      primaryImage {
        ... on ImageRef {
          _path
          mimeType
          width
          height
        }
      }
      description {
        html
        json
      }
      itinerary {
        html
        json
      }
      location {
        _path
        name
        description {
          html
          json
        }
        contactInfo {
          phone
          email
        }
        locationImage {
          ... on ImageRef {
            _path
          }
        }
        weatherBySeason
        address {
          streetAddress
          city
          state
          zipCode
          country
        }
      }
      instructorTeam {
        _metadata {
          stringMetadata {
            name
            value
          }
        }
        teamFoundingDate
        description {
          json
        }
        teamMembers {
          fullName
          contactInfo {
            phone
            email
          }
          profilePicture {
            ... on ImageRef {
              _path
            }
          }
          instructorExperienceLevel
          skills
          biography {
            html
          }
        }
      }
      administrator {
        fullName
        contactInfo {
          phone
          email
        }
        biography {
          html
        }
      }
    }
    _references {
      ... on ImageRef {
        _path
        mimeType
      }
      ... on LocationModel {
        _path
        __typename
      }
    }
  }
}


# in Query Variables
{
  "slug": "yosemite-backpacking"
}

恭喜！

恭喜！您现在已测试高级查询，以收集您在上一章中创建的内容片段的数据。

后续步骤

在 下一章，您将了解如何持久GraphQL查询，以及为什么在应用程序中使用持久查询是最佳实践。

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