コンテンツフラグメントと共に使用する AEM GraphQL API graphql-api-for-use-with-content-fragments
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 クエリへの応答としてレンダリングに必要なものだけを一括配信
- AEM Commerce が、GraphQL 経由でコマースプラットフォームのデータを使用する。
- AEM コンテンツフラグメントが、AEM GraphQL API（標準の GraphQL に基づくカスタム実装）と連携して、アプリケーションで使用するための構造化コンテンツを配信する。
GraphQL API 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-terminology
GraphQL では次を使用します。
-
- スキーマは、コンテンツフラグメントモデルに基づいて AEM で生成されます。
- GraphQL では、スキーマを使用して、AEM 用 GraphQL の実装で使用可能なタイプと操作を提供します。
-
-
GraphQL クエリに応答し、GraphQL スキーマへのアクセスを提供する AEM 内のパス。
-
詳しくは、GraphQL エンドポイントの有効化を参照してください。
-
ベストプラクティスを含む包括的な詳細については、「(GraphQL.org) GraphQL の概要」を参照してください。
GraphQL クエリタイプ graphql-query-types
GraphQL では、次のいずれかを返すクエリを実行できます。
-
1 つのエントリ
AEM は、クエリ（両方のタイプ）を Dispatcher と CDN によってキャッシュできる永続クエリに変換する機能を提供します。
GraphQL クエリのベストプラクティス（Dispatcher と CDN） graphql-query-best-practices
永続クエリは、パブリッシュインスタンスで次のように使用することをお勧めします。
- キャッシュされます
- AEM as a Cloud Service で一元管理されます
POST リクエストを使用する GraphQL クエリは、キャッシュされないのでお勧めしません。そのため、デフォルトのインスタンスでは、Dispatcher はそれらのクエリをブロックするように設定されています。
GraphQL は GET リクエストもサポートしていますが、これらは制限（URL の長さなど）に達する可能性があり、永続クエリを使用することで回避できます。
詳しくは、永続クエリのキャッシュの有効化を参照してください。
ENABLE_GRAPHQL_ENDPOINTという Cloud Manager環境変数の作成- （値：
true）
GraphiQL IDE graphiql-ide
また、GraphiQL IDE を使用して、GraphQL クエリのテストとデバッグを行うこともできます。
オーサー、プレビュー、パブリッシュの使用例 use-cases-author-preview-publish
使用例は、AEM as a Cloud Service 環境のタイプに応じて異なる場合があります。
-
パブリッシュ環境の使用目的：
- JS アプリケーションのデータのクエリ（標準の使用例）
-
オーサー環境の使用目的：
- パブリッシュ環境にデプロイする前にクエリをプレビューする
- JS アプリケーションのデータのクエリ（標準の使用例）
- パブリッシュ環境にデプロイする前にクエリをプレビューする
-
オーサー環境の使用目的：
-
「コンテンツ管理用」のデータのクエリ：
- AEM as a Cloud Service の GraphQL は現在読み取り専用の API です。
- REST API は、CR(U)D の操作に使用できます。
-
権限 permission
Assets へのアクセスに必要な権限です。
GraphQL クエリは、基になるリクエストの AEM ユーザーの権限で実行します。一部のフラグメント（Assets として保存）への読み取りアクセス権を持っていない場合、ユーザーは結果セットの一部になりません。
また、ユーザーが GraphQL クエリを実行するには、GraphQL エンドポイントへのアクセス権が必要です。
スキーマ生成 schema-generation
GraphQL は、厳密に型指定された API です。つまり、データは型別に明確に構造化され編成される必要があります。
GraphQL の仕様には、特定のインスタンス上のデータをクエリするための堅牢な API を作成する方法に関する一連のガイドラインが用意されています。これを行うには、クライアントは、クエリに必要なすべての型が定義されたスキーマを取得する必要があります。
コンテンツフラグメントの場合、GraphQL スキーマ（構造とタイプ）は、有効 なコンテンツフラグメントモデルとそれらのデータタイプに基づいています。
例えば、ユーザーが Article というコンテンツフラグメントモデルを作成した場合、AEM は GraphQL タイプ ArticleModel を生成します。このタイプに含まれるフィールドは、モデルで定義されているフィールドとデータタイプに対応しています。さらに、articleByPath や articleList など、このタイプで動作するクエリのいくつかのエントリポイントを作成します。
-
コンテンツフラグメントモデル：
-
対応する GraphQL スキーマ（GraphiQL 自動生成ドキュメントからの出力）:
この図では、生成された型
ArticleModelに複数のフィールドが含まれていることがわかります。-
そのうちの 3 つ（
author、main、referencearticle）は、ユーザーが管理しています。 -
その他のフィールドは AEM によって自動的に追加され、特定のコンテンツフラグメントに関する情報を提供するための便利な方法を表しています。この例では、（ヘルパーフィールド）
_path、_metadata、_variationsです。
-
-
ユーザーが Article モデルに基づいてコンテンツフラグメントを作成すると、GraphQL を使用してそれをクエリできます。例については、（GraphQL で使用するコンテンツフラグメント構造のサンプルに基づいた）サンプルクエリを参照してください。
AEM 用 GraphQL では、スキーマには柔軟性があります。つまり、コンテンツフラグメントモデルを作成、更新、削除するたびに、スキーマが自動生成されます。また、コンテンツフラグメントモデルを更新すると、データスキーマキャッシュも更新されます。
また、コンテンツフラグメントモデルを更新すると、データスキーマキャッシュも更新されます。
Sites GraphQL サービスは、コンテンツフラグメントモデルに対する変更を（バックグラウンドで）リッスンします。更新が検出されると、スキーマのその部分だけが再生成されます。この最適化により、時間が節約され、安定性も確保されます。
例えば、次のようになります。
-
Content-Fragment-Model-1とContent-Fragment-Model-2を含んだパッケージをインストールすると、Model-1およびModel-2の GraphQL タイプが生成されます。
-
次に
Content-Fragment-Model-2を変更すると、-
Model-2GraphQL 型だけが更新されます。 -
一方、
Model-1は同じままです。
-
スキーマは、GraphQL クエリと同じエンドポイントを通じて提供され、クライアントはスキーマが拡張子 GQLschema で呼び出されることに対処します。例えば、/content/cq:graphql/global/endpoint.GQLschema で単純な GET リクエストを実行すると、text/x-graphql-schema;charset=iso-8859-1 の Content-type を持つスキーマが出力されます。
スキーマの生成 - 未公開のモデル schema-generation-unpublished-models
コンテンツフラグメントがネストされると、親のコンテンツフラグメントモデルは公開されますが、参照モデルは公開されません。
この場合、AEM は親コンテンツフラグメントモデルの 不完全な スキーマを生成します。つまり、非公開のモデルに依存するフラグメント参照がスキーマから削除されます。
フィールド fields
スキーマ内には、次の 2 つの基本的なカテゴリに属する個々のフィールドがあります。
データタイプ data-types
AEM 用 GraphQL では一連のタイプをサポートしています。サポートされているすべてのコンテンツフラグメントモデルデータ型と、それに対応する GraphQL 型を以下の表に示します。
String、[String]String、[String]Float、[Float]BooleanCalendaronlyDate、onlyTime、dateTime の 3 つです。String[String]String、[String]String、[String]単一のフィールド：
Model - 直接参照されるモデル型マルチフィールド（1 つの参照タイプ）：
[Model] - 型の配列 Model（配列から直接参照）複数の参照型を持つマルチフィールド：
[AllFragmentModels] - 和集合型を持つ配列から参照される、すべてのモデル型の配列単一のフィールド：
Model - 直接参照されるモデル型マルチフィールド（1 つの参照タイプ）：
[Model] - 型の配列 Model（配列から直接参照）複数の参照型を持つマルチフィールド：
[AllFragmentModels] - 和集合型を持つ配列から参照される、すべてのモデル型の配列ヘルパーフィールド helper-fields
ユーザー生成フィールドのデータ型に加えて、AEM 用 GraphQL では、コンテンツフラグメントの識別やコンテンツフラグメントに関する追加情報の提供に役立つ多数の ヘルパー フィールドも生成されます。
これらのヘルパーフィールドは、ユーザーが定義したものと自動生成されたものを区別するために、先頭に _ が付きます。
パス path
パスフィールドは、AEM GraphQL で識別子として使用され、AEM リポジトリ内のコンテンツフラグメントアセットのパスを表します。これをコンテンツフラグメントの識別子として選択した理由は次のとおりです。
- AEM 内で一意である
- 取得しやすい
次のコードでは、WKND チュートリアルで提供されているように、コンテンツフラグメントモデル Author に基づいて作成されたすべてのコンテンツフラグメントのパスを表示します。
{
authorList {
items {
_path
}
}
}
特定のタイプのコンテンツフラグメントを 1 つ取得するには、まずそのパスも決定する必要があります。例：
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
item {
_path
firstName
lastName
}
}
}
サンプルクエリ - ある 1 つの特定の都市フラグメントを参照してください。
ID （UUID） id-uuid
ID フィールドは、AEM GraphQLの識別子としても使用されます。 これは、AEM リポジトリ内のコンテンツフラグメントアセットのパスを表しますが、実際のパスを保持する代わりに、リソースを表す UUID を保持します。 これをコンテンツフラグメントの識別子として選択した理由は次のとおりです。
- AEM 内で一意である
- 容易に取得でき、
- リソースを移動しても変更されません。
コンテンツフラグメントおよび参照されるコンテンツフラグメントまたはアセットの UUID は、JSON プロパティリク _id ストを介して返すことができます。
{
articleList {
items {
_id
_path
}
}
}
メタデータ metadata
また、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 型メタデータをクエリすることになります。
メタデータをクエリするには、次のようにします。
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
item {
_metadata {
stringMetadata {
name
value
}
}
}
}
}
生成された GraphQL スキーマを表示するには、すべてのメタデータ GraphQL 型を表示します。すべてのモデルタイプは同じ TypedMetaData を持ちます。
StringMetadata と StringArrayMetadata はどちらも、リポジトリに格納されているものについての指定であり、その取得手段についての指定ではありません。stringMetadata フィールドを呼び出すと、リポジトリに String として格納されているすべてのメタデータの配列を受け取ることになります。一方、stringArrayMetadata を呼び出すと、リポジトリに String[] として格納されているすべてのメタデータの配列を受け取ります。詳しくは、メタデータのサンプルクエリ - 「GB」という賞のメタデータのリストを参照してください。
バリエーション variations
コンテンツフラグメントのバリエーションに対するクエリを簡略化するために、_variations フィールドが実装されています。例：
{
authorByPath(_path: "/content/dam/wknd-shared/en/contributors/ian-provo") {
item {
_variations
}
}
}
_variations」フィールドには master バリエーションが含まれません。詳しくは、サンプルクエリ - 名前付きバリエーションを持つすべての都市を参照してください。
GraphQL 変数 graphql-variables
GraphQL では、クエリに変数を含めることができます。詳細情報は、変数に関する GraphQL のドキュメントを参照してください。
例えば、特定のバリエーション（利用可能な場合）でタイプ Author のコンテンツフラグメントをすべて取得するには、GraphiQL で引数 variation を指定できます。
クエリ：
query($variation: String!) {
authorList(variation: $variation) {
items {
_variation
lastName
firstName
}
}
}
クエリ変数：
{
"variation": "another"
}
このクエリは、作成者の完全なリストを返します。another バリエーションのない作成者は、元のデータに戻ります（この場合、_variation は master をレポートします）。
指定されたバリエーションを提供する作成者にリストを制限する（元のデータにフォールバックする作成者をスキップする）場合は、フィルターを適用する必要があります。
query($variation: String!) {
authorList(variation: $variation, filter: {
_variation: {
_expressions: {
value: $variation
}
}
}) {
items {
_variation
lastName
firstName
}
}
}
GraphQL ディレクティブ graphql-directives
GraphQL では、GraphQL ディレクティブと呼ばれる変数に基づいてクエリを変更する可能性があります。
例えば、変数 includePrice に基づいて、すべての AdventureModels のクエリに adventurePrice フィールドを含めることができます。
クエリ：
query GetAdventureByType($includePrice: Boolean!) {
adventureList {
items {
title
price @include(if: $includePrice)
}
}
}
クエリ変数：
{
"includePrice": true
}
フィルタリング filtering
GraphQL クエリでフィルタリングを使用して、特定のデータを返すこともできます。
フィルタリングでは、論理演算子と論理式に基づいた構文を使用します。
最もアトミックな部分は、特定のフィールドの内容に適用できる単一の式です。フィールドの内容を指定された定数値と比較します。
例えば、次の式
{
value: "some text"
_op: EQUALS
}
は、フィールドの内容を値 some text と比較し、内容が値と等しい場合に成功します。そうしないと、式は失敗します。
次の演算子を使用して、フィールドを特定の値と比較できます。
EQUALSString、ID、BooleanEQUALS_NOTString、IDCONTAINSString{ value: "mas", _op: CONTAINS } は Christmas、Xmas、master などと一致）CONTAINS_NOTStringSTARTS_WITHID{ value: "/content/dam/", _op: STARTS_WITH は /content/dam/path/to/fragment と一致するが、/namespace/content/dam/something とは一致しない）EQUALInt、FloatUNEQUALInt、FloatGREATERInt、FloatGREATER_EQUALInt、FloatLOWERInt、FloatLOWER_EQUALInt、FloatATCalendar、Date、TimeNOT_ATCalendar、Date、TimeBEFORECalendar、Date、TimeAT_OR_BEFORECalendar、Date、TimeAFTERCalendar、Date、TimeAT_OR_AFTERCalendar、Date、Timeまた、次のように式の評価方法を変更する追加のオプションを指定できるタイプもあります。
_ignoreCaseStringtime の値は TIME、time、tImE …に一致）_sensitivenessFloatfloat 値が同じと見なされるための一定のマージンを許可します（float 値の内部表現による技術的な制限を回避するため）。このオプションはパフォーマンスに悪影響を及ぼす可能性があるので、避ける必要があります。式は、論理演算子（_logOp）を使用して設定に組み合わせることができます。
OR- 少なくとも 1 つの式が成功した場合、式のセットは成功しますAND- すべての式が成功した場合、式のセットは成功します（デフォルト）
各フィールドは、独自の式セットでフィルタリングできます。 フィルター引数で指定されたすべてのフィールドの式セットは、最終的に独自の論理演算子で結合されます。
フィルター定義（filter 引数としてクエリに渡される）には次が含まれます。
- 各フィールドのサブ定義（フィールド名を使用してアクセスできます。例えば、データ（フィールド）タイプの
lastNameフィールドのフィルターにはlastNameフィールドがあります） - 各サブ定義には、式セットを提供する
_expressions配列と、式を組み合わせる必要がある論理演算子を定義する_logOpフィールドが含まれます - 各式は、値（
valueフィールド）と演算子（_operatorフィールド）によって定義され、フィールドの内容を比較する必要があります
項目を AND で組み合わせたい場合は _logOp を省略できます。また、等価性を確認したい場合は、これらがデフォルト値になるので、_operator を省略できます。
次の例は、大文字と小文字を区別せずに、Provo が lastName である、または sjö を含むすべてのユーザーをフィルタリングする完全なクエリを示しています。
{
authorList(filter: {
lastname: {
_logOp: OR
_expressions: [
{
value: "sjö",
_operator: CONTAINS,
_ignoreCase: true
},
{
value: "Provo"
}
]
}
}) {
items {
lastName
firstName
}
}
}
ネストされたフィールドに対してフィルターを適用することもできますが、パフォーマンスの問題が発生する可能性があるため、お勧めしません。
その他の例については、以下を参照してください。
-
- さらに、サンプルクエリ用に準備されているサンプルコンテンツおよび構造
並べ替え sorting
この機能を使用すると、指定したフィールドに従ってクエリ結果を並べ替えることができます。
並び替え条件：
-
フィールドパスを表すコンマ区切りの値のリストにする
- リストの最初のフィールドではプライマリの並び替え順を定義し、2 番目のフィールドではプライマリの並び替え条件の 2 つの値が等しい場合に使用し、3 番目のフィールドでは最初の 2 つの条件が等しい場合などに使用されます。
- ドット表記（field1.subfield.subfield など）
-
（オプション）並べ替えの方向
- ASC（昇順）または DESC（降順）。デフォルトでは ASC が適用されます
- 並べ替えの方向は、フィールドごとに指定できます。つまり、あるフィールドを昇順で、別のフィールドを降順（name、firstName DESC）で並べ替えることができます
例：
query {
authorList(sort: "lastName, firstName") {
items {
firstName
lastName
}
}
}
次のようにすることもできます。
{
authorList(sort: "lastName DESC, firstName DESC") {
items {
lastName
firstName
}
}
}
また、nestedFragmentname.fieldname の形式を使用して、ネストされたフラグメント内のフィールドで並べ替えることもできます。
例：
query {
articleList(sort: "authorFragment.lastName") {
items {
title
authorFragment {
firstName
lastName
birthDay
}
slug
}
}
}
ページング paging
この機能を使用すると、リストを返すクエリタイプに対してページングを実行できます。次の 2 つの方法があります。
ListクエリのoffsetとlimitPaginatedクエリのfirstとafter
リストクエリ - オフセットと制限 list-offset-limit
...List クエリでは、offset と limit を使用して、特定の結果サブセットを返すことができます。
offset：返される最初のデータセットを指定しますlimit：返されるデータセットの最大数を指定します
例えば、完全な 結果リストの 5 番目の記事から開始して、最大 5 つの記事を含む結果のページを出力するには、次のようにします。
query {
articleList(offset: 5, limit: 5) {
items {
authorFragment {
lastName
firstName
}
}
}
}
-
ページングには安定した並べ替え順序が必要です。同じ結果セットの異なるページをリクエストする複数のクエリで正しく動作するようにします。デフォルトでは、結果セットの各アイテムのリポジトリパスを使用して、順序が常に同じであることを確認します。 異なる並べ替え順を使用し、その並べ替えを JCR クエリレベルで実行できない場合、ページを決定する前に結果セット全体をメモリに読み込む必要があるので、パフォーマンスに悪影響が生じます。
-
オフセットが大きいほど、JCR クエリの結果セット全体から項目をスキップするのに時間がかかります。 大規模な結果セットに対する代替ソリューションは、
firstおよびafterメソッドでページ分割されたクエリを使用することです。
ページ分割されたクエリ - first と after paginated-first-after
...Paginated クエリタイプは、ほとんどの ...List クエリタイプの機能（フィルタリング、並べ替え）を再利用しますが、offset／limit 引数の代わりに、GraphQL カーソル接続仕様で定義されている first／after 引数を使用します。GraphQL の概要では、堅苦しくない概要を見つけることができます。
first：返される最初のn個の項目。
デフォルトは、50です。
最大値は100です。after：リクエストされたページの先頭を決定するカーソル。カーソルで表される項目は結果セットに含まれないことに注意してください。項目のカーソルは、edges構造体のcursorフィールドによって決定されます。
例えば、完全な 結果リスト内の指定されたカーソル項目から開始して、最大 5 つの冒険を含む結果のページを出力します。
query {
adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
edges {
cursor
node {
title
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
-
デフォルトのページングでは、結果の順序が常に同じになるように、フラグメントを表すリポジトリノードの UUID を順序付けに使用します。
sortを使用すると、UUID は一意の並べ替えを保証するために暗黙的に使用されます。同じ並べ替えキーを持つ 2 つの項目の場合も同様です。 -
内部の技術的な制約により、ネストされたフィールドに並べ替えとフィルタリングを適用すると、パフォーマンスが低下します。したがって、ルートレベルで保存されたフィールドのフィルター／並べ替えを使用することをお勧めします。 これは、ページ分割された大きな結果セットをクエリする場合にも推奨される方法です。
GraphQL クエリでの Web に最適化された画像配信 web-optimized-image-delivery-in-graphql-queries
Web に最適化された画像配信を使用すると、GraphQL クエリを使用して次のことができます。
-
DAM アセット画像への URL をリクエストします（コンテンツリファレンス によって参照）
-
画像の特定のレンディションが自動的に生成されて返されるように、クエリでパラメーターを渡す
note note NOTE 指定されたレンディションは AEM Assets に保存されません。レンディションは生成され、短期間キャッシュに保持されます。 -
JSON 配信の一部として URL を返す
AEM を使用して、次のことができます。
- Web に最適化された画像配信を GraphQL クエリに渡す。
つまり、クエリの実行中に、これらの画像に対する GET リクエストの URL パラメーターと同じ方法でコマンドが適用されます。
これにより、JSON 配信の画像レンディションを動的に作成できるので、これらのレンディションを手動で作成してリポジトリに保存する必要がなくなります。
GraphQL のソリューションでは、次のことが可能です。
-
URL のリクエスト：
ImageRefの参照で_dynamicUrlを使用 -
パラメーターを渡す：フィルターが定義されているリストヘッダーに
_assetTransformを追加
_dynamicUrl：DAM アセット_dmS7Url：Dynamic Media アセット
変換リクエストの構造 structure-transformation-request
AssetTransform（_assetTransform）は、URL 変換リクエストの作成に使用されます。
構造と構文は次のとおりです。
-
format：拡張子でサポートされるすべての形式を持つ列挙（GIF、PNG、PNG8、JPG、PJPG、BJPG、WEBP、WEBPLL、WEBPLY） -
seoName：ノード名の代わりにファイル名として使用される文字列 -
crop：フレームサブ構造。幅または高さが省略された場合、高さまたは幅が同じ値として使用されますxOrigin：フレームの x 原点（必須）yOrigin：フレームの y 原点（必須）width：フレームの幅height：フレームの高さ
-
size：寸法サブ構造。幅または高さが省略された場合、高さまたは幅が同じ値として使用されますwidth：寸法の幅height：寸法の高さ
-
rotation：サポートされているすべての回転の列挙（R90、R180、R270） -
flip：HORIZONTAL、VERTICAL、HORIZONTAL_AND_VERTICAL の列挙 -
quality：画質の割合を示す 1～100 の整数 -
width：出力画像の幅を定義する整数ですが、画像ジェネレーターでは無視されます -
preferWebp：webp が優先されるかどうかを示すブール値（デフォルト値は false）
URL 変換は、パス別、リスト別またはページ分割別のすべてのクエリタイプで使用できます。
すべてのパラメーターを使用した web に最適化された画像配信 web-optimized-image-delivery-full-parameters
すべてのパラメーターを使用したクエリ例を次に示します。
{
articleList(
_assetTransform: {
format:GIF
seoName:"test"
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
単一のクエリ変数を使用した web に最適化された画像配信 web-optimized-image-delivery-single-query-variable
単一のクエリ変数を使用した例を次に示します。
query ($seoName: String!) {
articleList(
_assetTransform: {
format:GIF
seoName:$seoName
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
複数のクエリ変数を使用した web に最適化された画像配信 web-optimized-image-delivery-multiple-query-variables
複数のクエリ変数を使用した例を次に示します。
query ($seoName: String!, $format: AssetTransformFormat!) {
articleList(
_assetTransform: {
format:$format
seoName:$seoName
crop:{
xOrigin:10
yOrigin:20
width:50
height:45
}
size:{
height:100
width:200
}
rotation:R90
flip:HORIZONTAL_AND_VERTICAL
quality:55
width:123
preferWebp:true
}
) {
items {
_path
featuredImage {
... on ImageRef {
_dynamicUrl
}
}
}
}
}
URL による web に最適化された画像配信リクエスト web-optimized-image-delivery-request-url
クエリを永続化クエリとして保存した場合（例えば dynamic-url-x という名前を使用）、永続化クエリを直接実行できます。
例えば、以前のサンプル（永続化されたクエリとして保存）を直接実行するには、次の URL を使用します。
-
単一のパラメーター、
dynamic-url-xという名前の永続クエリ-
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic-url-x;seoName=xxx応答は次のようになります。
-
-
複数のパラメーター、
dynamicという名前の永続クエリ-
http://localhost:4502/graphql/execute.json/wknd-shared/dynamic;seoName=billiboy;format=GIF;note caution CAUTION 末尾の ;は、パラメーターのリストを明確に終了するために必須です。
-
Web に最適化された画像配信に関する制限事項 web-optimized-image-delivery-limitations
次の制限があります。
-
クエリのすべての画像部分に適用される修飾子（グローバルパラメーター）
-
ヘッダーのキャッシュ
- オーサーにキャッシュされない
- パブリッシュのキャッシュ - 10 分の最大経過時間（クライアントは変更できません）
GraphQL クエリでの URL による Dynamic Media アセット配信 dynamic-media-asset-delivery-by-url
AEM コンテンツフラグメント用の GraphQL を使用すると、AEM Dynamic Media（Scene7）アセット（コンテンツ参照 で参照される）への URL をリクエストできます。
GraphQL のソリューションでは、次のことが可能です。
-
ImageRef参照で_dmS7Urlを使用する -
複数の参照（
ImageRef、MultimediaRef、DocumentRef）で_dmS7Urlを使用する -
スマート切り抜き機能で
_dmS7Urlを使用する-
_smartCropsプロパティは、特定のアセットで使用できるスマート切り抜き設定を公開します
-
dam:scene7File 属性と dam:scene7Domain 属性がアセットのメタデータに追加されます。_dmS7Url：Dynamic Media アセット_dynamicUrl：DAM アセット
URL による Dynamic Media アセット配信のサンプルクエリ - 画像参照 sample-query-dynamic-media-asset-delivery-by-url-imageref
サンプルクエリを以下に示します。
teamとpersonタイプの複数のコンテンツフラグメントの場合、ImageRefを返します
query allTeams {
teamList {
items {
_path
title
teamMembers {
fullName
profilePicture {
__typename
... on ImageRef{
_dmS7Url
height
width
}
}
}
}
}
}
URL による Dynamic Media アセット配信のサンプルクエリ - 複数の参照 sample-query-dynamic-media-asset-delivery-by-url-multiple-refs
サンプルクエリを以下に示します。
teamとpersonタイプの複数のコンテンツフラグメントの場合、ImageRef、MultimediaRef、DocumentRefを返します。
query allTeams {
teamList {
items {
_path
title
teamMembers {
fullName
profilePicture {
__typename
... on ImageRef{
_dmS7Url
height
width
}
}
featureVideo {
__typename
... on MultimediaRef{
_dmS7Url
size
}
}
about-me {
__typename
... on DocumentRef{
_dmS7Url
_path
}
}
}
}
}
}
URL による Dynamic Media アセット配信のサンプルクエリ - スマート切り抜きの使用 sample-query-dynamic-media-asset-delivery-by-url-smart-crop
サンプルクエリを以下に示します。
- リクエストされたアセットで使用できるスマート切り抜き設定を公開するには
query allTeams {
teamList {
items {
title
teamMembers {
profilePicture {
... on ImageRef {
height
width
_dmS7Url
_smartCrops {
width
height
name
}
}
}
}
}
}
}
AEM 用の GraphQL - 拡張機能の概要 graphql-extensions
AEM 用の GraphQL でのクエリの基本操作は、標準の GraphQL 仕様に従います。AEM での GraphQL クエリには、次のような拡張機能があります。
-
結果が 1 つだけ必要な場合：
- 市区町村などのモデル名を使用します。
-
結果のリストを想定している場合：
- モデル名に
Listを付け加えます（例：cityList） - サンプルクエリ - すべての都市に関するすべての情報を参照してください
これにより、以下のことが可能になります。
-
ASC: 昇順DESC: 降順
-
次のいずれかを使用して、結果のページを返します。
-
サンプルクエリ - すべての都市に関するすべての情報を参照してください
- モデル名に
-
フィルター
includeVariationsはListやPaginatedのクエリタイプに含まれます。クエリ結果でコンテンツフラグメントのバリエーションを取得するには、includeVariationsフィルターはtrueに設定する必要があります。- 詳しくは、特定モデルの複数のコンテンツフラグメントとそのバリエーションのサンプルクエリを参照してください。
note caution CAUTION フィルター includeVariationsとシステム生成フィールド_variationは、同じクエリ定義で一緒に使用することはできません。 -
論理和（OR）を使用する場合：
_logOp: ORを使用します- サンプルクエリ - 「Jobs」または「Smith」という名前を持つすべての人物を参照してください
-
論理積（AND）も存在しますが、（多くの場合）暗黙的です
-
コンテンツフラグメントモデル内のフィールドに対応するフィールド名に対してクエリを実行できます
- サンプルクエリ - ある会社の CEO と従業員の詳細を参照してください
-
モデルのフィールドに加えて、次のようなシステム生成フィールドがあります（フィールド名の先頭にアンダースコアが付きます）。
-
コンテンツの場合：
-
_locale：言語を表示します（言語マネージャーに基づく）- 特定ロケールの複数のコンテンツフラグメントのサンプルクエリを参照してください
-
_metadata：フラグメントのメタデータを表示します- メタデータのサンプルクエリ - 「GB」という賞のメタデータのリストを参照してください
-
_model：コンテンツフラグメントモデル（パスとタイトル）のクエリを許可します- モデルからのコンテンツフラグメントモデルのサンプルクエリを参照してください
-
_path：リポジトリ内のコンテンツフラグメントへのパス- サンプルクエリ - 1 つの特定の都市フラグメントを参照してください
-
_id：リポジトリ内のコンテンツフラグメントの UUID -
_reference：参照（リッチテキストエディターでのインライン参照など）を表示します -
_variation：コンテンツフラグメント内の特定のバリエーションを表示しますnote note NOTE コンテンツフラグメントに指定されたバリエーションが存在しない場合は、プライマリバリエーションが（フォールバック）デフォルトとして返されます。 note caution CAUTION システム生成フィールド _variationは、フィルターincludeVariationsと併用できません。- サンプルクエリ - 名前付きバリエーションを持つすべての都市を参照してください
-
-
画像配信の場合：
-
_authorURL：AEM オーサー上の画像アセットへの完全な URL -
_publishURL：AEM パブリッシュ上の画像アセットへの完全な URL -
Web に最適化された画像配信（DAM アセット）の場合：
-
_dynamicUrl：ImageRef参照で web に最適化された DAM アセットの完全な URLnote note NOTE _dynamicUrlは、画像アセットに使用する推奨 URL であり、可能な限り_path、_authorUrlおよび_publishUrlの代わりに使用してください。 -
_assetTransform：フィルターを定義するリストヘッダーにパラメーターを渡す -
以下を参照してください。
-
-
_dmS7Url：Dynamic Media アセットへの URL 配信に関するImageRef参照について
-
-
_tags：タグを含むコンテンツフラグメントまたはバリエーションの ID を表示するcq:tags識別子の配列です。- サンプルクエリ - 市区町村の区切り文字としてタグ付けされた、すべての都市の名前を参照してください。
- 詳しくは、特定のタグが添付された、任意のモデルのコンテンツフラグメントバリエーションのサンプルクエリを参照してください。
- 詳しくは、_tags ID でフィルタリングし、バリエーションを除外したサンプルクエリを参照してください。
- 詳しくは、_tags ID でフィルタリングし、バリエーションを含むサンプルクエリを参照してください。
note note NOTE また、コンテンツフラグメントのメタデータを一覧表示して、タグをクエリできます。 -
操作の場合：
-
_operator：特定の演算子（EQUALS、EQUALS_NOT、GREATER_EQUAL、LOWER、CONTAINS、STARTS_WITH）を適用します -
_apply：特定の条件（例：AT_LEAST_ONCE）を適用します -
_ignoreCase：クエリの実行時に大文字と小文字を区別しません
-
-
-
GraphQL のユニオン型がサポートされています
... onを使用します
-
ネストされたフラグメントに対するクエリ時のフォールバック：
- 任意のバリエーションがネストされたフラグメントに存在しない場合、マスター バリエーションが返されます。
外部 web サイトからの GraphQL エンドポイントのクエリ query-graphql-endpoint-from-external-website
外部 web サイトから GraphQL エンドポイントにアクセスするには、次の項目を設定する必要があります。
認証 authentication
コンテンツフラグメントに対するリモート AEM GraphQL クエリの認証を参照してください。
自動テスト automated-testing
AEM Cloud Manager でデプロイメントパイプラインを実行する場合、パイプライン実行中に自動テストが実行されます。
正確な結果を得るには、AEM as a Cloud Service ステージング 環境で 本番 環境をできるだけ正確にミラーリングする必要があります。これは、コンテンツにとって特に重要です。
AEM as a Cloud Service コンテンツコピーツールを使用して、本番コンテンツをステージング環境にコピーすることで、可能になります。
制限事項 limitations
潜在的な問題から保護するために、クエリにはデフォルトの制限が課されています。
- クエリには 100 万（1024 * 1024）文字を超える文字を含めることはできません
- クエリには、15,000 個を超えるトークンを含めることはできません
- クエリには、200,000 個を超える空白トークンを含めることはできません
また、次の事項にも注意する必要があります。
-
GraphQL クエリに 2 つ（またはそれ以上）のモデルで同じ名前のフィールドが含まれており、次の条件が満たされる場合、フィールド競合エラーが返されます。
-
したがって
- 2 つ（またはそれ以上のモデル）が可能な参照として使用されます（コンテンツフラグメント参照で許可された モデルタイプ として定義されている場合）。
また
- これら 2 つのモデルには共通の名前を持つフィールドがあります。つまり、両方のモデルに同じ名前が存在します。
また
- これらのフィールドは異なるデータタイプです。
-
例：
-
異なるモデルを持つ 2 つ（またはそれ以上）のフラグメント（
M1、M2など）が、別のフラグメントからの参照（コンテンツ参照またはフラグメント参照）として使用される場合。例：Fragment1MultiField/List -
異なるモデルを持つこれら 2 つのフラグメント（
M1、M2）には、同じ名前のフィールドがありますが、タイプが異なります。
次に例を示します。M1.TitleはTextM2.TitleはText/MultiField
-
GraphQL クエリに
Titleフィールドが含まれる場合、フィールド競合エラーが発生します。
-
-
FAQ faqs
次のような質問が寄せられました。
-
Q：「AEM 用 GraphQL API と Query Builder API の違いは何ですか？」
- A：「AEM GraphQL API は JSON 出力の完全な制御が可能であり、コンテンツをクエリするための業界標準になっています。今後、AEM GraphQL API への投資が計画されています。」
チュートリアル - AEM ヘッドレスと GraphQL をはじめる前に tutorial
実践的なチュートリアルを探している場合は、AEM ヘッドレスおよび GraphQL 入門をご覧ください。これは、AEM の GraphQL API を使用してコンテンツを構築および公開し、ヘッドレス CMS シナリオで外部アプリによって使用する方法を説明する包括的なチュートリアルです。