探索GraphQL API

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

在本章中,我們將探索一些常見的GraphQL查詢,以使用名為GraphiQL的IDE收集內容。 GraphiQL IDE允許您快速測試和細化返回的查詢和資料。 GraphiQL還提供了對文檔的輕鬆訪問,使您能夠輕鬆瞭解和瞭解可用的方法。

必備條件

本教學課程包含多部分,假設編寫內容片段中概述的步驟已完成。

目標

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

安裝GraphiQL工具

GraphiQL IDE是開發工具,僅在低級環境(如開發或本地實例)上需要。 因此,它不包含在AEM專案中,而是以個別套件形式提供,可以臨機安裝。

  1. 導覽至​軟體散發入口網站 > AEM作為雲端服務

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

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

    下載GraphiQL軟體包

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

  4. 從​AEM Start​功能表導覽至​Tools > Deployment > Packages

  5. 按一下​上傳包​並選擇在上一步中下載的包。 按一下​Install​安裝軟體包。

    安裝GraphiQL軟體包

查詢內容片段清單

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

  1. 導航到位於http://localhost:4502/content/graphiql.html的GraphiQL IDE。

  2. 將下列查詢貼入左側面板(在注釋清單下方):

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

    參與者清單結果

  4. 將游標置於_path文字下方,然後輸入​CTRL+Space​以觸發程式碼提示。 將fullNameoccupation新增至查詢。

    使用程式碼編輯來更新查詢

  5. 按​播放​按鈕再次執行查詢,您應看到結果包括fullNameoccupation的其他屬性。

    全名和職業成績

    fullNameoccupation 於簡單屬性。從定義內容片段模型一章中,請回顧fullNameoccupation是定義各個欄位的​屬性名稱​時使用的值。

  6. pictureReference 並且 biographyText 表示更複雜的欄位。使用下列更新查詢,以傳回有關pictureReferencebiographyText欄位的資料。

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

    biographyText 是多行文字欄位,而GraphQL API可讓我們為結果選擇多種格 htmlmarkdown, json 例如 plaintext

    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. 執行查詢時,預期只會傳回單一​Contributor

  3. 輸入以下查詢以查詢​Adventures​的清單,其中adventureActivitynot​等於​"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​變化:

    {
    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查詢的更多示例,請參見:學習搭配使用GraphQL與AEM —— 範例內容與查詢

恭喜!

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

後續步驟

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

本頁內容