AEM Delivery API を使用してコンテンツにアクセスする方法

AEM ヘッドレスデベロッパージャーニーのこのパートでは、GraphQL クエリを使用してコンテンツフラグメントのコンテンツにアクセスし、アプリにコンテンツをフィードする方法（ヘッドレス配信）について説明します。

これまでの説明内容

AEM ヘッドレスジャーニーの前のドキュメント、コンテンツをモデル化する方法では、AEM でのコンテンツモデリングの基本を説明しました。これで、コンテンツ構造をモデル化し、AEM コンテンツフラグメントモデルおよびコンテンツフラグメントを使用してその構造を実現する方法を理解できました。具体的には以下を達成できました。

  • コンテンツモデリングに関連する概念と用語を認識する。
  • ヘッドレスコンテンツ配信にコンテンツモデリングが必要な理由を理解する。
  • AEM コンテンツフラグメントモデルを使用してこの構造を実現する（およびコンテンツフラグメントを使用してコンテンツを作成する）方法を理解する。
  • コンテンツをモデル化する方法（原則と基本サンプル）を理解する。

この記事は、これらの基本事項に基づいているので、AEM GraphQL API を使用して AEM の既存のヘッドレスコンテンツにアクセスする方法を理解できます。

  • 対象読者：初心者
  • 目的：AEM GraphQL クエリを使用してコンテンツフラグメントのコンテンツにアクセスする方法を説明します。具体的な内容は次のとおりです。
    • GraphQL と AEM GraphQL API の概要を説明します。
    • AEM GraphQL API の詳細を説明します。
    • いくつかのサンプルクエリを通じて実際の動作を確認します。

コンテンツへのアクセス

（コンテンツフラグメントで）整然と構造化されたコンテンツがすべて用意されていて、それらが新しいアプリにフィードされるのを待つばかりだとします。問題は、どうやってコンテンツにアクセスするかです。

必要なのは、特定のコンテンツをターゲットにし、必要なものを選択してさらに処理するためにアプリに返す方法です。

Adobe Experience Manager （AEM）as a Cloud Service では、AEM GraphQL API を使用して、コンテンツフラグメントに選択的にアクセスし、必要なコンテンツのみを返すことができます。つまり、アプリケーションで使用する構造化コンテンツのヘッドレス配信を実現できることになります。

メモ

AEM GraphQL API はカスタマイズされた実装で、標準の GraphQL API 仕様に基づいています。

GraphQL - 概要

GraphQL は、次の機能を提供するオープンソース仕様です。

  • 構造化オブジェクトから特定のコンテンツを選択できるクエリ言語
  • 構造化コンテンツに対してこれらのクエリを実行するためのランタイム

GraphQL は、厳密に​型指定された API です。つまり、すべての​コンテンツが型別に明確に構造化および編成されている必要があります。その結果、アクセスする対象と方法を GraphQL が​認識​できるようになります。データフィールドは、コンテンツオブジェクトの構造を定義する GraphQL スキーマ内で定義されます。

次に、GraphQL クエリに応答するパスを GraphQL エンドポイントが提供します。

つまり、AEM と組み合わせて使用する際に必要なコンテンツだけを、アプリが正確に確実かつ効率的に選択できるということです。

メモ

詳しくは、GraphQL.org や GraphQL.com を参照してください。

AEM GraphQL API

AEM GraphQL API は、標準の GraphQL API 仕様に基づくカスタマイズバージョンで、コンテンツフラグメントに対して（複雑な）クエリを実行できるように特別に設定されたものです。

コンテンツは、コンテンツフラグメントモデルに従って構造化されているので、コンテンツフラグメントが使用されます。これは GraphQL の基本要件を満たしています。

  • コンテンツフラグメントモデルは、1 つ以上のフィールドで構成されます。
    • 各フィールドは、データタイプに従って定義されます。
  • コンテンツフラグメントモデルは、対応する AEM GraphQL スキーマの生成に使用されます。

AEM（およびコンテンツ）の GraphQL に実際にアクセスするには、エンドポイントを使用してアクセスパスを指定します。

AEM GraphQL API を使用して返されたコンテンツは、アプリケーションで使用できます。

クエリを直接入力およびテストできるように、標準の GraphQL インターフェイスの実装も AEM GraphQL で使用できます（これは AEM と共にインストールできます）。構文のハイライト表示、オートコンプリート、自動候補表示などの機能と共に、履歴およびオンラインドキュメントが用意されています。

メモ

AEM GraphQL API の実装は、GraphQL Java ライブラリに基づいています。

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

コンテンツフラグメントは、次の理由により、AEM スキーマおよびクエリ用の GraphQL の基盤となります。

  • ヘッドレスに配信できる、ページに依存しないコンテンツの設計、作成、キュレーションおよび公開が可能になります。
  • 選択したデータタイプを使用して、生成されるフラグメントの構造を事前に定義するコンテンツフラグメントモデルに基づいています。
  • モデルの定義時に使用できるフラグメント参照データタイプを使用して、構造のレイヤーを追加できます。

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

コンテンツフラグメントモデルは、

  • 有効​にされると、スキーマの生成に使用されます。
  • GraphQL に必要なデータタイプとフィールドを提供します。アプリケーションが、可能なことだけを要求して期待するものを受け取るようにします。
  • データタイプ​フラグメント参照​は、別のコンテンツフラグメントを参照するためにモデル内で使用できるので、構造レベルを追加します。

フラグメント参照

フラグメント参照​は、

  • コンテンツフラグメントモデルの定義時に使用できる特定のデータタイプです。

  • 特定のコンテンツフラグメントモデルに依存する別のフラグメントを参照します。

  • 構造化データを作成したあと取得できます。

    • マルチフィード​として定義した場合、複数のサブフラグメントをプライムフラグメントで参照（取得）できます。

JSON プレビュー

コンテンツフラグメントモデルの設計と開発に役立てるため、コンテンツフラグメントエディターで JSON 出力をプレビューできます。

JSON プレビュー

AEM GraphQL API を実際に使用する

初期セットアップ

コンテンツに関するクエリを開始する前に、次の操作が必要です。

サンプル構造

AEM GraphQL API をクエリで実際に使用するにあたって、次のような非常に基本的な 2 つのコンテンツフラグメントモデル構造を例として使用できます。

  • 会社
    • 名前 - テキスト
    • CEO（人）- フラグメント参照
    • 従業員（人）- フラグメント参照（複数可）
  • 人
    • 名前 - テキスト
    • 名前（名）- テキスト

ご覧のように、「CEO」フィールドと「従業員」フィールドは、「人」フラグメントを参照しています。

フラグメントモデルが使用されるのは、次の場合です。

  • コンテンツフラグメントエディターでコンテンツを作成する場合
  • クエリの実行対象となる GraphQL スキーマを生成する場合

クエリのテスト場所

クエリは、GraphiQL インターフェイスで入力できます。クエリエディターには、次のいずれかの方法でアクセスできます。

  • ツール／一般／GraphQL クエリエディター
  • 直接アクセス（例：http://localhost:4502/aem/graphiql.html）
GraphiQL インターフェイス

クエリの概要

わかりやすいクエリとしては、「会社」スキーマ内のすべてのエントリの名前を返す場合があります。以下では、すべての会社名のリストをリクエストします。

query {
  companyList {
    items {
      name
    }
  }
}

もう少し複雑なクエリとしては、「Jobs」という名前を持たないすべての人を選択する場合があります。以下では、「Jobs」という名前を持たないすべての人を抜き出します。これは EQUALS_NOT 演算子で実現します（演算子は他にも多数あります）。

query {
  personList(filter: {
    name: {
      _expressions: [
        {
          value: "Jobs"
          _operator: EQUALS_NOT
        }
      ]
    }
  }) {
    items {
      name
      firstName
    }
  }
}

また、もっと複雑なクエリを作成することもできます。例えば、「Smith」という名前の従業員が 1 人以上いるすべての会社をクエリする場合です。以下のクエリでは、「Smith」という名前の人を抜き出し、ネストされたフラグメントから取得した情報を返します。

query {
  companyList(filter: {
    employees: {
      _match: {
        name: {
          _expressions: [
            {
              value: "Smith"
            }
          ]
        }
      }
    }
  }) {
    items {
      name
      ceo {
        name
        firstName
      }
      employees {
        name
        firstName
      }
    }
  }
}

AEM GraphQL API の使用と必要な要素の設定について詳しくは、次のドキュメントを参照してください。

  • AEM での GraphQL の使用方法
  • サンプルコンテンツフラグメント構造
  • AEM での GraphQL の使用方法 - サンプルコンテンツとサンプルクエリ

次の手順

これで、AEM GraphQL API を使用してヘッドレスコンテンツにアクセスしクエリを実行する方法について説明します。次は、REST API を使用してコンテンツフラグメントのコンテンツにアクセスしコンテンツを更新する方法について説明します。

その他のリソース

このページ