콘텐츠 조각과 함께 사용하기 위한 AEM GraphQL API graphql-api-for-use-with-content-fragments

“…API용 쿼리 언어 및 기존 데이터로 이러한 쿼리를 수행하기 위한 런타임입니다. GraphQL은 API의 데이터에 대한 완전하고 이해하기 쉬운 설명을 제공합니다. 클라이언트가 필요로 하는 것을 정확히 요청할 수 있는 권한을 주고 시간이 지남에 따라 API를 더 쉽게 발전시킬 수 있으며 강력한 개발자 도구를 지원합니다.".

GraphQL.org를 참조하십시오.

“…유연한 API 계층을 위한 오픈 사양입니다. 기존 백엔드에 GraphQL을 추가하여 그 어느 때보다 빠르게 제품을 빌드할 수 있습니다…".

GraphQL 살펴보기를 참조하십시오.

"…2015년에 오픈 소스로 공개되기 전에 2012년 Facebook에서 내부적으로 개발한 데이터 쿼리 언어 및 사양입니다. 개발자 생산성을 높이고 전송되는 데이터 양을 최소화할 목적으로 REST 기반 아키텍처에 대한 대안을 제공합니다. GraphQL은 규모에 관계없이 수백 개의 조직에서 프로덕션에 사용됩니다.”

GraphQL Foundation을 참조하십시오.

graphql.org:

• GraphQL 소개

• GraphQL 사양

graphql.com:

• 튜토리얼

graphQL.org - Java

GitHub의 GraphQL Java™

쿼리

스키마 및 유형:

• 스키마는 콘텐츠 조각 모델을 기반으로 AEM에서 생성됩니다.
• 스키마를 사용하여 GraphQL은 AEM용 GraphQL 구현에 허용되는 유형 및 작업을 제공합니다.

필드

GraphQL 엔드포인트

• GraphQL 쿼리에 응답하고 GraphQL 스키마에 대한 액세스를 제공하는 AEM의 경로입니다.

• 자세한 내용은 GraphQL 엔드포인트 활성화를 참조하십시오.

단일 항목

항목 목록

게시 환경, 다음과 같은 작업을 수행하는 데 사용됨:

• JS 애플리케이션용 쿼리 데이터 (표준 사용 사례)

Author 환경, 다음과 같은 작업을 수행하는 데 사용됨:

• “콘텐츠 관리 목적”용 쿼리 데이터:

  • AEM의 GraphQL은 읽기 전용 API입니다.
  • REST API는 CR(u)D 작업에 사용할 수 있습니다.

귀하가 생성하는 필드입니다.

다양한 데이터 유형은 콘텐츠 조각 모델을 구성하는 방법을 기반으로 필드를 만드는 데 사용됩니다. 필드 이름은 데이터 형식 ​의 속성 이름 필드에서 가져옵니다.

• 사용자가 특정 데이터 형식을 구성할 수 있으므로 고려해야 하는 Render As 설정도 있습니다. 예를 들어 드롭다운에서 multifield을(를) 선택하여 여러 개의 한 줄 텍스트를 포함하도록 한 줄 텍스트 필드를 구성할 수 있습니다.

GraphQL for AEM에서도 여러 도우미 필드를 생성합니다.

이러한 필드는 콘텐츠 조각을 식별하거나 콘텐츠 조각에 대한 자세한 정보를 얻는 데 사용됩니다.

AEM용 GraphQL 확장의 세부사항

이 샘플 콘텐츠 및 구조를 사용하는 샘플 쿼리

• 그리고 샘플 쿼리에 사용하기 위해 준비된 샘플 콘텐츠 및 구조

WKND 프로젝트 기반 샘플 쿼리

필드 경로를 나타내는 쉼표로 구분된 값 목록입니다.

• 목록의 첫 번째 필드는 기본 정렬 순서를 정의합니다

  • 두 번째 필드는 기본 정렬 기준의 두 값이 동일한 경우 사용됩니다
  • 세 번째 필드는 처음 두 기준이 동일한 경우 사용됩니다.

• 점으로 구분된 표기법, 즉 field1.subfield.subfield 등입니다.

선택적 정렬 방향

• (ASC(오름차순) 또는 DESC(내림차순))이 포함되며, 기본값 ASC가 적용됩니다.
• 방향은 필드별로 지정할 수 있습니다. 즉, 한 필드는 오름차순으로 정렬하고 다른 필드는 내림차순으로 정렬할 수 있습니다(name, firstName DESC)

<conf.d/rewrites/base_rewrite.rules>

# Allow the dispatcher to be able to cache persisted queries - they need an extension for the cache file
RewriteCond %{REQUEST_URI} ^/graphql/execute.json
RewriteRule ^/(.*)$ /$1;.json [PT]

<conf.dispatcher.d/filters/ams_publish_filters.any>

# Allow GraphQL Persisted Queries & preflight requests
/0110 { /type "allow" /method '(GET|POST|OPTIONS)' /url "/graphql/execute.json*" }

Origin 헤더는 Dispatcher를 통해 AEM 게시로 전달되어서는 안 됩니다.

• clientheaders.any 파일을 확인하십시오.

대신 Dispatcher 수준에서 허용된 원본에 대해 CORS 요청을 평가해야 합니다. 또한 이 접근 방식을 사용하면 CORS 관련 헤더를 모든 경우에 한 곳에서 올바르게 설정할 수 있습니다.

• 이러한 구성은 vhost 파일에 추가해야 합니다. 예시 구성은 아래와 같으며, 간단하게 CORS 관련 부분만 제공되었습니다. 특정 사용 사례에 맞게 조정할 수 있습니다.

<VirtualHost *:80>
   ServerName "publish"

   # ...

   <IfModule mod_headers.c>
       Header add X-Vhost "publish"

        ################## Start of the CORS specific configuration ##################

        SetEnvIfExpr "req_novary('Origin') == ''"  CORSType=none CORSProcessing=false
        SetEnvIfExpr "req_novary('Origin') != ''"  CORSType=cors CORSProcessing=true CORSTrusted=false

        SetEnvIfExpr "req_novary('Access-Control-Request-Method') == '' && %{REQUEST_METHOD} == 'OPTIONS' && req_novary('Origin') != ''  " CORSType=invalidpreflight CORSProcessing=false
        SetEnvIfExpr "req_novary('Access-Control-Request-Method') != '' && %{REQUEST_METHOD} == 'OPTIONS' && req_novary('Origin') != ''  " CORSType=preflight CORSProcessing=true CORSTrusted=false
        SetEnvIfExpr "req_novary('Origin') -strcmatch 'https://%{HTTP_HOST}*'"  CORSType=samedomain CORSProcessing=false

        # For requests that require CORS processing, check if the Origin can be trusted
        SetEnvIfExpr "%{HTTP_HOST} =~ /(.*)/ " ParsedHost=$1

        ################## Adapt the regex to match CORS origin for your environment
        SetEnvIfExpr "env('CORSProcessing') == 'true' && req_novary('Origin') =~ m#(https://.*.your-domain.tld(:\d+)?$)#" CORSTrusted=true

        # Extract the Origin header
        SetEnvIfNoCase ^Origin$ ^https://(.*)$ CORSTrustedOrigin=https://$1

        # Flush If already set
        Header unset Access-Control-Allow-Origin
        Header unset Access-Control-Allow-Credentials

        # Trusted
        Header always set Access-Control-Allow-Credentials "true" "expr=reqenv('CORSTrusted') == 'true'"
        Header always set Access-Control-Allow-Origin "%{CORSTrustedOrigin}e" "expr=reqenv('CORSTrusted') == 'true'"
        Header always set Access-Control-Allow-Methods "GET" "expr=reqenv('CORSTrusted') == 'true'"
        Header always set Access-Control-Max-Age 1800 "expr=reqenv('CORSTrusted') == 'true'"
        Header always set Access-Control-Allow-Headers "Origin, Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers" "expr=reqenv('CORSTrusted') == 'true'"

        # Non-CORS or Not Trusted
        Header unset Access-Control-Allow-Credentials "expr=reqenv('CORSProcessing') == 'false' || reqenv('CORSTrusted') == 'false'"
        Header unset Access-Control-Allow-Origin "expr=reqenv('CORSProcessing') == 'false' || reqenv('CORSTrusted') == 'false'"
        Header unset Access-Control-Allow-Methods "expr=reqenv('CORSProcessing') == 'false' || reqenv('CORSTrusted') == 'false'"
        Header unset Access-Control-Max-Age "expr=reqenv('CORSProcessing') == 'false' || reqenv('CORSTrusted') == 'false'"

        # Always vary on origin, even if its not there.
        Header merge Vary Origin

        # CORS - send 204 for CORS requests which are not trusted
        RewriteCond expr "reqenv('CORSProcessing') == 'true' && reqenv('CORSTrusted') == 'false'"
        RewriteRule "^(.*)" - [R=204,L]

        ################## End of the CORS specific configuration ##################

   </IfModule>

   <Directory />

       # ...

   </Directory>

   # ...

</VirtualHost>

하나의 결과가 필요한 경우:

• 모델 이름을 사용하십시오(예: 도시).

결과 목록을 기대하는 경우:

• 모델 이름에 List를 추가하십시오. 예: cityList
• 샘플 쿼리 - 모든 도시에 대한 모든 정보를 참조하십시오

이후에 다음과 같은 작업을 수행할 수 있습니다.

• 결과 정렬

  • ASC: 오름차순
  • DESC: 내림차순

• 다음 중 하나를 사용하여 결과 페이지를 반환합니다.

  • 오프셋 및 제한이 포함된 목록 쿼리
  • 첫 번째 및 그 다음 페이지가 포함된 페이지 매김된 쿼리

• 샘플 쿼리 - 모든 도시에 대한 모든 정보를 참조하십시오

필터 includeVariations이(가) List 쿼리 형식에 포함되어 있습니다. 쿼리 결과에서 콘텐츠 조각 변형을 검색하려면 includeVariations 필터를 true(으)로 설정해야 합니다.

논리적 OR을 사용하려는 경우:

• _logOp: OR 사용
• 샘플 쿼리 - 이름이 “Jobs” 또는 “Smith”인 모든 사람을 참조하십시오

논리적 AND도 존재하지만 (흔히) 암시적

콘텐츠 조각 모델 내의 필드에 해당하는 필드 이름을 쿼리할 수 있습니다.

• 샘플 쿼리 - 회사 CEO 및 직원의 전체 세부 정보를 참조하십시오

모델의 필드 외에도 일부 시스템 생성 필드(앞에 밑줄 표시)가 있습니다.

• 콘텐츠의 경우:

  • _locale: 언어 표시, 언어 관리자 기반

    • 주어진 로케일의 복수 콘텐츠 조각에 대한 샘플 쿼리를 참조하십시오

  • _metadata: 조각에 대한 메타데이터 표시

    • 메타데이터에 대한 샘플 쿼리 - GB라는 제목의 상에 대한 메타데이터 나열을 참조하십시오

  • _model: 콘텐츠 조각 모델에 대한 쿼리 허용 (경로 및 제목)

    • 모델의 콘텐츠 조각 모델에 대한 샘플 쿼리를 참조하십시오

  • _path: 저장소 내의 콘텐츠 조각에 대한 경로

    • 샘플 쿼리 - 단일 특정 도시 조각을 참조하십시오

  • _reference: 참조 표시, 서식 있는 텍스트 편집기에 인라인 참조 포함

    • 프리페치된 참조가 포함된 복수 콘텐츠 조각에 대한 샘플 쿼리를 참조하십시오

  • _variation: 콘텐츠 조각 내 특정 변형 표시

    note note
    NOTE
    지정된 변형이 콘텐츠 조각에 존재하지 않는 경우, 마스터 변형은 (대체) 기본값으로 반환됩니다.

    note caution
    CAUTION
    시스템 생성 필드 _variation은 필터 includeVariations과 함께 사용할 수 없습니다.

    • 샘플 쿼리 - 이름이 붙은 변형이 있는 모든 도시를 참조하십시오

  • _tags : 태그가 포함된 콘텐츠 조각 또는 변형의 ID를 표시합니다. 이 목록은 cq:tags 식별자의 배열입니다.

    • 샘플 쿼리 - City Break로 태그된 모든 도시의 이름 참조
    • 특정 태그가 첨부된 주어진 모델의 콘텐츠 조각 변형에 대한 샘플 쿼리 참조

    note note
    NOTE
    콘텐츠 조각의 메타데이터를 나열하여 태그를 쿼리할 수도 있습니다.

• 작업:

  • _operator: 특정 연산자 적용 - EQUALS, EQUALS_NOT, GREATER_EQUAL, LOWER, CONTAINS, STARTS_WITH

    • 샘플 쿼리 - 이름이 “Jobs”가 아닌 모든 사람을 참조하십시오
    • 샘플 쿼리 - _path가 특정 접두사로 시작하는 모든 모험을 참조하십시오

  • _apply: 특정 조건 적용. 예: AT_LEAST_ONCE

    • 샘플 쿼리 - 적어도 한 번은 발생해야 하는 항목이 있는 배열 필터링을 참조하십시오

  • _ignoreCase: 쿼리할 때 대소문자 무시

    • 샘플 쿼리 - 대소문자에 관계없이 이름에 SAN이 있는 모든 도시를 참조하십시오

GraphQL 공용 구조체 형식이 지원됩니다.

• ... on 사용
  • 콘텐츠 참조가 있는 특정 모델의 콘텐츠 조각에 대한 샘플 쿼리를 참조하십시오

중첩된 조각 쿼리 시 대체:

• 요청된 변형이 중첩된 조각에 없으면 기본 변형이 반환됩니다.

GraphQL 쿼리에 둘 이상의 모델에서 이름이 같은 필드가 포함되어 있고 다음 조건이 충족되면 필드 충돌 오류가 반환됩니다.

• 여기서

  • 두 개 이상의 모델이 가능한 참조로 사용됩니다. 콘텐츠 조각 참조에서 허용된 모델 유형(으)로 정의된 경우.

  및:

  • 이 두 모델에는 공통 이름을 갖는 필드가 있습니다. 즉, 두 모델에서 동일한 이름이 발생합니다.

  및

  • 이러한 필드는 다른 데이터 유형입니다.

• 예:

  • 모델이 다른 두 개(예: M1, M2) 이상의 조각이 다른 조각에서 가능한 참조(콘텐츠 참조 또는 조각 참조)로 사용되는 경우(예: Fragment1 MultiField/List)

  • 모델이 다른 두 조각(M1, M2)에는 이름은 같지만 유형이 다른 필드가 있습니다.
    예시:

    • M1.Title을(를) Text(으)로
    • M2.Title을(를) Text/MultiField(으)로

  • 그러면 GraphQL 쿼리에 Title 필드가 포함된 경우 필드 충돌 오류가 발생합니다.