コンテンツフラグメントと共に使用する 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 API

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

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

  GraphQL.org を参照

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

  「Explore GraphQL」を参照

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

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

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

• graphql.org：

  • GraphQL の概要

  • GraphQL の仕様

• graphql.com：

  • ガイド

  • チュートリアル

  • 導入事例

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

• graphQL.org - Java

• GitHub の GraphQL Java

GraphQL 用語

GraphQL では次を使用します。

• クエリ

• スキーマとタイプ：

  • スキーマは、コンテンツフラグメントモデルに基づいて AEM で生成されます。
  • GraphQL では、スキーマを使用して、AEM 用 GraphQL の実装で使用可能なタイプと操作を提供します。

• フィールド

• GraphQL エンドポイント

  • GraphQL クエリに応答し、GraphQL スキーマへのアクセスを提供する AEM 内のパス。

  • 詳しくは、GraphQL エンドポイントの有効化を参照してください。

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

GraphQL クエリタイプ

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

• 1 つのエントリ

• エントリのリスト

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

• （キャッシュされる）永続的クエリ

GraphiQL IDE

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

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

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

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

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

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

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

権限

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

スキーマ生成

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

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

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

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

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

   

2. 対応する GraphQL スキーマ（GraphiQL 自動生成ドキュメントからの出力）:
   

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

   • そのうちの 3 つ（author、main、referencearticle）は、ユーザーが管理しています。

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

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

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

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

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

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

   1. Model-1 と Model-2 の GraphQL 型が生成されます。

2. 次に Content-Fragment-Model-2 を変更すると、

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

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

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

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

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

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

フィールド

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

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

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

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

• AEM 用 GraphQL が生成する多数のヘルパーフィールド

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

フィールドタイプ

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

ヘルパーフィールド

ユーザー生成フィールドのデータ型に加えて、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 では、次のスカラー型でグループ化された情報を公開します。

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

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

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

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

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

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

バリエーション

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

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

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

GraphQL 変数

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

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

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

### in query variables
{
    "variation": "Introduction"
}

GraphQL ディレクティブ

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

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

### 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 の拡張機能の詳細

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

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

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

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

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

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

  • モデル名（例：city）を使用します

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

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

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

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

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

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

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

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

  • コンテンツの場合：

    • _locale：言語を表示します（言語マネージャーに基づく）
      • 特定ロケールの複数のコンテンツフラグメントのサンプルクエリを参照してください
    • _metadata：フラグメントのメタデータを表示します
      • メタデータのサンプルクエリ - 「GB」という賞のメタデータのリストを参照してください
    • _model：コンテンツフラグメントモデル（パスとタイトル）のクエリを許可します
      • モデルからのコンテンツフラグメントモデルのサンプルクエリを参照してください
    • _path：リポジトリー内のコンテンツフラグメントへのパス
      • サンプルクエリ - 1 つの特定の都市フラグメントを参照してください
    • _reference：参照（リッチテキストエディターでのインライン参照など）を表示します
      • プリフェッチされた参照を含んだ複数のコンテンツフラグメントのサンプルクエリを参照してください
    • _variation：コンテンツフラグメント内の特定のバリエーションを表示します
      • サンプルクエリ - 名前付きバリエーションを持つすべての都市を参照してください

  • 操作の場合：

    • _operator：特定の演算子（EQUALS、EQUALS_NOT、GREATER_EQUAL、LOWER、CONTAINS、STARTS_WITH）を適用します
      • サンプルクエリ - 「Jobs」という名前を持たないすべての人物を参照してください
      • サンプルクエリ - _path が特定のプレフィックスで始まるすべてのアドベンチャーを参照してください
    • _apply：特定の条件（例：AT_LEAST_ONCE）を適用します
      • サンプルクエリ - 少なくとも 1 回は現れる項目を含んだ配列をフィルタリングを参照してください
    • _ignoreCase：クエリの実行時に大文字と小文字を区別しません
      • サンプルクエリ - 名前に SAN が含まれるすべての都市（大文字と小文字を区別しない場合）を参照してください

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

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

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

  • ネストされたフラグメントに特定のバリエーションが存在しない場合、 マスター バリエーションが返されます。

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

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

• CORS フィルター
• リファラーフィルター

認証

コンテンツフラグメントに対するリモート 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 をはじめる前に」のエンドツーエンドのチュートリアルをご覧ください。