與內容片段搭配使用的 AEM GraphQL API

了解如何搭配AEM GraphQL API使用Adobe Experience Manager(AEM)中的內容片段進行無頭式內容傳送。

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

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

• 避免與 REST 一樣的反覆 API 要求，
• 確保傳遞限於特定要求，
• 允許大量傳遞需要呈現的內容做為對單一 API 查詢的回應。

GraphQL API

GraphQL 是：

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

  請參閱 GraphQL.org

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

  請參閱探索 GraphQL。

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

  請參閱 GraphQL 基礎。

有關 GraphQL API 的更多資訊，請參閱以下章節 (以及許多其他資源)：

• 位於 graphql.org：

  • GraphQL 簡介

  • GraphQL 規格

• 位於 graphql.com：

  • 指南

  • 教學課程

  • 案例研究

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

• graphQL.org - Java

• GitHub 上的 GraphQL Java

GraphQL 術語

GraphQL 使用以下項目：

• 查詢

• 結構描述和類型：

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

• 欄位

• GraphQL 端點

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

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

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

GraphQL 查詢類型

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

• 單一項目

• 項目清單

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

GraphQL 查詢最佳做法 (Dispatcher 和 CDN)

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

• 它們被快取
• 由AEM集中管理

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

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

GraphiQL介面

標準的實施 GraphiQL 介面可與AEM GraphQL搭配使用。

此介面允許您直接輸入和測試查詢。

例如：

• http://localhost:4502/content/graphiql.html

這提供語法醒目提示、自動完成、自動建議等功能，以及歷史記錄和線上檔案：

作者和發佈環境的使用案例

使用案例取決於AEM環境的類型：

• 發佈環境：用於：

  • 為 JS 應用程式查詢資料 (標準使用案例)

• 作者環境：用於：

  • 為「內容管理目的」查詢資料：
    • AEM中的GraphQL目前是唯讀API。
    • REST API 可用於 CR(u)D 操作。

權限

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

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

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

結構描述產生

GraphQL 是強式類型 API，這表示資料必須結構明確並按類型組織。

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

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

例如，如果使用者建立的內容片段模型稱為 Article，則AEM會產生物件 article 屬於 ArticleModel. 此類型中的欄位對應於模型中定義的欄位和資料類型。

1. 內容片段模型：

   

2. 對應的 GraphQL 結構描述 (來自 GraphiQL 自動文件的輸出)：
   

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

   • 其中三個已由使用者控制：author、main 和 referencearticle。

   • 其他欄位是由AEM自動新增的，是提供特定內容片段相關資訊的實用方法；在本例中， _path, _metadata, _variations. 這些 Helper 欄位 前面加上 _ 以區分是使用者定義的還是自動產生的。

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

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

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 的結構描述輸出。

結構描述產生 - 未發佈的模型

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

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

欄位

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

• 產生的欄位。

  選取 欄位類型 可用來根據您如何設定內容片段模型來建立欄位。 欄位名稱取自 屬性名稱 欄位 資料類型.

  • 還有 呈現為 屬性，因為使用者可以設定某些資料類型；例如，作為單行文字或多欄位。

• GraphQL for AEM 也會產生許多 Helper 欄位。

  這些用於識別內容片段，或用於取得有關內容片段的詳細資訊。

欄位類型

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

Helper 欄位

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

路徑

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

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

下列程式碼會顯示根據內容片段模型建立的所有內容片段路徑 Person.

{
  personList {
    items {
      _path
    }
  }
}

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

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

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

中繼資料

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

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

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

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

若要查詢中繼資料：

{
  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 具有特定變數時，您可以指定變數 variation 在GraphiQL中。

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

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

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
    }
  }
}

如需進一步範例，請參閱：

• GraphQL for AEM 擴充功能 的詳細資訊

• 使用此範例內容和結構的範例查詢

  • 以及準備用於範例查詢的範例內容和結構

• 以 WKND 專案為基礎的範例查詢

GraphQL for AEM - 擴充功能摘要

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

• 如果您需要單一結果：

  • 使用模型名稱，例如城市

• 如果您期望結果清單：

  • 新增 List 到模型名稱，例如 cityList
  • 請參閱範例查詢 - 所有城市的所有資訊

• 篩選 includeVariations 包含在 List 查詢類型。 若要擷取查詢結果中的內容片段變化，請 includeVariations 篩選器必須設為 true.

  注意

  篩選 includeVariations 不能與系統生成的欄位一起使用 _variation.

• 如果要使用邏輯 OR：

  • 使用 _logOp: OR
  • 請參閱範例查詢 - 姓名為「Jobs」或「Smith」的所有人員

• 邏輯 AND 也存在，但 (通常) 是隱含的

• 您可以查詢與內容片段模型內欄位相對應的欄位名稱

  • 請參閱範例查詢 - 公司 CEO 和員工的完整詳細資料

• 除了模型內的欄位外，還有一些系統產生的欄位 (前面有底線)：

  • 對於內容：

    • _locale：顯示語言，根據語言管理員

      • 請參閱範例查詢：給定地區設定的多個內容片段

    • _metadata：顯示片段的中繼資料

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

    • _model：允許查詢內容片段模型 (路徑和標題)

      • 請參閱從模型進行的內容片段模型範例查詢

    • _path：存放庫中內容片段的路徑

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

    • _reference：顯示參考；包含 RTF 編輯器中的內聯參考

      • 請參閱預先擷取參考之多個內容片段的範例查詢

    • _variation：顯示內容片段中的特定變化

      注意

      如果內容片段不存在給定的變化，則主變化將作為 (備援) 預設值傳回。

      注意

      系統產生的欄位 _variation 無法與篩選器搭配使用 includeVariations.

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

    • _tags :顯示包含標籤之內容片段或變體的ID;這是 cq:tags 識別碼。

      • 請參閱 查詢示例 — 標籤為城市分行的所有城市的名稱
      • 請參閱 附加特定標籤之指定模型的內容片段變異查詢範例
      注意

      您也可以列出內容片段的中繼資料來查詢標籤。

      * And 操作：

    • _operator：套用特定的運算子；EQUALS、EQUALS_NOT、GREATER_EQUAL、LOWER、CONTAINS、STARTS_WITH

      • 請參閱範例查詢 - 所有姓名沒有「Jobs」的人員
      • 請參閱範例查詢 - 所有 _path 以特定前置詞開頭的冒險

    • _apply：套用特定條件；例如，AT_LEAST_ONCE

      • 請參閱範例查詢 - 篩選內含必須至少出現一次之項目的陣列

    • _ignoreCase：查詢時忽略大小寫

      • 請參閱範例查詢 - 所有名稱包含 SAN 的城市，不區分大小寫

• 支援 GraphQL 聯合類型：

  • 使用 ... on
    • 請參閱含內容參考之特定模型的內容片段的範例查詢

• 查詢巢狀片段時的備援：

  • 如果請求的變異不存在於巢狀片段中，則 主版 將會傳回變數。

CORS 篩選器

若要存取GraphQL端點，必須在客戶Git存放庫中設定CORS原則。 做法是為所需端點新增適當的 OSGi CORS 設定。

此配置必須指定受信任的網站源 alloworigin 或 alloworiginregexp 必須授予其存取權。

例如，若要授予 GraphQL 端點 和 https://my.domain 之持續性查詢端點的存取權，您可以使用：

{
  "supportscredentials":true,
  "supportedmethods":[
    "GET",
    "HEAD",
    "POST"
  ],
  "exposedheaders":[
    ""
  ],
  "alloworigin":[
    "https://my.domain"
  ],
  "maxage:Integer":1800,
  "alloworiginregexp":[
    ""
  ],
  "supportedheaders":[
    "Origin",
    "Accept",
    "X-Requested-With",
    "Content-Type",
    "Access-Control-Request-Method",
    "Access-Control-Request-Headers"
  ],
  "allowedpaths":[
    "/content/_cq_graphql/global/endpoint.json",
    "/graphql/execute.json/.*"
  ]
}

如果您為端點設定了虛名路徑，您也可以在 allowedpaths 中使用它。

查閱者篩選器

除了CORS設定，反向連結篩選器還必須設定為允許從第三方主機存取。

若要這麼做，請新增適當的OSGi反向連結篩選設定檔案，該設定檔案可：

• 指定受信任網站的主機名稱；allow.hosts 或 allow.hosts.regexp，
• 授予此主機名稱的存取權。

例如，要授予使用查閱者 my.domain 之要求的存取權，您可以：

{
    "allow.empty":false,
    "allow.hosts":[
      "my.domain"
    ],
    "allow.hosts.regexp":[
      ""
    ],
    "filter.methods":[
      "POST",
      "PUT",
      "DELETE",
      "COPY",
      "MOVE"
    ],
    "exclude.agents.regexp":[
      ""
    ]
}

驗證

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

常見問題

出現的問題：

1. 問題：「GraphQL API for AEM 與查詢產生器 API 有何不同？」

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

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

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

Business.Adobe.com 資源