持久 GraphQL 查询

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

注意

建议使用持久查询。 请参阅 GraphQL 查询最佳实践 (Dispatcher) 以了解详细信息和相关的 Dispatcher 配置。

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

持久查询及端点

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

  • 全球配置和端点
    查询具有对所有内容片段模型的访问权限。
  • 特定站点配置和端点
    为特定站点配置创建持久查询需要对应的站点配置特定的端点(用于提供对相关内容片段模型的访问权限)。
    例如,要创建特定于 WKND Sites 配置的持久查询,必须预先创建对应的 WKND 特定的端点。
注意

有关更多详细信息,请参阅在配置浏览器中启用内容片段功能

对于适当的 Sites 配置,需要启用 GraphQL 持久查询

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

  • 您可以使用 my-conf 特定的端点创建查询,然后查询将保存如下:
    /conf/my-conf/settings/graphql/persistentQueries/my-query
  • 您可以使用 global 端点创建相同的查询,但然后查询将保存如下:
    /conf/global/settings/graphql/persistentQueries/my-query
注意

这里有两种不同的查询,保存在不同的路径中。

它们只是正好使用了相同的模型,但通过不同的端点。

如何使 GraphQL 查询持久

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

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

GraphiQL IDE 是 首选​保留查询的方法。 使用 curl 命令行工具:

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

    例如,创建持久查询:

    $ 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. 此时,检查响应。

    例如,检查是否成功:

    {
      "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 操作来请求持久查询。

    例如,使用持久查询:

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

    例如,使用持久查询:

    $ 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. 创建打包的简单查询。

    例如:

    $ 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. 使用缓存控制创建打包的简单查询。

    例如:

    $ 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. 使用参数创建持久查询:

    例如:

    $ 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
            }
          }
        }
      }'
    

如何执行持久查询

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

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

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

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

    $ curl -X GET \
        https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query
    
  2. 使用参数执行查询。

    注意

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

    例如:

    $ curl -X GET \
        "https://publish-p123-e456.adobeaemcloud.com/graphql/execute.json/wknd/plain-article-query-parameters%3Bapath%3D%2Fcontent%2Fdam%2Fwknd%2Fen%2Fmagazine%2Falaska-adventure%2Falaskan-adventures%3BwithReference%3Dfalse
    

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

使用查询变量

查询变量可与持久查询一起使用。 使用变量名称和值将查询变量附加到以分号 (;) 为前缀的请求中。多个变量以分号分隔。

该模式如下所示:

<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= 的编码。 查询变量和任何特殊字符必须正确编码才能执行持久查询。

正在缓存您的持久查询

建议使用持久查询,因为它们可以缓存在调度程序和 CDN 层,最终提高请求客户端应用程序的性能。

默认情况下,AEM 将根据默认生存时间 (TTL) 使内容投放网络 (CDN) 缓存失效。

此值设置为:

  • 7200 秒是 Dispatcher 和 CDN 的默认 TTL;也称为​共享缓存
    • 默认:s-maxage=7200
  • 60 是客户端(例如浏览器)的默认 TTL
    • 默认:maxage=60

如果要更改 GraphLQ 查询的 TTL,则查询必须是:

在 GraphQL 中管理 HTTP 缓存标头

GraphiQL IDE – 请参阅“保存持久查询”

从 API 管理缓存

这涉及到在命令行界面中使用 CURL 将查询发布到 AEM。

例如:

curl -X PUT \
    -H 'authorization: Basic YWRtaW46YWRtaW4=' \
    -H "Content-Type: application/json" \
    "https://publish-p123-e456.adobeaemcloud.com/graphql/persist.json/wknd/plain-article-query-max-age" \
    -d \
'{ "query": "{articleList { items { _path author main { json } referencearticle { _path } } } }", "cache-control": { "max-age": 300 }}'

可以在创建时(PUT)或以后(例如,通过 POST 请求)设置 cache-control。在创建持久查询时,缓存控制是可选的,因为 AEM 可以提供默认值。有关使用 CURL 持久查询的示例,请参见如何持久 GraphQL 查询

为应用程序使用的查询 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 可以划分为以下部分:

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 将自动在请求中正确编码任何查询变量。

正在将持久查询转移到生产环境

应始终在 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 发布环境。

在此页面上