永續GraphQL查詢

永續查詢是儲存在Adobe Experience Manager(AEM)伺服器上的查詢。 客戶端可以發送具有查詢名稱的HTTPGET請求以執行該請求。 這種方法的好處是可快取。 雖然客戶端GraphQL查詢也可以使用無法快取的HTTPPOST請求執行，但永續查詢可以通過HTTP快取或CDN進行快取，從而提高效能。 永續查詢允許您簡化請求並提高安全性，因為您的查詢已封裝在伺服器上，而AEM且管理員完全控制了這些查詢。 在使用AEMGraphQL API時，最好使用永續查詢，並強烈建議使用它。

在上一章中，您探索了一些高級GraphQL查詢以收集WKND應用的資料。 在本章中，您將將這些查詢保留AEM到、更新它們，並瞭解如何對保留的查詢使用快取控制。

必備條件

本文檔是多部分教程的一部分。 在繼續本章之前，請確保已完成前幾章。

本教程使用 郵遞員 執行HTTP請求。 在開始本章之前，請確保您已註冊到服務。 本教程還需要Postman應用的工作知識，如如何設定集合、建立變數和發出請求。 請參閱上 構建請求 和 發送您的第一個請求 的子菜單。

在本章中，將上一章中探討的查詢保留為AEM。 您可以下載帶有這些標準GraphQL查詢的文本檔案 這裡 供參考。

目標

在本章中，瞭解如何：

  • 具有參數的Persist GraphQL查詢
  • 更新保留的查詢
  • 對永續查詢使用快取控制參數

永續查詢概述

此視頻概述了如何保留GraphQL查詢、更新查詢和使用快取控制。

啟用保留查詢

首先，確保為實例中的WKND站點項目啟用永續查AEM詢。

  1. 導航到 工具 > 常規 > 配置瀏覽器。

  2. 選擇 WKND站點，然後選擇 屬性 的子菜單。

    設定瀏覽器

    在「配置屬性」頁上，您應看到 GraphQL持久查詢 權限已啟用。

    組態屬性

導入郵遞員集合

為了便於學習本教程，提供了郵遞員收藏。 或者，命令行工具如 curl 可以用。

  1. 下載並安裝 郵遞員

  2. 下載 AdvancedConceptsofAEMHeadless.postman_collection.json

  3. 開啟郵遞員應用

  4. 選擇 檔案 > 導入 > 上載檔案 選擇 AdvancedConceptsofAEMHeadless.postman_collection.json 的子菜單。

    導入郵遞員集合

驗證

對作者實例發送查詢需AEM要身份驗證。 本教程基於AEMas a Cloud Service環境，並使用帶開發令牌的Bearer身份驗證。 要配置郵遞員集合的身份驗證，請執行以下步驟：

  1. 要獲取開發令牌，請導航至雲開發者控制台，開啟 整合 ，然後選擇 獲取本地開發令牌。

    獲取開發令牌

  2. 在郵遞員收藏中，導航至 驗證 頁籤 持有者令牌 的 類型 下拉菜單。

    在郵遞員中配置身份驗證

  3. 將開發令牌輸入 令牌 的子菜單。 您可以通過變數傳遞令牌，如下一節所述。

    在郵遞員中添加開發令牌

變數

您可以通過郵遞員集合中的變數傳遞諸如身份驗證令牌和URI元件等值，以簡化流程。 在本教程中，請使用以下步驟建立變數：

  1. 導航到 變數 頁籤，並建立以下變數：

    變數 值
    AEM_SCHEME https
    AEM_AUTH_TOKEN （您的開發令牌）
    AEM_HOST (實例的主機AEM名)
    AEM_PROJECT wknd

  2. 您還可以為要建立的每個永續查詢添加變數。 對於本教程，請保留以下查詢： getAdventureAdministratorDetailsByAdministratorName。 getTeamByAdventurePath。 getLocationDetailsByLocationPath。 getTeamMembersByAdventurePath。 getLocationPathByAdventurePath, getTeamLocationByLocationPath。

    建立以下變數：

    • AEM_GET_ADVENTURE_ADMINISTRATOR_DETAILS_BY_ADMINISTRATOR_NAME : adventure-administrator-details-by-administrator-name
    • AEM_GET_ADVENTURE_ADMINISTRATOR_DETAILS_BY_ADMINISTRATOR_NAME : adventure-administrator-details-by-administrator-name
    • AEM_GET_TEAM_LOCATION_BY_LOCATION_PATH : team-location-by-location-path
    • AEM_GET_TEAM_MEMBERS_BY_ADVENTURE_PATH : team-members-by-adventure-path
    • AEM_GET_LOCATION_DETAILS_BY_LOCATION_PATH : location-details-by-location-path
    • AEM_GET_LOCATION_PATH_BY_ADVENTURE_PATH : location-path-by-adventure-path
    • AEM_GET_TEAM_BY_ADVENTURE_PATH : team-by-adventure-path

    完成後， 變數 的子菜單。

    郵遞員中的「變數」頁籤

具有參數的Persist GraphQL查詢

在 無AEM頭和GraphQL視頻系列，您學習了如何建立永續GraphQL查詢。 在本節中，讓我們使用參數保持並執行GraphQL查詢。

建立永續查詢

對於本示例，讓我們堅持 getAdventureAdministratorDetailsByAdministratorName 查詢。

注意

HTTPPUT方法用於建立永續查詢，而HTTPPOST方法用於更新該查詢。

  1. 首先，在郵遞員集合中添加新請求。 選擇HTTPPUT方法以建立永續查詢並使用以下請求URI:

    {{AEM_SCHEME}}://{{AEM_HOST}}/graphql/persist.json/{{AEM_PROJECT}}/{{AEM_GET_ADVENTURE_ADMINISTRATOR_DETAILS_BY_ADMINISTRATOR_NAME}}

    請注意，URI使用 /graphql/persist.json 操作。

  2. 貼上 getAdventureAdministratorDetailsByAdministratorName GraphQL查詢到請求主體。 請注意，它是帶變數的標準GraphQL查詢 name 需要 String。

    將GraphQL查詢貼上到請求正文中

  3. 執行請求。 您應收到以下響應：

    執行PUT請求

    您已成功建立名為 adventure-administrator-details-by-administrator-name。

執行永續查詢

讓我們執行您建立的永續查詢。

  1. 使用以下請求URI在郵遞員集合中建立新GET請求：

    {{AEM_SCHEME}}://{{AEM_HOST}}/graphql/execute.json/{{AEM_PROJECT}}/{{AEM_GET_ADVENTURE_ADMINISTRATOR_DETAILS_BY_ADMINISTRATOR_NAME}}

    請注意，請求URI現在包括 execute.json 操作。

    如果按原樣執行此請求，則會引發錯誤，因為查詢需要變數 name。 必須將此變數作為參數傳遞到請求URI中。

    執行GET錯誤

  2. 接下來，檢索名為Jacob Wester的管理員。 永續GraphQL查詢的參數必須與以前的URI元件分隔為 ; 並在將它們傳入請求URI之前進行編碼。 在瀏覽器控制台中執行以下命令：

    encodeURIComponent(";name=Jacob Wester")

    對URI參數進行編碼

  3. 從控制台複製結果，然後在請求URI的末尾以Postman形式貼上。 您應具有以下請求URI:

    {{AEM_SCHEME}}://{{AEM_HOST}}/graphql/execute.json/{{AEM_PROJECT}}/{{AEM_GET_ADVENTURE_ADMINISTRATOR_DETAILS_BY_ADMINISTRATOR_NAME}}%3Bname%3DJacob%20Wester

  4. 執行GET請求。 您應收到以下響應：

    對URI參數進行編碼

您現在已建立並執行帶參數的永續GraphQL查詢。

您可以按照上述步驟保留GraphQL查詢的其餘部分 文本檔案 使用在 本章開始。

滿 郵遞員收藏 也可用於下載和導入。

更新保留的查詢

使用PUT請求建立保留查詢時，必須使用POST請求更新現有的保留查詢。 在本教程中，讓我們更新名為 adventure-administrator-details-by-administrator-name 建立的 上一節。

  1. 複製上一節中用於PUT請求的頁籤。 在副本中，將HTTP方法更改為POST。

  2. 在GraphQL查詢中，讓我們刪除 plaintext 格式 administratorDetails 的子菜單。

    更新GraphQL查詢

  3. 執行請求。 您應得到以下響應：

    POST響應

您現在已更新 adventure-administrator-details-by-administrator-name 永續查詢。 在中始終更新GraphQL查詢AEM（如果進行更改）非常重要。

在永續查詢中傳遞快取控制參數

GraphQL APIAEM允許您向查詢添加快取控制參數以提高效能。

使用 getAllAdventureDetails 在上一章中建立的查詢。 查詢響應很大，控制其是有用的 age 在快取中。

此永續查詢稍後用於更新 客戶端應用程式。

  1. 在郵遞員集合中，建立新變數：

    AEM_GET_ALL_AT_ONCE: all-adventure-details

  2. 建立新PUT請求以保留此查詢。

  3. 在 身體 頁籤，選擇 生 資料類型。

    選擇原始資料類型

  4. 要在查詢中使用快取控制，您需要將查詢包裝在JSON結構中，並在末尾添加快取控制參數。 將以下查詢複製並貼上到請求正文中：

    {
"query": " query getAllAdventureDetails($fragmentPath: String!) { adventureByPath(_path: $fragmentPath){ item { _path adventureTitle adventureActivity adventureType adventurePrice adventureTripLength adventureGroupSize adventureDifficulty adventurePrice adventurePrimaryImage{ ...on ImageRef{ _path mimeType width height } } adventureDescription { html json } adventureItinerary { 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 } } } }",
"cache-control": { "max-age": 300 }
}
    注意

    包裝查詢不能包含換行符。

    您的請求現在應如下所示：

    PUT具有快取控制參數的請求

  5. 執行請求。 您應該得到的響應表明 all-adventure-details 已成功建立永續查詢。

    使用快取控制參數建立永續查詢

恭喜！

恭喜！ 您現在已學會了如何使用參數永續GraphQL查詢、更新永續查詢以及將快取控制參數用於永續查詢。

後續步驟

在 下一章，您將在WKND應用中實現永續查詢的請求。

雖然本教程是可選的，但請確保在真實生產環境中發佈所有內容。 有關中的「作者」和「發佈」環境的AEM回顧，請參閱 無AEM頭和GraphQL視頻系列。

本頁內容