持久 GraphQL 查询 persisted-graphql-queries

持久查询是创建并存储在 Adobe Experience Manager (AEM) as a Cloud Service 服务器上的 GraphQL 查询。它们可以经客户端应用程序以 GET 请求方式请求。GET 请求的响应可以在 Dispatcher 和 CDN 层缓存，最终改进请求客户端应用程序的性能。这与标准的 GraphQL 查询不同，后者使用 POST 请求执行，而在 POST 请求中，无法轻松缓存响应。

GraphiQL IDE 在 AEM 中可供您开发、测试和持久您的 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下。要调用 Persisted 查询 activity=Camping，请求如下所示：

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

UTF-8 编码 %3B 是 ; 的，%3D 是 = 的编码。查询变量和任何特殊字符必须正确编码才能执行持久查询。

使用查询变量 - 最佳实践 query-variables-best-practices

在查询中使用变量时，应遵循一些最佳做法：

正在缓存您的持久查询 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} }'

可以在创建时（PUT）或以后（例如，通过 POST 请求）设置 cache-control。在创建持久查询时，缓存控制是可选的，因为 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 创作服务上创建持久查询，然后将其发布（复制）到 AEM 发布服务。通常，持久查询会在本地或开发环境等较低环境中创建和测试。然后，有必要将持久查询提升到更高级别的环境，最终在生产 AEM 发布环境中提供，以供客户端应用程序使用。

持久查询包

可以将持久查询构建在 AEM 程序包中。然后，可以在不同的环境中下载和安装 AEM 包。AEM 包也可以从 AEM 创作环境复制到 AEM 发布环境。

要创建包：

生成包后，您可以：