コンテンツフラグメントと共に使用する AEM GraphQL API

Adobe Experience Manager(AEM)as a Cloud Service のコンテンツフラグメントを AEM GraphQL API と共に使用してヘッドレスコンテンツ配信を実現する方法を説明します。

コンテンツフラグメントと共に使用する AEM as a Cloud Service GraphQL API は、オープンソースの標準 GraphQL API に大きく依存しています。

AEM の GraphQL API を使用すると、ヘッドレス CMS 実装の JavaScript クライアントにコンテンツフラグメントを効率的に配信できます。

  • REST で API リクエストの反復を回避
  • 特定の要件に限定された配信を確保
  • 1 つの API クエリへの応答としてレンダリングに必要なものだけを一括配信
メモ

GraphQL は現在、Adobe Experience Manager(AEM)as a Cloud Service の、2 つの(個別の)シナリオで使用されています。

GraphQL API

GraphQL とは次のことを意味します。

  • …API のクエリ言語と、既存のデータを使用してこれらのクエリを満たすランタイムです。GraphQL は、API のデータの完全で理解可能な説明を提供し、必要なものを正確に要求する力をクライアントに与え、API の長期的な発展を促し、強力な開発ツールの実現を可能にします。

    GraphQL.org を参照

  • …柔軟な API レイヤー用のオープンな仕様。GraphQL を既存のバックエンドに重ね合わせて、以前に比べて迅速に製品を構築…。

    Explore GraphQL」を参照

  • 「…2012 年に Facebook 社内で開発されたデータクエリ言語および仕様です。その後、2015 年には公式にオープンソースとなりました。開発者の生産性を高め、転送データの量を最小限に抑えるために、REST ベースのアーキテクチャに代わる手段を提供します。GraphQL は、あらゆる規模の数百の組織により実稼働環境で使用されています…」

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

GraphQL API の詳細については、(多くのリソースの中でも特に)以下を参照してください。

AEM 用 GraphQL の実装は、標準の GraphQL Java ライブラリをベースにしています。以下を参照してください。

GraphQL 用語

GraphQL では次を使用します。

ベストプラクティスを含む包括的な詳細については、「(GraphQL.org) GraphQL の概要」を参照してください。

GraphQL クエリタイプ

GraphQL では、次のいずれかを返すクエリを実行できます。

また、次の操作も実行できます。

メモ

また、GraphiQL IDE を使用して、GraphQL クエリのテストとデバッグを行うこともできます。

AEM 用 GraphQL のエンドポイント

エンドポイントは、AEM 用 GraphQL へのアクセスに使用するパスです。このパスを使用すると、以下が可能になります。

  • GraphQL スキーマへのアクセス
  • GraphQL クエリの送信
  • (GraphQL クエリに対する)応答の受信

AEM には次の 2 種類のエンドポイントがあります。

  • グローバル
    • すべてのサイトで使用できます。
    • このエンドポイントは、(設定ブラウザーで定義された)すべての Sites 設定のすべてのコンテンツフラグメントモデルを使用できます。
    • Sites 設定間で共有する必要があるコンテンツフラグメントモデルがある場合は、それらをグローバル Sites 設定の下に作成する必要があります。
  • Sites 設定:
    • 設定ブラウザーで定義されている Sites 設定に対応します。
    • 指定したサイト/プロジェクトに固有です。
    • Sites 設定固有のエンドポイントは、その特定の Sites 設定のコンテンツフラグメントモデルと、グローバル Sites 設定のコンテンツフラグメントモデルを使用します。
注意

コンテンツフラグメントエディターを使用すると、Sites 設定のコンテンツフラグメントから別の Sites 設定のコンテンツフラグメントを(ポリシーを介して)参照できます。

この場合、Sites 設定固有のエンドポイントを使用してすべてのコンテンツを取得できるわけではありません。

コンテンツ作成者がこのシナリオを制御する必要があります。例えば、共有コンテンツフラグメントモデルをグローバルサイト設定の下に配置すると便利です。

AEM グローバルエンドポイント用 GraphQL のリポジトリーパスは次のとおりです。

/content/cq:graphql/global/endpoint

アプリは、リクエスト URL で次のパスを使用できます。

/content/_cq_graphql/global/endpoint.json

AEM 用 GraphQL のエンドポイントを有効にするには、次の操作が必要です。

GraphQL エンドポイントの有効化

GraphQL エンドポイントを有効にするには、まず適切な設定が必要です。「コンテンツフラグメント - 設定ブラウザー 」を参照してください。

注意

コンテンツフラグメントモデルの使用が有効になっていない場合、「作成」オプションは使用できません。

対応するエンドポイントを有効にするには、以下を行います。

  1. ツールアセット に移動し、GraphQL を選択します。

  2. 作成」を選択します。

  3. 新しい GraphQL エンドポイントを作成​ダイアログが開きます。以下を指定します。

    • 名前:エンドポイントの名前。任意のテキストを入力できます。
    • 使用する GraphQL スキーマの提供元:ドロップダウンを使用して、必要なサイト/プロジェクトを選択します。
    メモ

    ダイアログには次の警告が表示されます。

    • 慎重に管理しない場合、GraphQL エンドポイントによりデータのセキュリティとパフォーマンスで問題が発生する可能性があります。エンドポイントを作成した後で、適切な権限を設定するようにしてください。
  4. 作成」で確定します。

  5. 次の手順」ダイアログには、セキュリティコンソールへの直接リンクが表示されるので、新しく作成したエンドポイントに適切な権限が付与されているか確認できます。

    注意

    エンドポイントは、すべてのユーザーがアクセスできます。そのため、GraphQL クエリがサーバーに大きな負荷をかける可能性があるので、特にパブリッシュインスタンスでは、セキュリティ上の問題が発生するおそれがあります。

    使用例に適した ACL をエンドポイントに設定できます。

GraphQL エンドポイントの公開

新しいエンドポイントを選択し、「 公開」を選択して、すべての環境で完全に使用できるようにします。

注意

エンドポイントは、すべてのユーザーがアクセスできます。

GraphQL クエリがサーバーに大きな負荷をかける可能性があるので、パブリッシュインスタンスでは、セキュリティ上の問題が発生する恐れがあります。

ユースケースに適した ACL をエンドポイントに設定する必要があります。

GraphiQL インターフェイス

標準の GraphiQL インターフェイスの実装は、AEM GraphQL で使用できます。これは AEM と共にインストールできます。

メモ

GraphiQL はグローバルエンドポイントにバインドされます(特定の Sites 設定の他のエンドポイントでは機能しません)。

このインターフェイスを使用すると、クエリを直接入力しテストできます。

例えば、次のようなものです。

  • http://localhost:4502/content/graphiql.html

構文のハイライト表示機能、オートコンプリート、自動候補表示などの機能と共に、履歴およびオンラインドキュメントが提供されています。

GraphiQL インターフェイス

AEM GraphiQL インターフェイスのインストール

GraphiQL ユーザーインターフェイスは、専用のパッケージ(GraphiQL Content Package v0.0.6(2021.3))で AEM にインストールできます。

オーサー環境とパブリッシュ環境の使用例

使用例は、AEM as a Cloud Service 環境のタイプに応じて異なる場合があります。

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

    • JS アプリケーションのデータのクエリ(標準の使用例)
  • オーサー環境の使用目的:

    • 「コンテンツ管理用」のデータのクエリ:
      • AEM as a Cloud Service の GraphQL は現在読み取り専用の API です。
      • CR(U)D 操作には REST API を使用できます。

権限

Assets へのアクセスに必要な権限です。

スキーマ生成

GraphQL は、厳密に型指定された API です。つまり、データは型別に明確に構造化され編成される必要があります。

GraphQL の仕様には、特定のインスタンス上のデータをクエリするための堅牢な API を作成する方法に関する一連のガイドラインが用意されています。そのタスクを行うには、クライアントはスキーマを取得する必要があります。この中には、クエリに必要なすべての型が定義されています。

コンテンツフラグメントの場合、GraphQL スキーマ(構造とタイプ)は、有効​なコンテンツフラグメントモデルとそれらのデータタイプに基づいています。

注意

有効​になっているコンテンツフラグメントモデルから派生した)すべての GraphQL スキーマは、GraphQL エンドポイントを通じて読み取り可能です。

つまり、漏洩するおそれがあるので、機密データが使用可能になっていないことを確認する必要があります。例えば、これには、モデル定義のフィールド名として存在する可能性のある情報が含まれます。

例えば、ユーザーが Article という名前のコンテンツフラグメントモデルを作成した場合、AEM は ArticleModel 型のオブジェクト article を生成します。この型に含まれるフィールドは、モデルで定義されているフィールドとデータ型に対応しています。

  1. コンテンツフラグメントモデル:

    GraphQL で使用するコンテンツフラグメントモデル

  2. 対応する GraphQL スキーマ(GraphiQL 自動生成ドキュメントからの出力):
    コンテンツフラグメントモデルに基づく GraphQL スキーマ

    この図では、生成された型 ArticleModel に複数のフィールドが含まれていることがわかります。

    • そのうちの 3 つ(authormainreferencearticle)は、ユーザーが管理しています。

    • その他のフィールド(この例では _path_metadata_variations)は AEM によって自動的に追加されたもので、特定のコンテンツフラグメントに関する情報を提供する便利な手段となっています。これらのヘルパーフィールドは、ユーザーが定義したものと自動生成されたものを区別するために、先頭に _ が付いています。

  3. ユーザーが Article モデルに基づいてコンテンツフラグメントを作成すると、GraphQL を使用してそれをクエリできます。例については、(GraphQL で使用するコンテンツフラグメント構造のサンプルに基づいた)サンプルクエリを参照してください。

AEM 用 GraphQL では、スキーマには柔軟性があります。つまり、コンテンツフラグメントモデルを作成、更新、削除するたびに、スキーマが自動生成されます。また、コンテンツフラグメントモデルを更新すると、データスキーマキャッシュも更新されます。

Sites GraphQL サービスは、コンテンツフラグメントモデルに対する変更を(バックグラウンドで)リッスンします。更新が検出されると、スキーマのその部分だけが再生成されます。この最適化により、時間が節約され、安定性も確保されます。

例えば、次のようになります。

  1. Content-Fragment-Model-1Content-Fragment-Model-2 を含んだパッケージをインストールすると、

    1. Model-1Model-2 の GraphQL 型が生成されます。
  2. 次に Content-Fragment-Model-2 を変更すると、

    1. Model-2 GraphQL 型だけが更新されます。

    2. 一方、Model-1 は同じままです。

メモ

REST API を使用してコンテンツフラグメントモデルの一括更新を行う場合などには、この点に留意することが大切です。

スキーマは、GraphQL クエリと同じエンドポイントを通じて提供され、クライアントはスキーマが拡張子 GQLschema で呼び出されることに対処します。例えば、/content/cq:graphql/global/endpoint.GQLschema で単純な GET リクエストを実行すると、text/x-graphql-schema;charset=iso-8859-1 の Content-type を持つスキーマが出力されます。

スキーマの生成 - 未公開のモデル

コンテンツフラグメントがネストされると、親のコンテンツフラグメントモデルは公開されますが、参照モデルは公開されません。

メモ

AEM UI はこのような問題を回避しますが、プログラムを使用して、またはコンテンツパッケージを使用して公開すると、この問題が発生する可能性があります。

この場合、AEM は親コンテンツフラグメントモデルの​不完全な​スキーマを生成します。つまり、非公開のモデルに依存するフラグメント参照がスキーマから削除されます。

フィールド

スキーマ内には、次の 2 つの基本的なカテゴリに属する個々のフィールドがあります。

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

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

    • また、レンダリング時の名前​プロパティも考慮する必要があります。ユーザーが特定のデータ型を、例えば、1 行のテキストか複数フィールドのどちらかとして設定できるからです。
  • AEM 用 GraphQL が生成する多数のヘルパーフィールド

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

フィールドタイプ

AEM 用 GraphQL では一連のタイプをサポートしています。サポートされているすべてのコンテンツフラグメントモデルデータ型と、それに対応する GraphQL 型を以下の表に示します。

コンテンツフラグメントモデル - データ型 GraphQL の型 説明
1 行のテキスト String、[String] 作成者名、場所名などの単純な文字列に使用します。
複数行テキスト 文字列 記事の本文などのテキストを出力するために使用します
数値 Float、[Float] 浮動小数点数と整数を表示するために使用します
ブール型 Boolean チェックボックスを表示するために使用します(単純な真/偽のステートメント)
日時 Calendar 日時を ISO 8086 形式で表示するために使用します。選択したタイプに応じて、AEM GraphQL で使用できるフレーバーは、onlyDateonlyTimedateTime の 3 つです。
列挙 String モデルの作成時に定義されたオプションのリストに含まれるオプションを表示するために使用します
タグ [String] AEM で使用されているタグを表す文字列のリストを表示するために使用します
コンテンツ参照 文字列 AEM 内の別のアセットへのパスを表示するために使用します
フラグメント参照 モデルタイプ 特定のモデルタイプの別のコンテンツフラグメントを参照するために使用します(モデルの作成時に定義されます)

ヘルパーフィールド

ユーザー生成フィールドのデータ型に加えて、AEM 用 GraphQL では、コンテンツフラグメントの識別やコンテンツフラグメントに関する追加情報の提供に役立つ多数の​ヘルパー​フィールドも生成されます。

パス

パスフィールドは、GraphQL で識別子として使用されます。これは、AEM リポジトリー内のコンテンツフラグメントアセットのパスを表します。これをコンテンツフラグメントの識別子として選択した理由は次のとおりです。

  • AEM 内で一意である
  • 取得しやすい

次のコードでは、コンテンツフラグメントモデル Person に基づいて作成されたすべてのコンテンツフラグメントのパスを表示します。

{
  personList {
    items {
      _path
    }
  }
}

特定のタイプのコンテンツフラグメントを 1 つ取得するには、まずそのパスも決定する必要があります。次に例を示します。

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      firstName
      name
    }
  }
}

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

メタデータ

また、AEM では GraphQL を通じて、コンテンツフラグメントのメタデータも公開します。メタデータは、コンテンツフラグメントのタイトル、サムネールパス、コンテンツフラグメントの説明、作成日など、コンテンツフラグメントを説明する情報です。

メタデータはスキーマエディターで生成され、特定の構造を持たないので、コンテンツフラグメントのメタデータを公開するために GraphQL 型 TypedMetaData が実装されました。TypedMetaData では、次のスカラー型でグループ化された情報を公開します。

フィールド
stringMetadata:[StringMetadata]!
stringArrayMetadata:[StringArrayMetadata]!
intMetadata:[IntMetadata]!
intArrayMetadata:[IntArrayMetadata]!
floatMetadata:[FloatMetadata]!
floatArrayMetadata:[FloatArrayMetadata]!
booleanMetadata:[BooleanMetadata]!
booleanArrayMetadata:[booleanArrayMetadata]!
calendarMetadata:[CalendarMetadata]!
calendarArrayMetadata:[CalendarArrayMetadata]!

各スカラー型は、名前と値の 1 つのペアを表すか、名前と値のペアの配列を表します。このペアの値は、グループ化されたときの型になります。

例えば、コンテンツフラグメントのタイトルを取得する場合は、このプロパティが String 型プロパティであることがわかっているので、すべての String 型メタデータをクエリすることになります。

メタデータをクエリするには、次のようにします。

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _path
      _metadata {
        stringMetadata {
          name
          value
        }
      }
    }
  }
}

生成された GraphQL スキーマを表示するには、すべてのメタデータ GraphQL 型を表示します。すべてのモデルタイプは同じ TypedMetaData を持ちます。

メモ

標準メタデータと配列メタデータの違い
StringMetadataStringArrayMetadata はどちらも、リポジトリーに格納されているものについての指定であり、その取得手段についての指定ではありません。

例えば、stringMetadata フィールドを呼び出すと、リポジトリーに String として格納されているすべてのメタデータの配列を受け取ることになります。一方、stringArrayMetadata を呼び出すと、リポジトリーに String[] として格納されているすべてのメタデータの配列を受け取ります。

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

バリエーション

コンテンツフラグメントのバリエーションに対するクエリを簡略化するために、_variations フィールドが実装されています。次に例を示します。

{
  personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
    item {
      _variations
    }
  }
}

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

GraphQL 変数

GraphQL では、クエリに変数を含めることができます。詳しくは、GraphQL の変数に関するドキュメントを参照してください。

例えば、特定のバリエーションを持つ Article タイプのコンテンツフラグメントをすべて取得するには、次のように、GraphiQL で変数 variation を指定します。

GraphQL 変数

### query
query GetArticlesByVariation($variation: String!) {
    articleList(variation: $variation) {
        items {
            _path
            author
        }
    }
}
 
### in query variables
{
    "variation": "uk"
}

GraphQL ディレクティブ

GraphQL では、GraphQL ディレクティブと呼ばれる変数に基づいてクエリを変更する可能性があります。

例えば、変数 includePrice に基づいて、すべての AdventureModels のクエリに adventurePrice フィールドを含めることができます。

GraphQL ディレクティブ

### query
query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      adventureTitle
      adventurePrice @include(if: $includePrice)
    }
  }
}
 
### in query variables
{
    "includePrice": true
}

フィルタリング

GraphQL クエリでフィルタリングを使用して、特定のデータを返すこともできます。

フィルタリングでは、論理演算子と論理式に基づいた構文を使用します。

例えば、次の(基本的な)クエリでは、Jobs または Smith という名前を持つすべての人を抜き出します。

query {
  personList(filter: {
    name: {
      _logOp: OR
      _expressions: [
        {
          value: "Jobs"
        },
        {
          value: "Smith"
        }
      ]
    }
  }) {
    items {
      name
      firstName
    }
  }
}

その他の例については、以下を参照してください。

AEM 用の GraphQL - 拡張機能の概要

AEM 用の GraphQL でのクエリの基本操作は、標準の GraphQL 仕様に従います。AEM での GraphQL クエリには、次のような拡張機能があります。

永続的クエリ(キャッシュ)

POST リクエストを使用してクエリを準備した後、HTTP キャッシュまたは CDN でキャッシュできる GET リクエストを使用して、そのクエリを実行できます。

このようにする必要があるのは、POST クエリが通常はキャッシュされないからです。クエリをパラメーターとして GET を使用する場合、HTTP サービスや中間ステップにとってパラメーターが大きくなりすぎるという重大なリスクがあります。

持続的なクエリでは、常に適切な Sites 設定に関連するエンドポイントを使用する必要があるため、次のどちらかまたは両方を使用できます。

  • グローバル設定とエンドポイント:
    クエリは、すべてのコンテンツフラグメントモデルにアクセスできます。
  • 特定の Sites 設定およびエンドポイント:
    特定の Sites 設定用の永続クエリを作成するには、対応する Sites 設定固有のエンドポイント(関連するコンテンツフラグメントモデルへのアクセスを提供)が必要です。例えば、WKND Sites 設定専用の永続クエリを作成するには、対応する WKND 固有の Sites 設定と、WKND 固有のエンドポイントを事前に作成する必要があります。
メモ

詳しくは、設定ブラウザーでのコンテンツフラグメント機能の有効化を参照してください。

適切な Sites 設定では、GraphQL Persistence Queries を有効にする必要があります。

例えば、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
メモ

これらは 2 つの異なるクエリで、異なるパスに保存されます。

同じモデルを使用していますが、異なるエンドポイントを介しています。

特定のクエリを永続化するために必要な手順は次のとおりです。

  1. 新しいエンドポイント URL /graphql/persist.json/<config>/<persisted-label> に PUT してクエリを準備します。

    例えば、次のようにして、永続的クエリを作成します。

    $ 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
            }
          }
        }
      }'
    
  8. パラメーター付きのクエリを実行します。

    次に例を示します。

    $ curl -X POST \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -H "Content-Type: application/json" \
        "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    
    $ curl -X GET \
        "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters;apath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    
  9. パブリッシュでクエリを実行するには、関連する永続的ツリーをレプリケートする必要があります。

    • レプリケーションに POST を使用する場合:

      $curl -X POST   http://localhost:4502/bin/replicate.json \
        -H 'authorization: Basic YWRtaW46YWRtaW4=' \
        -F path=/conf/wknd/settings/graphql/persistentQueries/plain-article-query \
        -F cmd=activate
      
    • パッケージを使用する場合:

      1. 新しいパッケージ定義を作成します。
      2. 設定(例:/conf/wknd/settings/graphql/persistentQueries)を含めます。
      3. パッケージをビルドします。
      4. パッケージをレプリケートします。
    • レプリケーション/配布ツールを使用する場合:

      1. 配布ツールに移動します。
      2. 設定のツリーアクティベーション(例:/conf/wknd/settings/graphql/persistentQueries)を選択します。
    • (ワークフローランチャーの設定を通じて)ワークフローを使用する場合:

      1. 様々なイベント(例:作成、変更など)で設定をレプリケートするワークフローモデルを実行するためのワークフローランチャールールを定義します。
  10. クエリの設定がいったん公開されると、パブリッシュエンドポイントを使用するだけで、同じ原則が適用されます。

    メモ

    匿名アクセスの場合は、ACL で「全員」にクエリ設定へのアクセスが許可されているとシステムが想定します。

    そうでない場合は、実行できなくなります。

    メモ

    URL 内のセミコロン(「;」)はすべてエンコードする必要があります。

    例えば、永続的クエリを実行するリクエストの場合と同様に、次のようにします。

    curl -X GET \ "http://localhost:4502/graphql/execute.json/wknd/plain-article-query-parameters%3bapath=%2fcontent2fdam2fwknd2fen2fmagazine2falaska-adventure2falaskan-adventures;withReference=false"
    

外部 Web サイトからの GraphQL エンドポイントのクエリ

外部 Web サイトから GraphQL エンドポイントにアクセスするには、次の項目を設定する必要があります。

CORS フィルター

メモ

AEM での CORS リソース共有ポリシーについて詳しくは、クロスオリジンリソース共有(CORS)についてを参照してください。

GraphQL エンドポイントにアクセスするには、顧客の Git リポジトリーに CORS ポリシーを設定する必要があります。それには、目的のエンドポイントに適した OSGi CORS 設定ファイルを追加します。

この設定では、アクセスを許可する必要がある信頼できる Web サイトオリジン alloworigin または alloworiginregexp を指定する必要があります。

例えば、https://my.domain の GraphQL エンドポイントと永続クエリのエンドポイントへのアクセスを許可するには、以下を使用します。

{
  "supportscredentials":true,
  "supportedmethods":[
    "GET",
    "HEAD",
    "POST"
  ],
  "exposedheaders":[
    ""
  ],
  "alloworigin":[
    "https://my.domain"
  ],
  "maxage:Integer":1800,
  "alloworiginregexp":[
    ""
  ],
  "supportedheaders":[
    "Origin",
    "Accept",
    "X-Requested-With",
    "Content-Type",
    "Access-Control-Request-Method",
    "Access-Control-Request-Headers"
  ],
  "allowedpaths":[
    "/content/_cq_graphql/global/endpoint.json",
    "/graphql/execute.json/.*"
  ]
}

エンドポイントのバニティーパスを設定した場合は、allowedpaths でも使用できます。

リファラーフィルター

CORS 設定に加えて、サードパーティホストからのアクセスを許可するために、リファラーフィルターを設定する必要があります。

それには、以下を行う適切な OSGi Referrer Filter 設定ファイルを追加します。

  • 信頼できる Web サイトのホスト名(allow.hosts または allow.hosts.regexp)を指定する。
  • この名前のホストに対するアクセスを許可する。

例えば、リファラー my.domain を持つリクエストにアクセスを許可するには、次の操作を行います。

{
    "allow.empty":false,
    "allow.hosts":[
      "my.domain"
    ],
    "allow.hosts.regexp":[
      ""
    ],
    "filter.methods":[
      "POST",
      "PUT",
      "DELETE",
      "COPY",
      "MOVE"
    ],
    "exclude.agents.regexp":[
      ""
    ]
}
注意

以下は顧客の責任で行う必要があります。

  • 信頼できるドメインにのみアクセスを許可する
  • 機密情報が公開されていないことを確認する
  • ワイルドカードの [*] 構文を使用しない。これを使用すると、GraphQL エンドポイントへの認証済みアクセスが無効になり、エンドポイントが世界中に公開されることになります。
注意

有効​になっているコンテンツフラグメントモデルから派生した)すべての GraphQL スキーマは、GraphQL エンドポイントを通じて読み取り可能です。

つまり、漏洩するおそれがあるので、機密データが使用可能になっていないことを確認する必要があります。例えば、これには、モデル定義のフィールド名として存在する可能性のある情報が含まれます。

認証

コンテンツフラグメントに対するリモート AEM GraphQL クエリの認証を参照してください。

FAQ

次のような質問が寄せられました。

  1. Q:「AEM 用 GraphQL API と Query Builder API の違いは何ですか?

    • A:「AEM GraphQL API は JSON 出力の完全な制御が可能であり、コンテンツをクエリするための業界標準になっています。今後、AEM GraphQL API への投資が計画されています。

チュートリアル - AEM ヘッドレスと GraphQL をはじめる前に

実践的なチュートリアルを探している場合は、AEM の GraphQL API を使用し、外部アプリで使用するコンテンツをヘッドレス CMS シナリオで構築して公開する方法を示す「AEM ヘッドレスと GraphQL をはじめる前に」のエンドツーエンドのチュートリアルをご覧ください。

このページ