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

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

AEMは、コンテンツフラグメントと共に使用されるCloud ServiceGraphQL APIとして、標準のオープンソースのGraphQL APIに大きく基づいています。

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

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

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

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種類のエンドポイントがあります。

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

コンテンツフラグメントエディターでは、あるテナントのコンテンツフラグメントが別のテナントのコンテンツフラグメントを(ポリシーを介して)参照できるようにします。

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

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

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 と共にインストールできます。

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

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

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

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

GraphiQL インターフェイス

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

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

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

使用例は、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で使用できる3つのフレーバーがあります。onlyDateonlyTimedateTime
列挙 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 サービスや中間ステップにとってパラメーターが大きくなりすぎるという重大なリスクがあります。

持続的なクエリは、常に適切な(テナント)構成に関連するエンドポイントを使用する必要があります。そのため、どちらかまたは両方を使用できます。

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

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

適切なテナント構成に対して、GraphQL Persistenceクエリ​を有効にする必要があります。

例えば、my-queryという名前の特定のクエリがあり、テナント構成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転送者フィルタ設定ファイルを追加することで行います。

  • 信頼できる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 をはじめる前に」のエンドツーエンドのチュートリアルをご覧ください。

このページ

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now