コンテンツフラグメントと共に使用する AEM GraphQL API graphql-api-for-use-with-content-fragments

「…API のクエリ言語と、既存のデータを使用してこれらのクエリを満たすランタイムです。GraphQL は、API でデータの完全で理解可能な説明を提供します。必要なものと不要なものを正確に求める力をクライアントに提供し、API を時間の経過と共に発展させ、強力な開発者ツールを実現します」。

GraphQL.org を参照

「…柔軟な API レイヤー用のオープンな仕様。GraphQL を既存のバックエンドに重ね合わせ、これまでにない速さで製品を構築できます…」

Explore GraphQL を参照してください。

「…2012 年に Facebook 社内で開発されたデータクエリ言語および仕様です。その後、2015 年には公式にオープンソースとなりました。開発者の生産性を高め、転送データの量を最小限に抑えるために、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 エンドポイントの有効化を参照してください。

1 つのエントリ

エントリのリスト

パブリッシュ環境の使用目的：

• JS アプリケーションのデータのクエリ（標準の使用例）

オーサー環境の使用目的：

• 「コンテンツ管理用」のデータのクエリ：

  • AEM の GraphQL は読み取り専用の API です。
  • REST API は、CR(U)D の操作に使用できます。

ユーザーが生成するフィールド

選択されたフィールドタイプを使用して、コンテンツフラグメントモデルの設定方法に基づいてフィールドが作成されます。フィールド名は、データタイプ ​の「プロパティ名」フィールドから取得されます。

• ユーザーが特定のデータタイプを設定できるので、レンダリング形式 ​設定も考慮する必要があります。例えば、1 行のテキストフィールドに複数の 1 行のテキストを含めるように設定するには、ドロップダウンから「multifield」を選択します。

AEM の GraphQL も、複数のヘルパーフィールドを生成します。

これらは、コンテンツフラグメントを識別するためや、コンテンツフラグメントに関する詳細を取得するために使用されます。

AEM 用 GraphQL の拡張機能の詳細

このサンプルコンテンツおよび構造を使用したサンプルクエリ

• さらに、サンプルクエリ用に準備されているサンプルコンテンツおよび構造

WKND プロジェクトに基づいたサンプルクエリ

フィールドパスを表すコンマ区切りの値のリスト

• リスト内の最初のフィールドで、主な並べ替え順を定義します

  • 2 番目のフィールドは、主な並べ替え条件の 2 つの値が等しい場合に使用されます
  • 最初の 2 つの条件が等しい場合は 3 番目のフィールドを、などのように使用されます

• 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 関連のヘッダーが、どの場合でも 1 か所で正しく設定されます。

• このような設定は 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>

結果が 1 つだけ必要な場合：

• 市区町村などのモデル名を使用します。

結果のリストを想定している場合：

• モデル名に List を付け加えます（例：cityList）
• サンプルクエリ - すべての都市に関するすべての情報を参照してください

これにより、以下のことが可能になります。

• 結果の並べ替え

  • ASC : 昇順
  • DESC : 降順

• 次のいずれかを使用して、結果のページを返します。

  • オフセットと制限を指定したリストクエリ
  • 最初とその後を指定したページ分割クエリ

• サンプルクエリ - すべての都市に関するすべての情報を参照してください

フィルター includeVariations は List のクエリタイプに含まれます。クエリ結果でコンテンツフラグメントのバリエーションを取得するには、includeVariations フィルターを true に設定する必要があります。

論理和（OR）を使用する場合：

• _logOp: OR を使用します
• サンプルクエリ - 「Jobs」または「Smith」という名前を持つすべての人物を参照してください

論理積（AND）も存在しますが、（多くの場合）暗黙的です

コンテンツフラグメントモデル内のフィールドに対応するフィールド名に対してクエリを実行できます

• サンプルクエリ - ある会社の CEO と従業員の詳細を参照してください

モデルのフィールドに加えて、次のようなシステム生成フィールドがあります（フィールド名の先頭にアンダースコアが付きます）。

• コンテンツの場合：

  • _locale：言語を表示します（言語マネージャーに基づく）

    • 特定ロケールの複数のコンテンツフラグメントのサンプルクエリを参照してください

  • _metadata：フラグメントのメタデータを表示します

    • メタデータのサンプルクエリ - 「GB」という賞のメタデータのリストを参照してください

  • _model：コンテンツフラグメントモデル（パスとタイトル）のクエリを許可します

    • モデルからのコンテンツフラグメントモデルのサンプルクエリを参照してください

  • _path：リポジトリ内のコンテンツフラグメントへのパス

    • 詳しくは、サンプルクエリ - 1 つの特定の都市フラグメントを参照してください。

  • _reference：参照（リッチテキストエディターでのインライン参照など）を表示します

    • プリフェッチされた参照を含んだ複数のコンテンツフラグメントのサンプルクエリを参照してください

  • _variation：コンテンツフラグメント内の特定のバリエーションを表示します

    note note
    NOTE
    コンテンツフラグメントに指定されたバリエーションが存在しない場合は、プライマリバリエーションが（フォールバック）デフォルトとして返されます。

    note caution
    CAUTION
    システム生成フィールド _variation は、フィルター includeVariations と併用できません。

    • サンプルクエリ - 名前付きバリエーションを持つすべての都市を参照してください

  • _tags：タグを含むコンテンツフラグメントまたはバリエーションの ID を表示します。このリストは cq:tags 識別子の配列です。

    • サンプルクエリ - 市区町村の区切り文字としてタグ付けされた、すべての都市の名前を参照してください。
    • 詳しくは、特定のタグが添付された、任意のモデルのコンテンツフラグメントバリエーションのサンプルクエリを参照してください。

    note note
    NOTE
    また、コンテンツフラグメントのメタデータを一覧表示して、タグをクエリできます。

• 操作の場合：

  • _operator：特定の演算子（EQUALS、EQUALS_NOT、GREATER_EQUAL、LOWER、CONTAINS、STARTS_WITH）を適用します

    • サンプルクエリ - 「Jobs」という名前を持たないすべての人物を参照してください
    • サンプルクエリ - _path が特定の接頭辞で始まるすべてのアドベンチャーを参照してください

  • _apply：特定の条件（例：AT_LEAST_ONCE）を適用します

    • サンプルクエリ - 少なくとも 1 回は現れる項目を含んだ配列をフィルタリングを参照してください

  • _ignoreCase：クエリの実行時に大文字と小文字を区別しません

    • サンプルクエリ - 名前に SAN が含まれるすべての都市（大文字と小文字を区別しない場合）を参照してください

GraphQL のユニオン型がサポートされています

• ... on を使用します
  • 特定モデルのコンテンツフラグメントのうちコンテンツ参照を含んだものを取得するサンプルクエリを参照してください

ネストされたフラグメントに対するクエリ時のフォールバック：

• 要求されたバリエーションがネストされたフラグメントに存在しない場合、プライマリ ​バリエーションが返されます。

GraphQL クエリに 2 つ（またはそれ以上）のモデルで同じ名前のフィールドが含まれており、次の条件が満たされる場合、フィールド競合エラーが返されます。

• したがって

  • 2 つ（またはそれ以上のモデル）が可能な参照として使用されます（コンテンツフラグメント参照で許可された​ モデルタイプ ​として定義されている場合）。

  また

  • これら 2 つのモデルには共通の名前を持つフィールドがあります。つまり、両方のモデルに同じ名前が存在します。

  また

  • これらのフィールドは異なるデータタイプです。

• 例：

  • 異なるモデルを持つ 2 つ（またはそれ以上）のフラグメント（M1、M2 など）が、別のフラグメントからの参照（コンテンツ参照またはフラグメント参照）として使用される場合。例：Fragment1 MultiField/List

  • 異なるモデルを持つこれら 2 つのフラグメント（M1、M2）には、同じ名前のフィールドがありますが、タイプが異なります。
    次に例を示します。

    • M1.Title は Text
    • M2.Title は Text/MultiField

  • GraphQL クエリに Title フィールドが含まれる場合、フィールド競合エラーが発生します。