持續性 GraphQL 查詢 persisted-graphql-queries

持續性查詢是在 Adobe Experience Manager (AEM) as a Cloud Service 伺服器上建立和儲存的 GraphQL 查詢。用戶端應用程式可以透過 GET 要求來要求它們。GET 要求的回應可以在 Dispatcher 和 CDN 層快取，最終提高發出要求之用戶端應用程式的效能。這與標準的 GraphQL 查詢不同，後者使用 POST 要求執行，其回應無法輕鬆快取。

AEM 有提供 GraphiQL IDE，可讓您在傳送到生產環境之前，開發、測試和保留您的 GraphQL 查詢。如果需要自訂 (例如自訂快取時)，您可以使用 API，請參閱如何保留 GraphQL 查詢中提供的 cURL 範例。

持續性查詢和端點 persisted-queries-and-endpoints

持續性查詢必須一律使用與適當的 Sites 設定相關的端點；所以可以使用以下其中之一，或兩者都使用：

例如，如果有一個名為 my-query 的特定查詢，它使用 Sites 設定 my-conf 中的模型 my-model：

如何保留 GraphQL 查詢 how-to-persist-query

建議最初在 AEM 編寫環境中保留查詢，然後將查詢傳輸到生產 AEM 發佈環境，以供應用程式使用。

有多種保留查詢的方法，包括：

GraphiQL IDE 是保留查詢的​ 首選 ​方法。若要使用 cURL 命令列工具保留特定查詢：

如何執行持續性查詢 execute-persisted-query

若要執行持續性查詢，用戶端應用程式使用以下語法發出 GET 要求：

GET <AEM_HOST>/graphql/execute.json/<PERSISTENT_PATH>

其中 PERSISTENT_PATH 是持續性查詢儲存所在的縮短路徑。

使用查詢變數 query-variables

查詢變數可以與持續性查詢一起使用。查詢變數使用變數名稱和值附加到開頭為分號 (;) 的要求。多個變數會用分號分隔。

模式如下所示：

<AEM_HOST>/graphql/execute.json/<PERSISTENT_QUERY_PATH>;variable1=value1;variable2=value2

例如，以下查詢包含一個變數 activity 以根據活動值篩選清單：

query getAdventuresByActivity($activity: String!) {
      adventureList (filter: {
        adventureActivity: {
          _expressions: [
            {
              value: $activity
            }
          ]
        }
      }){
        items {
          _path
        adventureTitle
        adventurePrice
        adventureTripLength
      }
    }
  }

此查詢可以保留在路徑 wknd/adventures-by-activity 下。若要在 activity=Camping 呼叫持續性查詢，要求將如下所示：

<AEM_HOST>/graphql/execute.json/wknd/adventures-by-activity%3Bactivity%3DCamping

%3B 是 ; 的 UTF-8 編碼，%3D 是 = 的編碼。查詢變數和任何特殊字元必須正確編碼才能執行持續性查詢。

使用查詢變數 - 最佳做法 query-variables-best-practices

在查詢中使用變數時，應遵循以下幾個最佳做法：

當 Dispatcher 啟用 CACHE_GRAPHQL_PERSISTED_QUERIES 時，則值中包含/ 或 \ 字元的參數會在 Dispatcher 層級上進行兩次編碼。為了避免這種情況：

快取持續性查詢 caching-persisted-queries

建議使用持續性查詢，因為可以在 Dispatcher 和內容傳遞網路 (CDN) 層進行快取，最終提升發出要求的用戶端應用程式效能。

依預設，AEM 將根據存留時間 (TTL) 定義使快取失效。這些 TTL 可以依照以下參數定義。這些參數可以透過各種方式存取，根據所使用的機制，名稱會有所不同：

編寫執行個體 author-instances

對於編寫執行個體，預設值為：

這些：

發佈執行個體 publish-instances

對於發佈執行個體，預設值為：

這些可以被覆寫：

管理 GraphiQL IDE 中的 HTTP 快取標頭 http-cache-headers-graphiql-ide

GraphiQL IDE - 請參閱儲存持續性查詢

在持續性查詢層級管理快取 cache-persisted-query-level

這涉及在命令列介面中使用 cURL 將查詢發佈到 AEM。

對於 PUT (建立) 方法的範例：

curl -u admin:admin -X PUT \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

對於 POST (更新) 方法的範例：

curl -u admin:admin -X POST \
--url "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
--header "Content-Type: application/json" \
--data '{ "query": "{articleList { items { _path author } } }", "cache-control": { "max-age": 300 }, "surrogate-control": {"max-age":600, "stale-while-revalidate":1000, "stale-if-error":1000} }'

cache-control 可以在建立時 (PUT) 或稍後 (例如透過 POST 要求) 設定。建立持續性查詢時，快取控制是選用的，因為 AEM 可以提供預設值。如需有關如何使用 cURL 保留查詢的範例，請參閱如何保留 GraphQL 查詢。

使用 Cloud Manager 變數管理快取 cache-cloud-manager-variables

Cloud Manager 環境變數可以使用 Cloud Manager 來定義以定義所需的值：

使用 OSGi 設定管理快取 cache-osgi-configration

若要全域管理快取，您可以為​ 持續性查詢服務設定進行 OSGi 設定。

發佈執行個體的預設 OSGi 設定：

設定查詢回應代碼 configuring-query-response-code

預設情況下，PersistedQueryServlet 執行查詢時，會傳送 200 回應，無論實際結果如何。

您可以設定 OSGi 設定 (針對​ 持續性查詢服務設定)，以決定持續性查詢中出現錯誤時，/execute.json/persisted-query 端點是否傳回更詳細的狀態代碼。

欄位 Respond with application/graphql-response+json(responseContentTypeGraphQLResponseJson) 可依要求定義：

編碼查詢 URL 以供應用程式使用 encoding-query-url

為供應用程式使用，建構查詢變數時使用的任何特殊字元 (即分號 (;)、等號 (=)、斜線 /) 必須是轉換為使用相應的 UTF-8 編碼。

例如：

curl -X GET \ "https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/adventure-by-path%3BadventurePath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fadventures%2Fbali-surf-camp%2Fbali-surf-camp"

URL 可以分解成以下幾個部分：

在純文字中，要求 URI 如下所示：

/graphql/execute.json/wknd/adventure-by-path;adventurePath=/content/dam/wknd/en/adventures/bali-surf-camp/bali-surf-camp

若要在用戶端應用程式中使用持續性查詢，AEM Headless 用戶端 SDK 應該用於 JavaScript、Java 或 NodeJS。Headless 用戶端 SDK 會自動將要求中的任何查詢變數適當地編碼。

將持續性查詢轉移到您的生產環境 transfer-persisted-query-production

持續性查詢應一律建立在 AEM Author 服務上，然後發佈 (複製) 到 AEM Publish 服務。通常，持續性查詢是在低層環境 (例如本機或開發環境) 中建立和測試的。然後，必須將持續性查詢提升到高層環境，最終使它們能在生產 AEM Publish 環境中供用戶端應用程式使用。

封裝持續性查詢

持續性查詢可以內建在 AEM 套件 中。然後，AEM 套件可以下載和安裝在不同的環境中。AEM 套件也可以從 AEM 編寫環境複製到 AEM 發佈環境。

若要建立套件：

建置套件後，您可以：