了解GraphQL API

AEM的GraphQL API提供強大的查詢語言,可將內容片段的資料公開給下游應用程式。 內容片段模型會定義內容片段所使用的資料結構。 每當建立或更新內容片段模型時,架構就會轉譯並新增至組成GraphQL API的「圖表」中。

在本章中,我們將探索一些常見的GraphQL查詢,以使用名為GraphiQL的IDE收集內容。 GraphiQL IDE允許您快速測試和調整返回的查詢和資料。 GraphiQL還可輕鬆存取說明檔案,讓您輕鬆了解和了解可用的方法。

必備條件

這是多部分教學課程,假設已完成製作內容片段中概述的步驟。

目標

  • 了解如何使用GraphiQL工具,使用GraphQL語法來建構查詢。
  • 了解如何查詢內容片段和單一內容片段清單。
  • 了解如何篩選及要求特定資料屬性。
  • 了解如何查詢內容片段的變異。
  • 了解如何加入多個內容片段模型的查詢

安裝GraphiQL工具

GraphiQL IDE是開發工具,僅在開發或本地實例等較低級別環境中需要。 因此,AEM專案中不包含此套件,而是可臨機安裝的個別套件。

  1. 導覽至​Software Distribution Portal > AEM as aCloud Service

  2. 搜索「GraphiQL」(請務必在​GraphiQL​中包含​i

  3. 下載最新​GraphiQL內容包v.x.x.x

    下載GraphiQL包

    zip檔案是可直接安裝的AEM套件。

  4. 從​AEM Start​菜單導航至​Tools > Deployment > Packages

  5. 按一下「上傳套件」 ,然後選擇上一步驟中下載的套件。 按一下​Install​以安裝軟體包。

    安裝GraphiQL包

查詢內容片段清單

常見的需求是查詢多個內容片段。

  1. 導航到GraphiQL IDE(http://localhost:4502/content/graphiql.html)。

  2. 將下列查詢貼到左側面板(在備注清單下):

    {
      contributorList {
        items {
            _path
          }
      }
    }
    
  3. 按頂部菜單中的​播放​按鈕以執行查詢。 您應該會看到上一章中「貢獻者」內容片段的結果:

    貢獻者清單結果

  4. 將游標置於_path文本下,然後輸入​CTRL+空格​以觸發代碼提示。 將fullNameoccupation新增至查詢。

    使用程式碼編輯更新查詢

  5. 按​Play​按鈕再次執行查詢,您應該會看到結果包含fullNameoccupation的其他屬性。

    全名和職業結果

    fullName 和屬 occupation 性簡單。從定義內容片段模型章節回想,fullNameoccupation是定義各個欄位的​屬性名稱​時使用的值。

  6. pictureReference 和代 biographyText 表更複雜的欄位。使用下列內容更新查詢,以傳回pictureReferencebiographyText欄位的相關資料。

    {
    contributorList {
        items {
          _path
          fullName
          occupation
          biographyText {
            html
          }
          pictureReference {
            ... on ImageRef {
                _path
                width
                height
                }
            }
        }
      }
    }
    

    biographyText 是多行文字欄位,GraphQL API可讓我們為結果選擇各種格式, html例如 markdownjsonplaintext

    pictureReference 是內容參考,且應為影像,因此會使用內 ImageRef 建物件。這可讓我們要求有關要參考之影像的其他資料,例如widthheight

  7. 接下來,嘗試查詢​Adventures​清單。 執行下列查詢:

    {
      adventureList {
        items {
          adventureTitle
          adventureType
          adventurePrimaryImage {
            ...on ImageRef {
              _path
              mimeType
            }
          }
        }
      }
    }
    

    您應該會看到傳回的​Adventures​清單。 您可以在查詢中新增其他欄位,以進行實驗。

篩選內容片段清單

接下來,我們將探討如何根據屬性值將結果篩選為內容片段的子集。

  1. 在GraphiQL UI中輸入以下查詢:

    {
    contributorList(filter: {
      occupation: {
        _expressions: {
          value: "Photographer"
          }
        }
      }) {
        items {
          _path
          fullName
          occupation
        }
      }
    }
    

    上述查詢會對系統中的所有貢獻者執行搜尋。 新增的篩選器至查詢的開頭,將對occupation欄位和字串"Photographer"執行比較。

  2. 執行查詢時,應該只傳回單一​貢獻者

  3. 輸入以下查詢以查詢​Adventures​清單,其中adventureActivity為​not​等於​"Surfing":

    {
      adventureList(filter: {
        adventureActivity: {
            _expressions: {
                _operator: EQUALS_NOT
                value: "Surfing"
            }
        }
    }) {
        items {
        _path
        adventureTitle
        adventureActivity
        }
      }
    }
    
  4. 執行查詢並檢查結果。 請注意,所有結果中均未包含等於​"Surfing"​的adventureType

篩選和建立複雜查詢有許多其他選項,以上只是幾個範例。

查詢單一內容片段

您也可以直接查詢單一內容片段。 AEM中的內容以分層方式儲存,而片段的唯一識別碼基於片段的路徑。 如果目標是傳回關於單一片段的資料,建議您使用路徑並直接查詢模型。 使用此語法表示查詢複雜度會非常低,且會產生更快的結果。

  1. 在GraphiQL編輯器中輸入以下查詢:

    {
     contributorByPath(_path: "/content/dam/wknd/en/contributors/stacey-roswells") {
        item {
          _path
          fullName
          biographyText {
            html
          }
        }
      }
    }
    
  2. 執行查詢並觀察​Stacey Roswells​片段的單一結果是否已傳回。

    在上一個練習中,您使用篩選器來縮小結果清單。 您可以使用類似的語法來依路徑篩選,但基於效能原因,建議使用上述語法。

  3. 回想一下製作內容片段章節中,為​Stacey Roswells​建立了​Summary​變異。 更新查詢以傳回​Summary​變數:

    {
    contributorByPath
    (
        _path: "/content/dam/wknd/en/contributors/stacey-roswells"
        variation: "summary"
    ) {
        item {
          _path
          fullName
          biographyText {
            html
          }
        }
      }
    }
    

    即使變體名為​Summary,變體仍以小寫形式保存,因此會使用summary

  4. 執行查詢並觀察biography欄位包含的html結果要短得多。

查詢多個內容片段模型

您也可以將個別查詢合併為單一查詢。 這對於將為應用程式提供電源所需的HTTP請求數減到最少非常有用。 例如,應用程式的​首頁​檢視可根據​兩個​不同的內容片段模型來顯示內容。 我們不必執行​兩個​個別的查詢,而是可以將查詢合併為單一請求。

  1. 在GraphiQL編輯器中輸入以下查詢:

    {
      adventureList {
        items {
          _path
          adventureTitle
        }
      }
      contributorList {
        items {
          _path
          fullName
        }
      }
    }
    
  2. 執行查詢並觀察結果集包含​Adventures​和​Contributors​的資料:

{
  "data": {
    "adventureList": {
      "items": [
        {
          "_path": "/content/dam/wknd/en/adventures/bali-surf-camp/bali-surf-camp",
          "adventureTitle": "Bali Surf Camp"
        },
        {
          "_path": "/content/dam/wknd/en/adventures/beervana-portland/beervana-in-portland",
          "adventureTitle": "Beervana in Portland"
        },
        ...
      ]
    },
    "contributorList": {
      "items": [
        {
          "_path": "/content/dam/wknd/en/contributors/jacob-wester",
          "fullName": "Jacob Wester"
        },
        {
          "_path": "/content/dam/wknd/en/contributors/stacey-roswells",
          "fullName": "Stacey Roswells"
        }
      ]
    }
  }
}

其他資源

如需更多GraphQL查詢的範例,請參閱:學習如何搭配AEM使用GraphQL — 範例內容與查詢

恭喜!

恭喜,您剛剛建立並執行了多個GraphQL查詢!

後續步驟

在下一章從React應用程式查詢AEM中,您將探索外部應用程式如何查詢AEM GraphQL端點。 修改範例WKND GraphQL React應用程式以新增篩選GraphQL查詢的外部應用程式,可讓應用程式的使用者依活動篩選歷險。 您也將了解一些基本的錯誤處理。

本頁內容