持久 GraphQL 查询 persisted-queries-caching

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

GraphiQL IDE 在 AEM 中可供您开发、测试和持久您的 GraphQL 查询,然后再转移到您的生产环境。对于需要自定义的情况(例如,当自定义缓存时)可使用该 API;请参阅在如何使 GraphQL 查询持久中提供的 cURL 示例。

持久查询及端点 persisted-queries-and-endpoints

持久查询必须始终使用与相应 Sites 配置相关的端点,因此它们可以使用以下项之一或全部:

  • 全球配置和端点
    查询具有对所有内容片段模型的访问权限。
  • 特定 Sites 配置和端点
    为特定 Sites 配置创建持久查询需要对应的 Sites 配置特定的端点(用于提供对相关内容片段模型的访问权限)。
    例如,要创建特定于 WKND Sites 配置的持久查询,必须预先创建对应的 WKND 特定的端点。
NOTE
有关更多详细信息,请参阅在配置浏览器中启用内容片段功能
对于适当的 Sites 配置,需要启用 GraphQL 持久查询

例如,如果存在名为 my-query 的特定查询,使用来自 Sites 配置 my-conf 的模型 my-model

  • 您可以使用 my-conf 特定的端点创建查询,然后查询将保存如下:
    /conf/my-conf/settings/graphql/persistentQueries/my-query
  • 您可以使用 global 端点创建相同的查询,但然后查询将保存如下:
    /conf/global/settings/graphql/persistentQueries/my-query
NOTE
这里有两种不同的查询,保存在不同的路径中。
它们只是正好使用了相同的模型,但通过不同的端点。

如何使 GraphQL 查询持久 how-to-persist-query

建议先在 AEM 作者环境中保留查询,然后将查询转移到 AEM 发布环境中,供应用程序使用。

有多种持久查询的方法,包括:

GraphiQL IDE 是 首选 ​保留查询的方法。使用 cURL 命令行工具使给定的查询持久:

  1. 使用 PUT 操作将查询放入新端点 URL /graphql/persist.json/<config>/<persisted-label> 来准备查询。

    例如,创建持久查询:

    code language-shell
    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
        -d \
    '{
      articleList {
        items{
            _path
            author
            main {
                json
            }
        }
      }
    }'
    
  2. 此时,检查响应。

    例如,检查是否成功:

    code language-json
    {
      "action": "create",
      "configurationName": "wknd",
      "name": "plain-article-query",
      "shortPath": "/wknd/plain-article-query",
      "path": "/conf/wknd/settings/graphql/persistentQueries/plain-article-query"
    }
    
  3. 然后,您可以通过对 URL /graphql/execute.json/<shortPath> 执行 GET 操作来请求持久查询。

    例如,使用持久查询:

    code language-shell
    $ curl -X GET \
        http://localhost:4502/graphql/execute.json/wknd/plain-article-query
    
  4. 通过将持久查询 POST 到已经存在的查询路径来更新持久查询。

    例如,使用持久查询:

    code language-shell
    $ curl -X POST \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query" \
        -d \
    '{
      articleList {
        items{
            _path
            author
            main {
                json
            }
          referencearticle {
            _path
          }
        }
      }
    }'
    
  5. 创建打包的简单查询。

    例如:

    code language-shell
    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-wrapped" \
        -d \
    '{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }"}'
    
  6. 使用缓存控制创建打包的简单查询。

    例如:

    code language-shell
    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-max-age" \
        -d \
    '{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }", "cache-control": { "max-age": 300 }}'
    
  7. 使用参数创建持久查询:

    例如:

    code language-shell
    $ curl -X PUT \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/persist.json/wknd/plain-article-query-parameters" \
        -d \
    'query GetAsGraphqlModelTestByPath($apath: String!, $withReference: Boolean = true) {
      articleByPath(_path: $apath) {
        item {
          _path
            author
            main {
            plaintext
            }
            referencearticle @include(if: $withReference) {
            _path
            }
          }
        }
      }'
    

如何执行持久查询 execute-persisted-query

要执行持久查询,客户端应用程序使用以下语法发出 GET 请求:

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

其中 PERSISTENT_PATH 是保存持久查询的缩略路径。

  1. 例如,wknd 是配置名称,plain-article-query 为持久查询的名称。要执行查询:

    code language-shell
    $ curl -X GET \
        https://localhost:4502/graphql/execute.json/wknd/plain-article-query
    
  2. 使用参数执行查询。

    note note
    NOTE
    执行持久查询时,必须对查询变量和值进行正确地编码

    例如:

    code language-bash
    $ curl -X GET \
        "https://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters%3Bapath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fmagazine%2Falaska-adventure%2Falaskan-adventures%3BwithReference%3Dfalse
    

    请参阅使用查询变量以了解更多详细信息。

使用查询变量 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

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

正在缓存您的持久查询 caching-persisted-queries

建议使用持久查询,因为可在 Dispatcher 和内容交付网络 (CDN) 层缓存此类查询,最终提高发出请求的客户端应用程序的性能。

默认情况下,AEM 将根据生存时间 (TTL) 定义使缓存失效。可通过以下参数定义这些 TTL。可通过多种方式访问这些参数,其名称因所使用的机制而异:

缓存类型
HTTP 标头
cURL
OSGi 配置
浏览器
max-age
cache-control : max-age
cacheControlMaxAge
CDN
s-maxage
surrogate-control : max-age
surrogateControlMaxAge
CDN
stale-while-revalidate
surrogate-control : stale-while-revalidate
surrogateControlStaleWhileRevalidate
CDN
stale-if-error
surrogate-control : stale-if-error
surrogateControlStaleIfError

创作实例 author-instances

创作实例的默认值为:

  • max-age : 60
  • s-maxage : 60
  • stale-while-revalidate : 86400
  • stale-if-error : 86400

这些值:

  • 无法用OSGi配置覆盖
  • 可由使用cURL定义HTTP标头设置的请求覆盖;它应包含适用于cache-control和/或surrogate-control的设置;例如,请参阅在持久查询级别管理缓存

发布实例 publish-instances

发布实例的默认值为:

  • max-age : 60
  • s-maxage : 7200
  • stale-while-revalidate : 86400
  • stale-if-error : 86400

这些值可被覆盖:

在持久查询级别管理缓存 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 查询持久

使用 OSGi 配置管理缓存 cache-osgi-configration

要全局管理缓存,您可以为​ 持久查询服务配置 ​配置OSGi设置。 否则,此OSGi配置对发布实例🔗使用默认值。

NOTE
OSGi 配置仅适用于发布实例。创作实例上存在该配置,但忽略了它。

为应用程序使用的查询 URL 编码 encoding-query-url

对于应用程序,在构建查询变量时使用的任何特殊字符(即分号 (;)、等号 (=)、斜杠 /)才能使用相应的 UTF-8 编码。

例如:

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

URL 可以划分为以下部分:

URL 部分
描述
/graphql/execute.json
持久查询端点
/wknd/adventure-by-path
持久查询路径
%3B
; 的编码
adventurePath
查询变量
%3D
= 的编码
%2F
/ 的编码
%2Fcontent%2Fdam...
内容片段的编码路径

在纯文本中,请求 URI 如下所示:

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

要在客户端应用程序中使用持久查询,应使用 AEM headless 客户端 SDK JavaScriptJavaNodeJS。Headless 客户端 SDK 将自动在请求中正确编码任何查询变量。

正在将持久查询转移到生产环境 transfer-persisted-query-production

应始终在 AEM 创作服务上创建持久查询,然后将其发布(复制)到 AEM 发布服务。通常,持久查询会在本地或开发环境等较低环境中创建和测试。然后,有必要将持久查询提升到更高级别的环境,最终在生产 AEM 发布环境中提供,以供客户端应用程序使用。

持久查询包

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

要创建包:

  1. 导航到​ 工具 > 部署 >
  2. 通过点按​ 创建包 ​创建包。 这将打开一个用于定义包的对话框。
  3. 在包定义对话框中,在​ 常规 ​下输入​ 名称,如“wknd-persistent-queries”。
  4. 输入版本号,如“1.0”。
  5. 在​ 过滤器 ​下添加新的​ 过滤器。使用路径查找器选择 persistentQueries 文件夹。例如,对于wknd配置,完整路径将为/conf/wknd/settings/graphql/persistentQueries
  6. 选择​ 保存 ​以保存新的包定义并关闭对话框。
  7. 在新创建的包定义中选择​ 生成 ​按钮。

生成包后,您可以:

  • 下载 包,并在其他环境上重新上传。
  • 通过点击​ 更多 > 复制 ​来​ 复制 ​包。这会将包复制到连接的 AEM 发布环境。
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2