지속 GraphQL 쿼리 persisted-graphql-queries

지속 쿼리는 Adobe Experience Manager(AEM) as a Cloud Service 서버에서 생성 및 저장되는 GraphQL 쿼리입니다. 클라이언트 애플리케이션에서 GET 요청을 사용하여 요청할 수 있습니다. GET 요청의 응답은 Dispatcher 및 CDN 계층에서 캐시될 수 있으므로 궁극적으로 요청하는 클라이언트 애플리케이션의 성능이 향상됩니다. 이 경우 응답을 쉽게 캐시할 수 없는 POST 요청을 사용하여 실행되는 표준 GraphQL 쿼리와는 다릅니다.

프로덕션 환경으로 이전하기 전에 GraphQL 쿼리를 개발, 테스트 및 지속할 수 있도록 GraphiQL IDE가 AEM에 제공됩니다. 맞춤화가 필요한 경우(예: 캐시를 사용자 정의하는 경우) API를 사용할 수 있습니다. GraphQL 쿼리를 지속하는 방법에 제시된 cURL 예제를 참조하십시오.

지속 쿼리 및 엔드포인트 persisted-queries-and-endpoints

지속 쿼리는 항상 적절한 Sites 구성과 관련된 엔드포인트를 사용해야 합니다. 따라서 다음 중 하나 또는 둘 다를 사용할 수 있습니다.

예를 들어 Sites 구성 my-conf의 모델 my-model을 사용하는 my-query라는 특정 쿼리가 있는 경우:

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

쿼리에서 변수를 사용할 때 따라야 할 몇 가지 모범 사례가 있습니다.

지속 쿼리 캐싱 caching-persisted-queries

지속 쿼리는 Dispatcher 및 CDN(Content Delivery Network) 계층에서 캐시될 수 있어 궁극적으로 요청하는 클라이언트 애플리케이션의 성능이 향상되므로 이를 사용하는 것이 좋습니다.

기본적으로 AEM은 TTL(Time To Live) 정의에 따라 캐시를 무효화합니다. 이러한 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 작성자 서비스에서 만든 다음 AEM 게시 서비스에 게시(복제)해야 합니다. 지속 쿼리는 종종 로컬 또는 개발 환경과 같은 하위 수준 환경에서 생성되고 테스트됩니다. 그런 다음 지속 쿼리를 더 높은 수준의 환경으로 승격하여 궁극적으로 클라이언트 애플리케이션이 사용할 수 있도록 프로덕션 AEM 게시 환경에서 사용할 수 있도록 해야 합니다.

패키지 지속 쿼리

지속 쿼리를 AEM 패키지에 빌드할 수 있습니다. 그런 다음 AEM 패키지를 다운로드하여 다른 환경에 설치할 수 있습니다. AEM 패키지를 AEM 작성자 환경에서 AEM 게시 환경으로 복제할 수도 있습니다.

패키지를 제작하려면 다음 작업을 수행하십시오.

패키지를 빌드하면 다음과 같은 작업을 수행할 수 있습니다.