AEM GraphQL API,用於內容片段

與內容片段搭配使用的Adobe Experience Manager As a Cloud Service(AEM)GraphQL API,主要是以標準、開放原始碼的GraphQL API為基礎。

在AEM中使用GraphQL API,可在無頭CMS實作中,將內容片段有效率地傳送至JavaScript用戶端:

  • 避免重複的API要求,就像REST一樣,
  • 確保交付內容僅限於特定要求,
  • 允許大量傳送呈現為單一API查詢回應所需的內容。
注意

GraphQL目前用於Adobe Experience Manager(AEM)的兩個(個別)藍本中,做為雲端服務:

GraphQL API

GraphQL是:

  • "…API的查詢語言,以及使用您現有資料完成這些查詢的執行時期。 GraphQL提供您API中資料的完整且易於理解的描述,讓客戶能夠要求確切的所需內容,而不需要其他內容,讓API隨著時間推移而更容易發展,並提供功能強大的開發人員工具。"。

    請參閱GraphQL.org

  • "…開放式規格,以提供有彈性的API圖層。 將GraphQL置於您現有的後端,以前所未有的速度建立產品……."。

    請參閱瀏覽GraphQL

  • 」…Facebook於2012年在內部開發了一種資料查詢語言和規範,2015年在公開開源於Facebook。它為基於REST的體系結構提供了替代方案,其目的是提高開發人員的生產力並將傳輸的資料量減至最少。 GraphQL由數百個各種規模的組織在生產中使用……"

    請參見GraphQL Foundation

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

適用於AEM實作的GraphQL是以標準GraphQL Java程式庫為基礎。 請參閱:

GraphQL術語

GraphQL使用下列功能:

  • 查詢

  • 結構和類型:

    • 結構描述是由AEM根據內容片段模型產生。
    • 使用您的結構描述,GraphQL顯示GraphQL在AEM實施中允許的類型和操作。
  • 欄位

  • GraphQL端點

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

    • 有關詳細資訊,請參見啟用GraphQL端點

有關詳細資訊,請參閱(GraphQL.org)GraphQL簡介,包括 Best Practices

GraphQL查詢類型

使用GraphQL,您可以執行查詢以返回:

適用於AEM端點的GraphQL

端點是用來存取GraphQL for AEM的路徑。 您(或您的應用程式)可以使用此路徑:

  • 訪問GraphQL模式,
  • 發送您的GraphQL查詢,
  • 接收響應(對您的GraphQL查詢)。

GraphQL for AEM端點的儲存庫路徑為:

/content/cq:graphql/global/endpoint

您的應用程式可在請求URL中使用下列路徑:

/content/_cq_graphql/global/endpoint.json

若要啟用GraphQL for AEM的端點,您需要:

注意

這些步驟在不久的將來可能會有所改變。

啟用GraphQL端點

注意

如需Adobe提供的套件的詳細資訊,請參閱支援套件以簡化這些步驟。

若要在AEM中啟用GraphQL查詢,請在/content/cq:graphql/global/endpoint處建立端點:

  • 節點cq:graphqlglobal必須為sling:Folder類型。
  • 節點endpoint必須為nt:unstructured類型,並包含graphql/sites/components/endpointsling:resourceType
注意

每個人都能存取端點。 這可能會——尤其是在發佈例項上——造成安全性顧慮,因為GraphQL查詢可能會對伺服器造成沈重負載。

您可以在端點上設定與您的使用案例相應的ACL。

注意

您的端點不會立即可用。 您必須分別為GraphQL端點提供其他配置

注意

此外,您還可以使用GraphiQL IDE測試和調試GraphQL查詢。

GraphQL端點的其他配置

注意

如需Adobe提供的套件的詳細資訊,請參閱支援套件以簡化這些步驟。

需要其他配置:

  • Dispatcher:
    • 若要允許必要的URL
    • 必要
  • 虛名 URL:
    • 為端點分配簡化的URL
    • 可選
  • OSGi配置:
    • GraphQL Servlet配置:
      • 處理對端點的請求
      • 配置名稱為org.apache.sling.graphql.core.GraphQLServlet。 它需要作為OSGi工廠配置提供
      • sling.servlet.extensions 必須設為 [json]
      • sling.servlet.methods 必須設為 [GET,POST]
      • sling.servlet.resourceTypes 必須設為 [graphql/sites/components/endpoint]
      • 必要
    • 架構Servlet配置:
      • 建立GraphQL模式
      • 配置名稱為com.adobe.aem.graphql.sites.adapters.SlingSchemaServlet。 它需要作為OSGi工廠配置提供
      • sling.servlet.extensions 必須設為 [GQLschema]
      • sling.servlet.methods 必須設為 [GET]
      • sling.servlet.resourceTypes 必須設為 [graphql/sites/components/endpoint]
      • 必要
    • CSRF配置:
      • 端點的安全保護
      • 配置名稱為com.adobe.granite.csrf.impl.CSRFFilter
      • /content/cq:graphql/global/endpoint新增至現有的已排除路徑清單(filter.excluded.paths)
      • 必要

支援軟體包

為簡化GraphQL端點的設定,Adobe提供了GraphQL Sample Project套件。

此存檔同時包含所需的附加配置 GraphQL端點。 如果安裝在普通AEM實例上,則會在/content/cq:graphql/global/endpoint處顯示完全工作的GraphQL端點。

此軟體包旨在成為您自己的GraphQL項目的藍圖。 有關如何使用軟體包的詳細資訊,請參閱軟體包​README

如果您偏好手動建立所需的組態,Adobe也提供專屬的GraphQL端點內容套件。 此內容包僅包含GraphQL端點,無需任何配置。

圖形QL介面

標準GraphiQL介面的實作可與AEM GraphQL搭配使用。 這可與AEM](#installing-graphiql-interface)一起安裝。[

此介面可讓您直接輸入並測試查詢。

例如:

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

它提供語法反白顯示、自動完成、自動建議等功能,以及歷史記錄和線上檔案:

GraphiQL接

安裝AEM GraphiQL介面

GraphiQL使用者介面可安裝在AEM上,並附上專用的套件:GraphiQL Content Package v0.0.4套件。

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

使用案例可視AEM的雲端服務環境類型而定:

  • 發佈環境;用於:

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

    • 查詢資料以「進行內容管理」:
      • AEM中的GraphQL(雲端服務)目前是唯讀API。
      • REST API可用於CR(u)D操作。

權限

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

方案生成

GraphQL是強式型別的API,這表示資料必須依類型清楚地結構化和組織。

GraphQL規範提供了一系列指引,說明如何建立用於查詢特定實例上資料的強穩API。 為此,客戶端需要讀取Schema,該包含查詢所需的所有類型。

對於內容片段,GraphQL結構(結構和類型)基於​Enabled 內容片段模型及其資料類型。

注意

所有GraphQL結構(衍生自​Enabled​的內容片段模型)都可通過GraphQL端點讀取。

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

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

  1. 內容片段模型:

    用於GraphQL的內容片

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

    這表示產生的類型ArticleModel包含數個欄位

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

    • AEM會自動新增其他欄位,並代表提供特定內容片段相關資訊的實用方法;在此範例中,_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則保持不變。

注意

請務必注意,以防您透過REST api或其他方式對內容片段模型進行大量更新。

模式通過與GraphQL查詢相同的端點服務,客戶端處理以GQLschema副檔名調用模式的事實。 例如,對/content/cq:graphql/global/endpoint.GQLschema執行簡單的GET請求將導致輸出具有Content-type的架構:text/x-graphql-schema;charset=iso-8859-1

欄位

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

  • 您產生的欄位。

    選擇欄位類型會用來根據您的內容片段模型設定欄位。 欄位名稱取自​資料類型​的​屬性名稱​欄位。

    • 還有​Render As​屬性要考慮,因為用戶可以配置某些資料類型;例如,單行文字或多欄位。
  • GraphQL for AEM也會產生許多協助欄位

    這些用來識別內容片段,或取得內容片段的詳細資訊。

欄位類型

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

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

輔助欄位

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

路徑

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

  • 在AEM中是唯一的,
  • 很容易被牽扯。

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

{
  personList {
    items {
      _path
    }
  }
}

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

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

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

中繼資料

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

由於中繼資料是透過架構編輯器產生,因此沒有特定結構,因此TypedMetaData GraphQL類型已實作以公開內容片段的中繼資料。 TypedMetaData 公開按以下標量類型分組的資訊:

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

每個標量類型代表單個名稱——值對或名稱——值對陣列,其中該對的值是其所分組的類型。

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

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

{
  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允許將變數放在查詢中。 有關詳細資訊,請參見GraphiQL的GraphQL文檔。

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

GraphQL變

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

GraphQL指令

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

例如,您可以在查詢中根據變數includePrice包含adventurePrice欄位,以查詢所有AdventureModels

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端點

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

CORS篩選

注意

如需AEM中CORS資源共用原則的詳細概觀,請參閱瞭解跨原始資源共用(CORS)

若要存取GraphQL端點,必須在客戶Git儲存庫中設定CORS原則。 若要這麼做,請新增適當的OSGi CORS設定檔,以用於所需的端點。

此配置必須指定必須授予訪問權的受信任網站源alloworiginalloworiginregexp

例如,要授予對https://my.domain的GraphQL端點的訪問權,可使用:

{
  "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"
  ]
}

如果您已為端點配置虛名路徑,也可以在allowedpaths中使用該路徑。

反向連結篩選器

除了CORS設定外,必須設定「反向連結」篩選器,才能允許第三方主機的存取。

若要這麼做,請新增適當的OSGi反向連結篩選設定檔案,其中:

  • 指定可信網站主機名;allow.hostsallow.hosts.regexp,
  • 授予此主機名的訪問權限。

例如,若要授與反向連結my.domain的請求存取權,您可以:

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

客戶仍有責任:

  • 僅授與受信任網域的存取權
  • 確保未公開任何敏感資訊
  • 不使用通配符[*]語法;這既將禁用對GraphQL端點的驗證訪問,也將它向全世界公開。
注意

所有GraphQL 方案(衍生自​已啟用​的內容片段模型)都可通過GraphQL端點讀取。

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

驗證

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

常見問題

出現的問題:

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

    • :「AEM GraphQL API提供JSON輸出的完整控制,是查詢內容的業界標準。未來,AEM將計畫投資AEM GraphQL API。"

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

正在尋找實作教學課程? 請參閱AEM無頭和GraphQL端對端教學課程,說明如何在無頭CMS案例中,使用AEM的GraphQL API建立和公開內容,並由外部應用程式使用。

本頁內容

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free