GraphQL API の探索 explore-graphql-apis

Last update: Mon Jan 29 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

トピック：
Content Fragments
GraphQL API

作成対象：

Beginner
Developer

AEM の GraphQL API は、コンテンツフラグメントのデータをダウンストリームアプリケーションに公開する強力なクエリ言語を提供します。コンテンツフラグメントモデルは、コンテンツフラグメントで使用されるデータスキーマを定義します。コンテンツフラグメントモデルが作成または更新されるたびに、スキーマが解釈され、GraphQL API を構成する「グラフ」に追加されます。

この章では、「GraphiQL」という IDE を使用してコンテンツを収集する一般的な GraphQL クエリをいくつか見ていきます。 GraphiQL IDE を使用すると、返されるクエリとデータを素早くテストして調整できます。また、GraphiQL ではドキュメントへのアクセスも容易になり、どのようなメソッドがあるのかを簡単に学習して理解できます。

前提条件 prerequisites

このマルチパートチュートリアルでは、「コンテンツフラグメントのオーサリング」の手順が完了していることが想定されています。

目的 objectives

GraphiQL ツールを使用して、GraphQL 構文でクエリを作成する方法を学びます
コンテンツフラグメントのリストと単一のコンテンツフラグメントでクエリを実行する方法を学びます
特定のデータ属性をフィルタリングしてリクエストする方法を理解します
複数のコンテンツフラグメントモデルのクエリを結合する方法を理解します
GraphQL クエリを永続化する方法を学びます。

GraphQL エンドポイントを有効にする enable-graphql-endpoint

GraphQL エンドポイントは、コンテンツフラグメントに対してGraphQL API クエリを有効にするように設定する必要があります。

AEM の開始画面で、ツール／一般／GraphQL に移動します。

右上の「作成」をタップし、表示されたダイアログで次の値を入力します。

名前*：マイプロジェクトエンドポイント.
次により提供される GraphQL を使用… *：マイプロジェクト

GraphQL エンドポイントの作成

「作成」をクリックしてエンドポイントを保存します。

プロジェクト設定に基づいて作成された GraphQL エンドポイントでは、そのプロジェクトに属するモデルに対するクエリのみが有効になります。ここでは、人物および チーム モデルに対するクエリのみを使用できます。

note note
NOTE
また、グローバルエンドポイントを作成して、複数の設定をまたいでモデルに対するクエリを有効にすることもできます。これは、環境にセキュリティの脆弱性がもたらされ、AEM の管理が全体的に複雑になる可能性があるため、慎重に使用する必要があります。

これで、お使いの環境で 1 つの GraphQL エンドポイントが有効になりました。

GraphiQL IDE の使用

GraphiQL ツールを使用すると、開発者は現在の AEM 環境のコンテンツに対するクエリを作成およびテストできます。 GraphiQL ツールを使用すると、実稼働設定でクライアントアプリケーションで使用されるクエリを 永続化または保存 することができます。

次に、組み込みの GraphiQL IDE を使用してAEM の GraphQL API の機能を見ていきます。

AEM の開始画面で、ツール／一般／GraphQL クエリエディター に移動します。

GraphiQL IDE に移動

note note
NOTE
AEM の古いバージョンでは、GraphiQL IDE を使用できない場合があります。その場合は、次の説明に従って手動でインストールします。

右上で、エンドポイントが マイプロジェクトエンドポイント に設定されていることを確認します。

これにより、すべてのクエリで マイプロジェクト プロジェクトに作成されたモデルが対象となります。

コンテンツフラグメントのリストでのクエリ query-list-cf

共通の要件は、複数のコンテンツフラグメントでクエリを実行することです。

次のクエリをメインパネルに貼り付けます（コメントリストの置き換え）。

code language-graphql
`query allTeams { teamList { items { _path title } } }`

上のメニューにある再生ボタンを押してクエリを実行します。前の章で作成したコンテンツフラグメントの結果が表示されます。
title テキストの下にカーソルを合わせ、Ctrl +スペース キーを押してコードのヒントをトリガーします。 shortname および description をクエリに追加します。
再生ボタンをクリックしてクエリを再度実行すると、shortname と description の追加プロパティを含む結果が表示されます。

shortname は単純なプロパティで、description は複数行のテキストフィールドです。GraphQL API を使用すると、 html、markdown、json または plaintext など、様々な形式の結果から選択できます。

ネストされたフラグメントのクエリ

次に、クエリのテストでネストされたフラグメントを取得します。 チーム モデルが参照する人物モデルを思い出してください。

teamMembers プロパティ含めるをようにクエリを更新します。これは、フィールドから人物モデルへの フラグメント参照 フィールドです。次のように、人物モデルのプロパティを返すことができます。

code language-graphql
`query allTeams { teamList { items { _path title shortName description { plaintext } teamMembers { fullName occupation } } } }`

JSON 応答

code language-json

code language-json
`{ "data": { "teamList": { "items": [ { "_path": "/content/dam/my-project/en/team-alpha", "title": "Team Alpha", "shortName": "team-alpha", "description": { "plaintext": "This is a description of Team Alpha!" }, "teamMembers": [ { "fullName": "John Doe", "occupation": [ "Artist", "Influencer" ] }, { "fullName": "Alison Smith", "occupation": [ "Photographer" ] } ] } ] } } }`

{
    "data": {
        "teamList": {
        "items": [
            {
            "_path": "/content/dam/my-project/en/team-alpha",
            "title": "Team Alpha",
            "shortName": "team-alpha",
            "description": {
                "plaintext": "This is a description of Team Alpha!"
            },
            "teamMembers": [
                {
                "fullName": "John Doe",
                "occupation": [
                    "Artist",
                    "Influencer"
                ]
                },
                {
                "fullName": "Alison Smith",
                "occupation": [
                    "Photographer"
                ]
                }
              ]
        }
        ]
        }
    }
}

ネストされたフラグメントに対してクエリを実行できるのは、AEM GraphQL API の優れた機能です。この簡単な例ではネストが 2 レベルのみですが、フラグメントをさらにネストすることは可能です。例えば、人物に関連付けられた住所モデルがある場合、3 つのモデルすべてから 1 つのクエリでデータを返すことができます。

コンテンツフラグメントのリストのフィルタリング filter-list-cf

ここからは、プロパティ値に基づいて結果をコンテンツフラグメントのサブセットでフィルタリングする方法を見ていきましょう。

GraphiQL UI で次のクエリを入力します。

code language-graphql
`query personByName($name:String!){ personList( filter:{ fullName:{ _expressions:[{ value:$name _operator:EQUALS }] } } ){ items{ _path fullName occupation } } }`

上記のクエリは、システム内のすべての「人物」フラグメントに対して検索を実行します。クエリの先頭に追加されたフィルターにより、name フィールドと変数文字列 $nameで比較が行われます。

「クエリ変数」パネルに以下を入力します。

code language-json
`{"name": "John Doe"}`

クエリを実行する際、「人物」コンテンツフラグメントが John Doe の値を返すことが想定されます。

複雑なクエリをフィルタリングして作成する方法は他にも多数あります。詳しくは、「AEM での GraphQL の使用方法 - サンプルコンテンツとサンプルクエリ」をご覧ください。

上のクエリを強化してプロファイル画像を取得します。

code language-graphql

code language-graphql
`query personByName($name:String!){ personList( filter:{ fullName:{ _expressions:[{ value:$name _operator:EQUALS }] } } ){ items{ _path fullName occupation profilePicture{ ... on ImageRef{ _path _authorUrl _publishUrl height width } } } } }`

query personByName($name:String!){
  personList(
    filter:{
      fullName:{
        _expressions:[{
          value:$name
          _operator:EQUALS
        }]
      }
    }
  ){
    items{
      _path
      fullName
      occupation
      profilePicture{
        ... on ImageRef{
          _path
          _authorUrl
          _publishUrl
          height
          width

        }
      }
    }
  }
}

profilePicture はコンテンツ参照であり、画像であると想定されるので、組み込みの ImageRef オブジェクトが使用されます。これにより、参照されている画像に関する追加データ（width および heightなど）をリクエストできます。

単一のコンテンツフラグメントのクエリ query-single-cf

単一のコンテンツフラグメントに対して直接クエリを実行することもできます。 AEM のコンテンツは階層的に保存され、フラグメントの一意の識別子はフラグメントのパスに基づきます。

GraphiQL エディターに次のクエリを入力します。

code language-graphql
`query personByPath($path: String!) { personByPath(_path: $path) { item { fullName occupation } } }`

「クエリ変数」に以下を入力します。

code language-json
`{"path": "/content/dam/my-project/en/alison-smith"}`

クエリを実行し、単一の結果が返されることを確認します。

クエリの永続化 persist-queries

クエリとクエリから返された結果データに満足したら、次の手順はクエリを AEM に保存または永続化することです。永続クエリは、GraphQL API をクライアントアプリケーションに公開するための推奨されるメカニズムです。クエリが永続化されると、GET リクエストを使用してリクエストでき、Dispatcher および CDN レイヤーでキャッシュできます。そして、永続化されたクエリのパフォーマンスが大幅に向上します。永続クエリを使用すると、パフォーマンスのメリットに加えて、余計なデータが誤ってクライアントアプリケーションに公開されるのを防ぐことができます。永続クエリについて詳しくは、こちらを参照してください。

次に、2 つのシンプルなクエリを永続化します。これらは次の章で使用します。

GraphiQL IDE で次のクエリを入力します。

code language-graphql
`query allTeams { teamList { items { _path title shortName description { plaintext } teamMembers { fullName occupation } } } }`

クエリが機能することを確認します。

次に、「名前を付けて保存」をタップし、クエリ名 として all-teams と入力します。

クエリは、左パネルの「永続クエリ」に表示されます。
次に、永続クエリの横にある「…」をタップし、「URL をコピー」をタップしてパスをクリップボードにコピーします。

新しいタブを開き、コピーしたパスをブラウザーに貼り付けます。

code language-plain
`https://$YOUR-AEMasCS-INSTANCEID$.adobeaemcloud.com/graphql/execute.json/my-project/all-teams`

パスは上記のようになります。クエリの JSON 結果が返されたことを確認できます。

上記の URL の分類：

table 0-row-2 1-row-2 2-row-2 3-row-2
名前	説明
`/graphql/execute.json`	永続クエリのエンドポイント
`/my-project`	`/conf/my-project` のプロジェクト設定
`/all-teams`	永続クエリの名前

GraphiQL IDE に戻り、「+」ボタンを使って新しいクエリを永続化します

code language-graphql

code language-graphql
`query personByName($name: String!) { personList( filter: { fullName:{ _expressions: [{ value: $name _operator:EQUALS }] } }){ items { _path fullName occupation biographyText { json } profilePicture { ... on ImageRef { _path _authorUrl _publishUrl width height } } } } }`

query personByName($name: String!) {
  personList(
    filter: {
      fullName:{
        _expressions: [{
          value: $name
          _operator:EQUALS
        }]
      }
    }){
    items {
      _path
      fullName
      occupation
      biographyText {
        json
      }
      profilePicture {
        ... on ImageRef {
          _path
          _authorUrl
          _publishUrl
          width
          height
        }
      }
    }
  }
}