與內容片段搭配使用的 AEM GraphQL API graphql-api-for-use-with-content-fragments

IMPORTANT
適用於內容片段的GraphQL API各項功能,可透過早期採用者計畫取得。
若要檢視狀態,以及如果您有興趣要如何套用,請檢視發行說明

了解如何將 Adobe Experience Manager (AEM) as a Cloud Service 中的內容片段與 AEM GraphQL API 搭配使用,以實現 Headless 內容傳遞。

與內容片段搭配使用的 AEM as a Cloud Service GraphQL API,在很大程度上是以標準、開放原始碼的 GraphQL API 為基礎。

在 AEM 中使用 GraphQL API 可以在 Headless CMS 實作中高效率地將內容片段傳遞給 JavaScript 用戶端:

  • 避免與 REST 一樣的反覆 API 要求,
  • 確保傳遞限於特定要求,
  • 允許大量傳遞需要轉譯的內容做為對單一 API 查詢的回應。
NOTE
GraphQL 目前在 Adobe Experience Manager (AEM) as a Cloud Service 中用於兩個 (獨立) 情況:
NOTE
請參閱結構化內容傳遞與管理的AEM API,以取得各種可用API的概觀,以及所涉及概念的比較。
NOTE
如需 Experience Manager API 的最新資訊,另請造訪「Adobe Experience Manager as a Cloud Service API」。

GraphQL API graphql-api

GraphQL 是:

  • …API 的查詢語言和使用現有資料完成這些查詢的執行階段。GraphQL 可完整清楚地描述 API 中的資料,使用戶端能夠準確地要求所需內容,別無其他,如此可輕鬆地隨著時間發展 API,造就強大的開發人員工具。」。

    請參閱 GraphQL.org

  • …靈活 API 層的開放規格。將 GraphQL 置於現有後端之上,可比以往更快速地建置產品…」。

    請參閱探索 GraphQL

  • 「…一種資料查詢語言和規格,由 Facebook 於 2012 年在內部開發,然後於 2015 年公開原始碼。它提供了 REST 式架構的替代方案,目的是提高開發人員的生產力並盡量減少傳輸的資料量。GraphQL 用於生產環境,數百個各種規模的組織都在使用…」

    請參閱 GraphQL 基礎

如需 GraphQL API 的資訊,請參閱以下章節 (以及許多其他資源):

GraphQL for AEM 實作是以標準 GraphQL Java 庫為基礎。請參閱:

GraphQL 術語 graphql-terminology

GraphQL 使用以下項目:

  • 查詢

  • 結構描述和類型

    • 結構描述是由 AEM 根據內容片段模型所產生。
    • 使用您的結構描述,GraphQL 呈現 GraphQL for AEM 實作可用的類型和操作。
  • 欄位

  • GraphQL 端點

    • AEM 中回應 GraphQL 查詢並提供 GraphQL 結構描述存取權的路徑。

    • 如需詳細資訊,請參閱啟用 GraphQL 端點

請參閱 (GraphQL.org) GraphQL 簡介 了解完整的詳細資訊,包括最佳做法

GraphQL 查詢類型 graphql-query-types

使用 GraphQL,您可以執行查詢以傳回以下兩者之一:

AEM 提供將查詢 (兩種類型) 轉換為持續性查詢的功能,可由 Dispatcher 和 CDN 快取

GraphQL 查詢最佳做法 (Dispatcher 和 CDN) graphql-query-best-practices

持續性查詢是建議用於發佈執行個體的方法,如下:

  • 它們被快取
  • 它們由 AEM as a Cloud Service 集中管理
NOTE
通常編寫執行個體沒有 Dispatcher/CDN,因此在那裡使用持續性查詢沒有任何好處;除了測試它們。

不建議使用 POST 要求的 GraphQL 查詢,因為它們不會被快取,因此在預設執行個體上,Dispatcher 設定為阻擋此類查詢。

雖然 GraphQL 也支援 GET 要求,但這些要求可能會達到限制 (例如,URL 的長度),而使用持續性查詢可以避免此狀況。

如需更多的詳細資訊,請參閱啟用持續性查詢的快取

NOTE
若要在 Dispatcher 中允許直接和/或 POST 查詢,您可以要求您的系統管理員:
NOTE
執行直接查詢的功能可能會在未來的某個時間被淘汰。

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

權限是存取資產所需的權限。

GraphQL 查詢是在基礎要求之 AEM 使用者的許可下執行的。如果使用者沒有某些片段 (儲存為資產) 的讀取權限,它們將不會包含在結果集中。

此外,使用者必須可以存取 GraphQL 端點才能執行 GraphQL 查詢。

結構描述產生 schema-generation

GraphQL 是強式類型 API,這表示資料必須結構明確並依類型編排。

GraphQL 規格提供了一系列指南,說明如何建立健全的 API 來查詢特定執行個體上的資料。為此,用戶端必須擷取結構描述,其中包含查詢所需的所有類型。

對於內容片段,GraphQL 結構描述 (結構和類型) 是以​ 啟用的內容片段模型及其資料類型為基礎。

CAUTION
所有 GraphQL 結構描述 (衍生自已​ 啟用 ​的內容片段模型) 都可透過 GraphQL 端點讀取。
這表示您必須確保沒有敏感資料,因為它可能會以這種方式洩露;例如,這包括可以在模型定義中做為欄位名稱出現的資訊。

例如,如果使用者建立了一個名為 Article 的內容片段模型,則 AEM 會產成一個 GraphQL 類型 ArticleModel。此類型中的欄位對應於模型中定義的欄位和資料類型。此外,它還為操作此類型的查詢建立一些登入點,例如 articleByPatharticleList

  1. 內容片段模型:

    與 GraphQL 搭配使用的內容片段模型

  2. 對應的 GraphQL 結構描述 (來自 GraphiQL 自動文件的輸出):
    根據內容片段模型的 GraphQL 結構描述

    此顯示產生的類型 ArticleModel 包含多個欄位

    • 其中三個已由使用者控制:authormainreferencearticle

    • 其他欄位由 AEM 自動新增,並代表可提供特定內容片段資訊的有用方法;在此範例中,(Helper 欄位) _path_metadata_variations

  3. 使用者根據文章模型建立內容片段後,就可以透過 GraphQL 對其進行查詢。例如,請參閱範例查詢 (根據與 GraphQL 搭配使用的範例內容片段結構)。

在 GraphQL for AEM 中,結構描述是靈活的。這表示著每次建立、更新或刪除內容片段模型時都會自動產生它。當您更新內容片段模型時,資料結構描述快取也會重新整理。

當您更新內容片段模型時,資料結構描述快取也會重新整理。

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 將保持不變。

NOTE
如果您想透過 REST API 或其他方式對內容片段模型進行大量更新,請務必注意這一點。

結構描述透過與 GraphQL 查詢相同的端點提供服務,用戶端處理以 GQLschema 副檔名呼叫結構描述這一事實。例如,對 /content/cq:graphql/global/endpoint.GQLschema 執行簡單的 GET 要求,將導致內容類型為 text/x-graphql-schema;charset=iso-8859-1 的結構描述輸出。

結構描述產生 - 未發佈的模型 schema-generation-unpublished-models

巢狀內嵌內容片段時,可能會發佈父內容片段模型,但不會發佈被參考的模型。

NOTE
AEM UI 可防止這種情況發生,但如果以程式設計方式或使用內容套件進行發佈,則可能會發生這種情況。

發生這種情況時,AEM 會為父內容片段模型產生​ 不完整 ​結構描述。這表示相依於未發佈模型的片段參考已從結構描述中刪除。

欄位 fields

在結構描述中有個別欄位,分成兩個基本類別:

  • 產生的欄位。

    一系列資料類型用於根據內容片段模型的設定方式建立欄位。欄位名稱取自​ 資料類型 ​索引標籤的​ 屬性名稱 ​欄位。

    • 也必須考慮​ 轉譯為 ​設定,因為使用者可以設定某些資料類型。例如,從下拉選單中選擇 multifield,可以將單行文字欄位設定為包含多個單行文字。
  • GraphQL for AEM 也會產生幾個 Helper 欄位

資料類型 data-types

GraphQL for AEM 支援類型清單。表示所有支援的內容片段模型資料類型和對應的 GraphQL 類型:

內容片段模型 - 資料類型
GraphQL 類型
說明
單行文字
String[String]
用於簡單的字串,例如作者姓名、位置名稱等。
多行文字
String[String]
用於輸出文字,例如文章正文
數字
Float[Float]
用於顯示浮點數和正規數
布林值
Boolean
用於顯示核取方塊 → 簡單的 true/false 陳述式
日期和時間
Calendar
用於以 ISO 8601 格式顯示日期和時間。視所選類型而定,AEM GraphQL 中可使用三種風格:onlyDateonlyTimedateTime
列舉
String
用於顯示模型建立時定義之選項清單中的選項
標記
[String]
用於顯示字串清單,字串代表 AEM 中使用的標記
內容參考
String[String]
用於顯示 AEM 中另一個資產的路徑
內容參考 (UUID)
String[String]
用於顯示路徑,以AEM中通往其他資產的UUID表示
片段參考
模型類型

單一欄位:Model - 模型類型,直接參考

多個欄位,具單一參考類型:[Model] - Model 類型陣列,從陣列直接參考

多個欄位,具多個參考類型:[AllFragmentModels] - 所有模型類型陣列,從聯合類型的陣列參考
用於參考特定模型類型的一個或多個內容片段,在建立模型時定義
片段參考 (UUID)
模型類型

單一欄位:Model - 模型類型,直接參考

多個欄位,具單一參考類型:[Model] - Model 類型陣列,從陣列直接參考

多個欄位,具多個參考類型:[AllFragmentModels] - 所有模型類型陣列,從聯合類型的陣列參考
用於參考特定模型類型的一個或多個內容片段,在建立模型時定義

Helper 欄位 helper-fields

除了使用者產生之欄位的資料類型外,GraphQL for AEM 也會產生幾個 Helper 欄位,以協助識別內容片段,或提供有關內容片段的其他資訊。

這些 Helper 欄位前面加上 _ 以區分是使用者定義的還是自動產生的。

路徑 path

路徑欄位作為 AEM GraphQL 中的標識符。它代表 AEM 存放庫中內容片段資產的路徑。我們選擇它作為內容片段的標識符,因為它:

  • 在 AEM 中是唯一的,
  • 容易撷取。

以下程式碼將顯示根據內容片段模型 Author (WKND 教學課程提供) 建立之所有內容片段的路徑。

{
  authorList {
    items {
      _path
    }
  }
}

若要撷取特定類型的單一內容片段,您還需要先確定其路徑。例如:

{
  authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
    item {
      _path
      firstName
      lastName
    }
  }
}

請參閱範例查詢 - 單一特定城市片段

ID (UUID) id-uuid

此ID欄位也會用作AEM GraphQL中的識別碼。 它代表AEM存放庫中內容片段資產的路徑,但不會儲存實際路徑,而是儲存代表資源的UUID。 我們選擇它作為內容片段的標識符,因為它:

  • 在 AEM 中是唯一的,
  • 可以輕鬆擷取,
  • 不會變更資源移動的時間。

內容片段和參照內容片段或資產的UUID,可透過JSON屬性_id傳回。

{
  articleList {
    items {
        _id
        _path
    }
  }
}

中繼資料 metadata

透過 GraphQL,AEM 還公開內容片段的中繼資料。中繼資料是描述內容片段的資訊,例如內容片段的標題、縮圖路徑、內容片段的描述、建立日期等。

由於中繼資料是透過結構描述編輯器產生的,因此沒有特定的結構,所以實作 TypedMetaData GraphQL 類型來公開內容片段的中繼資料。TypedMetaData 公開依以下純量類型群組的資訊:

欄位
stringMetadata:[StringMetadata]!
stringArrayMetadata:[StringArrayMetadata]!
intMetadata:[IntMetadata]!
intArrayMetadata:[IntArrayMetadata]!
floatMetadata:[FloatMetadata]!
floatArrayMetadata:[FloatArrayMetadata]!
booleanMetadata:[BooleanMetadata]!
booleanArrayMetadata:[booleanArrayMetadata]!
calendarMetadata:[CalendarMetadata]!
calendarArrayMetadata:[CalendarArrayMetadata]!

每個純量類型代表單一名稱-值配對或名稱-值配對組,配對中的值屬於該群組的類型。

例如,如果你想擷取內容片段的標題,我們知道這個屬性是字串屬性,所以我們會查詢所有的字串中繼資料:

若要查詢中繼資料:

{
  authorByPath(_path: "/content/dam/wknd-shared/en/contributors/sofia-sj-berg") {
    item {
      _metadata {
        stringMetadata {
          name
          value
        }
      }
    }
  }
}

如果檢視產生的 GraphQL 結構描述,則可以檢視所有中繼資料 GraphQL 類型。所有模型類型都具有相同的 TypedMetaData

NOTE
一般和陣列中繼資料的區別
請記住,StringMetadataStringArrayMetadata 都是指儲存在存放庫的中繼資料,而不是擷取它們的方式。
例如,呼叫 stringMetadata 欄位,您將收到以 String 儲存在存放庫之所有中繼資料的陣列,如果呼叫 stringArrayMetadata,則會收到以 String[] 儲存在存放庫之所有中繼資料的陣列。

請參閱中繼資料的範例查詢 - 列出 GB 獎項的中繼資料

變化 variations

_variations 欄位已實作以簡化查詢內容片段具有的變化。例如:

{
  authorByPath(_path: "/content/dam/wknd-shared/en/contributors/ian-provo") {
    item {
      _variations
    }
  }
}
NOTE
_variations 欄位不包含 master 變化,在技術上,原始資料 (在 UI 中參考為​ 主版) 不視為明確變化。

請參閱「範例查詢 - 所有具有名稱變化的城市」。

NOTE
如果內容片段不存在特定的變化,則原始資料 (也稱為主版變化) 會作為 (備援) 預設值傳回。

GraphQL 變數 graphql-variables

GraphQL 允許在查詢中放置變數。如需詳細資訊,請參閱 GraphQL 變數文件

例如,若要取得特定變化 (若有) 中類型為 Author 的所有內容片段,您可以在 GraphiQL 中指定引數 variation

GraphQL 變數

查詢

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 欄位。

GraphQL 指示詞

查詢

query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      title
      price @include(if: $includePrice)
    }
  }
}

查詢變數

{
    "includePrice": true
}

篩選 filtering

您還可以在 GraphQL 查詢中使用篩選來傳回特定資料。

篩選使用以邏輯運算子和運算式的語法。

最不可部分完成的部分是可套用到特定欄位內容的單一運算式。它將欄位內容與特定的常數值進行比較。

例如,運算式:

{
  value: "some text"
  _op: EQUALS
}

會將欄位內容與值 some text 進行比較,如果內容等於該值則成功。否則,運算式將失敗。

以下運算子可用於將欄位與特定值相比較:

運算子
類型
運算式成功,如果…
EQUALS
String, ID, Boolean
…值與欄位內容完全相同
EQUALS_NOT
String, ID
…值與欄位內容​ ​相同
CONTAINS
String
…欄位內容包含值 ({ value: "mas", _op: CONTAINS } 將符合 ChristmasXmasmaster…)
CONTAINS_NOT
String
…欄位內容 ​包含值
STARTS_WITH
ID
… ID 以特定值開頭 ({ value: "/content/dam/", _op: STARTS_WITH 將符合 /content/dam/path/to/fragment,但不符合 /namespace/content/dam/something
EQUAL
Int, Float
…值與欄位內容完全相同
UNEQUAL
Int, Float
…值與欄位內容​ ​相同
GREATER
Int, Float
…欄位內容大於值
GREATER_EQUAL
Int, Float
…欄位內容大於或等於值
LOWER
Int, Float
…欄位內容小於值
LOWER_EQUAL
Int, Float
…欄位內容小於或等於值
AT
Calendar, Date, Time
…欄位內容與值完全相同 (包含時區設定)
NOT_AT
Calendar, Date, Time
…欄位內容與值​ ​相同
BEFORE
Calendar, Date, Time
…值表示的時間點在欄位內容表示的時間點之前
AT_OR_BEFORE
Calendar, Date, Time
… 值表示的時間點在欄位內容表示的時間點之前或相同
AFTER
Calendar, Date, Time
…值表示的時間點在欄位內容表示的時間點之後
AT_OR_AFTER
Calendar, Date, Time
…值表示的時間點在欄位內容表示的時間點之後或相同

某些類型也可讓您指定其他選項來修改評估運算式的方式:

選項
類型
說明
_ignoreCase
String
忽略字串的大小寫,例如 time 值與 TIMEtimetImE 相符…
_sensitiveness
Float
允許 float 值的某些差數視為相同 (以解決由於 float 值的內部表示造成的技術限制;應避免,因為此選項可能對效能有負面影響

運算式可以使用邏輯運算子 (_logOp) 合併成一個集合:

  • OR- 如果至少有一個運算式成功,則運算式集成功
  • AND - 如果所有運算式成功,則運算式集成功 (預設)

每個欄位都可以由自己的運算式集進行篩選。篩選器引數中提到的所有欄位的運算式集最終將由自己的邏輯運算子合併。

篩選器定義 (作為 filter 引數傳遞給查詢) 包含:

  • 每個欄位的子定義 (欄位可以透過其名稱存取,例如,資料 (欄位) 類型中的 lastName 欄位其篩選器中有一個 lastName 欄位)
  • 每個子定義包含 _expressions 陣列,其提供運算式集,以及 _logOp 欄位,其定義應用來將運算式合併的邏輯運算子
  • 每個運算式由值 (value 欄位) 和運算子 (_operator 欄位) 定義,應比較欄位內容與

如果您要將項目與 AND 合併,則可以省略 _logOp;如果要檢查是否相等,則可以省略 _operator,因為這些是預設值。

以下範例示範一個完整的查詢,該查詢會篩選所有 lastNameProvo 或包含 sjö 的人,不受大小寫影響:

{
  authorList(filter: {
    lastname: {
      _logOp: OR
      _expressions: [
        {
          value: "sjö",
          _operator: CONTAINS,
          _ignoreCase: true
        },
        {
          value: "Provo"
        }
      ]
    }
  }) {
    items {
      lastName
      firstName
    }
  }
}

雖然您也可以對巢狀欄位進行篩選,但不建議這樣做,因為這可能會導致效能問題。

如需進一步範例,請參閱:

排序 sorting

此功能可讓您根據指定的欄位將查詢結果進行排序。

排序標準:

  • 以逗號分隔的值清單,這些值代表欄位路徑

    • 清單中的第一個欄位將定義主要排序順序,如果主要排序標準的兩個值相等,將使用第二個欄位,如果前兩個標準相等,則使用第三個欄位
    • 點符號,即 field1.subfield.subfield 等…
  • 具有順序方向 (選擇性)

    • ASC (遞增) 或 DESC (遞減);預設是套用 ASC
    • 可以為每個欄位指定方向,這表示您可以對一個欄位遞增排序,對另一個欄位遞減排序 (姓名,名字 DESC)

例如:

query {
  authorList(sort: "lastName, firstName") {
    items {
      firstName
      lastName
    }
  }
}

同時:

{
  authorList(sort: "lastName DESC, firstName DESC") {
    items {
        lastName
        firstName
    }
  }
}

您也可以使用 nestedFragmentname.fieldname格式,對巢狀片段內的欄位進行排序。

NOTE
這可能會對效能產生負面影響。

例如:

query {
  articleList(sort: "authorFragment.lastName")  {
    items {
      title
      authorFragment {
        firstName
        lastName
        birthDay
      }
      slug
    }
  }
}

分頁 paging

此功能可讓您針對傳回清單的查詢類型執行分頁。提供兩種方法:

  • List 查詢中,offsetlimit
  • Paginated 查詢中,firstafter

清單查詢 - offset 和 limit list-offset-limit

...List 查詢中,您可以使用 offsetlimit 傳回特定的結果子集:

  • offset:指定第一個要傳回的資料集
  • limit:指定傳回的資料集數量上限

例如,要輸出最多包含五篇文章的結果頁面,從​ 完整 ​結果清單中的第五篇文章開始:

query {
   articleList(offset: 5, limit: 5) {
    items {
      authorFragment {
        lastName
        firstName
      }
    }
  }
}
NOTE
  • 分頁需要穩定的排序順序,才能在多個查詢要求同一結果集的不同頁面時,跨多個查詢正常運作。依預設,它使用結果集中每個項目的存放庫路徑來確保順序始終相同。如果使用不同的排序順序,且如果無法在 JCR 查詢層級進行排序,則會對效能產生負面影響,因為在確定頁面之前必須先將整個結果集載入到記憶體中。

  • 偏移量越高,從完整的 JCR 查詢結果集中略過項目所需的時間就越多。針對大型結果集的替代解決方案是使用已分頁查詢搭配 firstafter 方法。

已分頁查詢 - first 和 after paginated-first-after

...Paginated 查詢類型重複使用大部分的 ...List 查詢類型功能 (篩選、排序),但沒有使用 offset/limit 引數,而是使用 first/after,如 GraphQL 游標連接規格所定義。您可以在 GraphQL 簡介中找到不太正式的簡介。

  • first:要傳回的前 n 個項目。
    預設為 50
    最大值為 100
  • after:決定所要求頁面開始的游標;請注意,游標所代表的項目不包含在結果集中;項目的游標由 edges 結構的 cursor 欄位決定。

例如,要輸出最多包含五篇文章的結果頁面,從​ 完整 ​結果清單中的特定游標項目開始:

query {
    adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
        edges {
          cursor
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
    }
}
NOTE
  • 依預設,分頁使用代表片段的存放庫節點 UUID 進行排序,以確保結果的順序始終相同。使用 sort 時,會以隱含的方式使用 UUID 以確保唯一排序;即使是排序鍵相同的兩個項目也一樣。

  • 由於內部技術限制,如果對巢狀欄位套用排序和篩選,效能會降低。因此,建議使用儲存在根層級的篩選/排序欄位。如果要查詢大型已分頁結果集,同樣也建議使用此方法。

GraphQL 查詢中的 Web 最佳化影像傳遞 web-optimized-image-delivery-in-graphql-queries

Web 最佳化影像傳遞可讓您使用 Graphql 查詢進行下列作業:

  • 要求 DAM 資產影像的 URL (由 內容參考 ​進行參考)

  • 透過查詢傳遞參數,以便自動產生並傳回特定的影像轉譯

    note note
    NOTE
    指定的轉譯未存儲在 AEM Assets 中。轉譯會在快取中產生並保留一小段時間。
  • 將 URL 作為 JSON 傳遞的一部分傳回

您可以使用 AEM 進行以下作業:

這表示在查詢執行期間會套用命令,其方式與這些影像的 GET 要求中的 URL 參數相同。

這可讓您為 JSON 傳遞動態地建立影像轉譯,即不必手動建立這些轉譯並將其儲存在存放庫中。

GraphQL 中的解決方案代表您可以:

  • 要求 URL:在 _dynamicUrl 參考上使用 ImageRef

  • 傳遞參數:新增 _assetTransform 到您定義篩選器的清單標頭中

NOTE
內容參考 可用於 DAM 資產和 Dynamic Media 資產。擷取適當的 URL 使用不同的參數:
  • _dynamicUrl:DAM 資產
  • _dmS7Url:Dynamic Media 資產
如果參考的資產是 DAM 資產,則 _dmS7Url 的值將為 null。請參閱「透過 GraphQL 查詢以 URL 進行動態媒體資產傳遞」。

轉換要求結構 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-asset-delivery-by-url

GraphQL for AEM Content Fragments 可讓您要求 AEM Dynamic Media (Scene7) 資產的 URL (由​ 內容參考 ​所參考)。

GraphQL 中的解決方案代表您可以:

NOTE
若要這樣做,您需要有 Dynamic Media 雲端設定
這會在建立資產時,將 dam:scene7Filedam:scene7Domain 屬性新增到資產的中繼資料中。
NOTE
內容參考 ​可用於 DAM 資產和 Dynamic Media 資產。擷取適當的 URL 使用不同的參數:
  • _dmS7Url:Dynamic Media 資產
  • _dynamicUrl:DAM 資產
如果參考的資產是 Dynamic Media 資產,則 _dynamicURL 的值將為 null。請參閱「GraphQL 查詢中的 Web 最佳化影像傳遞」。

Dynamic Media 資產透過 URL 進行傳遞的範例查詢 - 影像參考 sample-query-dynamic-media-asset-delivery-by-url-imageref

以下是範例查詢:

  • 對於類型為 teamperson 的多個內容片段,傳回 ImageRef
query allTeams {
  teamList {
    items {
      _path
      title
      teamMembers {
        fullName
        profilePicture {
          __typename
          ... on ImageRef{
            _dmS7Url
            height
            width
          }
        }
      }
    }
  }
}

Dynamic Media 資產透過 URL 進行傳遞的範例查詢 - 多個參考 sample-query-dynamic-media-asset-delivery-by-url-multiple-refs

以下是範例查詢:

  • 對於類型為 teamperson 的多個內容片段,傳回 ImageRefMultimediaRefDocumentRef
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
            }
          }
        }
      }
    }
  }
}

GraphQL for AEM - 擴充功能摘要 graphql-extensions

使用 GraphQL for AEM 進行查詢的基本操作符合標準 GraphQL 規格。使用 GraphQL for AEM 進行查詢,有一些擴充功能:

從外部網站查詢 GraphQL 端點 query-graphql-endpoint-from-external-website

若要從外部網站查詢 GraphQL 端點,您需要設定:

驗證 authentication

請參閱針對內容片段之遠端 AEM GraphQL 查詢的驗證

自動化測試 automated-testing

在 AEM Cloud Manager 中執行部署管道時,會在管道執行期間執行自動化測試。

為了提供準確的結果,您的 AEM as a Cloud Service 中繼 ​環境應盡可能與您的​ 生產 ​環境相似。這對於內容來說非常重要。

您可以透過使用 AEM as a Cloud Service 內容複製工具 將生產內容複製到中繼環境來實現這一點。

限制 limitations

為了防範潛在問題,對您的查詢會施加預設限制:

  • 查詢不能包含超過 1M (1024 * 1024) 個字元
  • 查詢不能包含超過 15000 個語彙基元
  • 查詢不能包含超過 200000 個空白語彙基元

您還需要了解:

  • 當您的 GraphQL 查詢在兩個 (或多個) 模型中具有相同名稱的欄位,並且滿足以下條件時,將傳回欄位衝突錯誤:

    • 當:

      • 將兩個 (或更多模型) 當作可能的參考時,並且它們在內容片段參考中定義為允許的​ 模型類型

      和:

      • 這兩個模型的欄位具有相同的名稱;即兩個模型中出現相同的名稱。

      • 這些欄位的資料類型不同。
    • 例如:

      • 當兩個 (或多個) 具有不同模型 (例如,M1M2) 的片段用作來自另一個片段的可能參考 (內容參考或片段參考) 時;例如 Fragment1 MultiField/List

      • 而這兩個具有不同模型 (M1M2) 的片段擁有相同名稱但不同類型的欄位。
        說明:

        • M1.Title 作為 Text
        • M2.Title 作為 Text/MultiField
      • 那麼如果 GraphQL 查詢包含 Title 欄位,就會出現欄位衝突錯誤。

常見問題 faqs

出現的問題:

  1. 問題:「GraphQL API for AEM 與查詢產生器 API 有何不同?

    • 答案
      AEM GraphQL API 可讓您完全控制 JSON 輸出,是業界的查詢內容標準。
      在未來,AEM 計畫投資 AEM GraphQL API。

教學課程 - AEM Headless 和 GraphQL 快速入門 tutorial

正在尋找實作教學課程?查看 AEM Headless 和 GraphQL 快速入門端對端教學課程,說明如何在 Headless CMS 情境下使用 AEM GraphQL API 建立和公開內容並供外部應用程式取用。

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab