文件AEMAEM 教學課程AEM Headless 教學課程

探索AEM GraphQL API

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主題：

建立對象：

  • undefined
  • undefined

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查詢會篩選fullName個「Jacob Wester」的任何administrator的所有冒險，傳回兩個巢狀內容片段中的資訊：冒險和講師。

  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團隊內容片段的​ Description ​欄位。 現在，讓我們擷取這些參考。

  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 Backpacking Adventure：

    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欄位同時顯示標誌影像和插入​ Description ​欄位的Yosemite Valley Lodge內容片段。

使用指令進行查詢

有時在開發使用者端應用程式時，您需要有條件地變更查詢的結構。 在此情況下，AEM GraphQL API可讓您使用GraphQL指示，以根據提供的條件變更查詢的行為。 如需GraphQL指示詞的詳細資訊，請參閱GraphQL檔案。

在上一節中，您已瞭解如何在多行文字欄位中查詢內嵌參考。 內容是從plaintext格式的description欄位擷取。 接下來，讓我們展開該查詢，並使用指示詞來有條件地擷取json格式的description。

  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，也稱為查詢的指示詞。 指示詞可用來根據在includeJson中傳遞的布林值，有條件地包含json格式的description欄位資料。

  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