用AEM於內容片段的GraphQL API

瞭解如何在GraphQL API中使用Adobe Experience Manager(AEM)as a Cloud Service的內AEM容片段進行無頭內容傳遞。

與內AEM容片段一起使用的as a Cloud ServiceGraphQL API主要基於標準的開源GraphQL API。

在中使用GraphQL APIAEM可以在無頭CMS實現中將內容片段高效傳送到JavaScript客戶端:

  • 避免像REST一樣的迭代API請求,
  • 確保交付僅限於具體要求,
  • 允許批量交付作為對單個API查詢的響應的呈現所需的內容。
注意

GraphQL目前在Adobe Experience Manager()as a Cloud Service的兩種(單獨AEM的)情形中使用:

GraphQL API

GraphQL為:

  • "…API的查詢語言和用現有資料完成這些查詢的運行時。 GraphQL提供了對API中資料的完整且易於理解的描述,使客戶能夠準確詢問他們需要什麼,而不需要更多,使API更易於隨時間推移而發展,並支援功能強大的開發人員工具。

    請參閱 GraphQL.org

  • "…靈活API層的開放規範。 將GraphQL置於您現有的後端上,以比以往更快地構建產品……。

    請參閱 瀏覽GraphQL

  • "。…2012年,Facebook在內部開發了資料查詢語言和規範,2015年公開開源。 它提供了基於REST的體系結構的替代方案,目的是提高開發人員的工作效率並最大限度地減少資料傳輸量。 GraphQL由數百個不同規模的組織在生產中使用……」

    請參閱 GraphQL基礎

有關GraphQL API的詳細資訊,請參閱以下各節(包括許多其他資源):

用於實現的AEMGraphQL基於標準的GraphQL Java庫。 請參閱:

GraphQL術語

GraphQL使用以下功能:

查看 (GraphQL.org)GraphQL簡介 全面詳情,包括 最佳做法

GraphQL查詢類型

使用GraphQL,您可以執行查詢以返回以下任一值:

您還可以執行以下操作:

GraphiQL IDE

可以使用test和調試GraphQL查詢 GraphiQL IDE

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

使用案例可以取決於as a Cloud Service環境AEM的類型:

  • 發佈環境;用於:

    • 查詢JS應用程式的資料(標準用例)
  • 作者環境;用於:

    • 為「內容管理目的」查詢資料:
      • as a Cloud Service中AEM的GraphQL當前是只讀API。
      • REST API可用於CR(u)D操作。

權限

這些權限是訪問Assets所需的權限。

架構生成

GraphQL是強類型API,這意味著資料必須按類型清晰地結構化和組織。

GraphQL規範提供了一系列指導原則,說明如何建立用於查詢特定實例上的資料的強健API。 要執行此操作,客戶端需要獲取 架構,其中包含查詢所需的所有類型。

對於內容片段,GraphQL架構(結構和類型)基於 已啟用 內容片段模型 以及資料類型。

注意

所有GraphQL架構(從已導出的內容片段模型派生) 已啟用)可通過GraphQL終結點讀取。

這意味著您需要確保沒有敏感資料可用,因為敏感資料可能會以這種方式洩露;例如,這包括在模型定義中可以作為欄位名稱顯示的資訊。

例如,如果用戶建立了名為 Article,然AEM後生成對象 articleArticleModel。 此類型中的欄位與模型中定義的欄位和資料類型相對應。

  1. 內容片段模型:

    用於GraphQL的內容片段模型

  2. 相應的GraphQL架構(從GraphiQL自動文檔輸出):
    基於內容片段模型的GraphQL模式

    這顯示生成的類型 ArticleModel 包含 欄位

    • 其中三個由用戶控制: authormainreferencearticle

    • 其他欄位則由自動添加AEM,並代表提供某一內容片段資訊的有用方法;在本例中, _path_metadata_variations。 這些 幫助器欄位 標有前面 _ 區分用戶定義的內容和自動生成的內容。

  3. 用戶根據文章模型建立內容片段後,可通過GraphQL查詢。 有關示例,請參見 示例查詢 (基於 用於GraphQL的內容片段結構示例)。

在GraphQL中AEM,架構是靈活的。 這意味著每次建立、更新或刪除內容片段模型時,都會自動生成它。 更新內容片段模型時,還會刷新資料架構快取。

站點GraphQL服務監聽(在後台)對內容片段模型進行的任何修改。 檢測到更新後,只會重新生成該模式的那一部分。 這種優化節省了時間並提供了穩定性。

例如,如果:

  1. 安裝包含 Content-Fragment-Model-1Content-Fragment-Model-2:

    1. GraphQL類型 Model-1Model-2 生成。
  2. 然後修改 Content-Fragment-Model-2:

    1. Model-2 將更新GraphQL類型。

    2. 然而 Model-1 將保持不變。

注意

請注意,如果要通過REST api或其他方式對內容片段模型進行批量更新,則必須注意這一點。

通過與GraphQL查詢相同的終結點來提供架構,而客戶端則處理使用擴展調用架構的事實 GQLschema。 例如,執行簡單 GET 請求 /content/cq:graphql/global/endpoint.GQLschema 將導致輸出具有Content-type的架構: text/x-graphql-schema;charset=iso-8859-1

架構生成 — 未發佈的模型

嵌套內容片段時,可能會發佈父內容片段模型,但引用的模型未發佈。

注意

UI可AEM以阻止此情況發生,但如果以寫程式方式或使用內容包進行發佈,則可能發生此情況。

當發生這種情況時,AEM將生成 不完整 父內容片段模型的架構。 這意味著從架構中刪除依賴於未發佈模型的片段引用。

欄位

在架構中,有兩個基本類別的單個欄位:

  • 生成的欄位。

    選擇 欄位類型 用於根據配置內容片段模型的方式建立欄位。 欄位名稱取自 屬性名稱資料類型

    • 還有 呈現為 屬性需要考慮,因為用戶可以配置某些資料類型;例如,作為單行文本或多欄位。
  • GraphQLAEM還生成 幫助器欄位

    這些內容用於標識內容片段或獲取有關內容片段的詳細資訊。

欄位類型

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

內容片段模型 — 資料類型 GraphQL類型 說明
單行文本 字串, [字串] 用於簡單字串,如作者名、位置名等。
多行文本 字串 用於輸出文本,例如文章的正文
數量 浮起, [浮動] 用於顯示浮點數和常規數
布林值 (Boolean) 布林函數 用於顯示複選框→簡單的true/false語句
日期和時間 日曆 用於以ISO 8086格式顯示日期和時間。 根據所選類型,GraphQL中有三種可用的AEM類型: onlyDateonlyTimedateTime
列舉 String 用於從建立模型時定義的選項清單中顯示選項
標記 [String] 用於顯示表示中使用的標籤的字串列AEM表
內容參考資料 字串 用於在中顯示指向另一個資產的路AEM徑
片段引用 模型類型 用於引用建立模型時定義的特定模型類型的另一個內容片段

幫助程式欄位

除了用戶生成欄位的資料類型外,GraphQL還AEM生成許多 幫助 欄位,以幫助標識內容片段,或提供有關內容片段的其他資訊。

路徑

路徑欄位用作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 顯示按以下標量類型分組的資訊:

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

每個標量類型都表示單個名稱值對或名稱值對的陣列,其中該對的值屬於其分組的類型。

例如,如果要檢索內容片段的標題,我們知道此屬性是String屬性,因此我們將查詢所有String元資料:

要查詢元資料,請執行以下操作:

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

如果查看生成的GraphQL架構,則可以查看所有元資料GraphQL類型。 所有模型類型都具有相同 TypedMetaData

注意

正常元資料和陣列元資料的差異
記住 StringMetadataStringArrayMetadata 這兩個選項都引用儲存在儲存庫中的內容,而不是如何檢索它們。

例如,通過調用 stringMetadata 欄位中,您將接收儲存在儲存庫中的所有元資料的陣列 String ,如果您 stringArrayMetadata 您將接收儲存在儲存庫中的所有元資料的陣列 String[]

請參閱 元資料查詢示例 — 列出標題為GB的獎項的元資料

變數

_variations 已實現欄位,以簡化對內容片段的變體的查詢。 例如:

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

請參閱 示例查詢 — 具有命名變體的所有城市

GraphQL變數

GraphQL允許將變數放在查詢中。 有關詳細資訊,請參閱 變數的GraphQL文檔

例如,要獲取類型的所有內容片段 Article 具有特定變數的變數,可以 variation 在GraphiQL中。

GraphQL變數

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

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

GraphQL指令

在GraphQL中,有可能基於變數更改查詢,稱為GraphQL指令。

例如,您可以在 adventurePrice 查詢中的 AdventureModels,基於變數 includePrice

GraphQL指令

### query
query GetAdventureByType($includePrice: Boolean!) {
  adventureList {
    items {
      adventureTitle
      adventurePrice @include(if: $includePrice)
    }
  }
}

### in query variables
{
    "includePrice": true
}

篩選

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

篩選使用基於邏輯運算子和表達式的語法。

例如,以下(基本)查詢將篩選名稱為 JobsSmith:

query {
  personList(filter: {
    name: {
      _logOp: OR
      _expressions: [
        {
          value: "Jobs"
        },
        {
          value: "Smith"
        }
      ]
    }
  }) {
    items {
      name
      firstName
    }
  }
}

有關更多示例,請參見:

GraphQL for AEM — 擴展摘要

使用GraphQL查詢的基本操作,AEM以符合標準GraphQL規範。 對於具有以下幾AEM個副檔名的GraphQL查詢:

從外部網站查詢GraphQL終結點

要從外部網站訪問GraphQL終結點,您需要配置:

驗證

請參閱 內容片段AEM上遠程GraphQL查詢的驗證

常見問題

出現的問題:

  1. :"GraphQL API與Query Builder APIAEM有何不同?"

    • A:"GraphQL APIAEM提供對JSON輸出的完全控制,是查詢內容的行業標準。
      今後,AEM計畫投資GraphQLAEM API。
      "

教程 — 無頭和AEMGraphQL入門

想要實習教程嗎? 簽出 無頭和AEMGraphQL入門 端到端教程,演示如何使用AEMGraphQL API構建和公開內容,並讓外部應用在無頭CMS方案中使用。

本頁內容