了解如何在 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 客户端:
GraphQL 当前用于 Adobe Experience Manager (AEM) as a Cloud Service 中的两种(分隔的)场景:
GraphQL 是:
“…一种用于 API 和运行时的查询语言,使用您的现有数据满足这些查询。GraphQL 提供了 API 中数据的完整且可理解的描述,使客户端能够精确地请求所需要的数据,避免其他多余内容,让 API 更容易随时间演进,并提供了强大的开发人员工具。”
请参阅 GraphQL.org。
“…一种面向灵活 API 层的开发规格。将 GraphQL 放在现有后端之上,相比从前能够更快地构建产品…”
请参阅探索 GraphQL。
“…一种数据查询语言和规范,由 Facebook 在 2012 年内部开发,然后在 2015 年公开开源发布。它提供了对基于 REST 的架构的替代,其目的是为了提高开发人员的工作效率并尽可能减少传输的数据量。GraphQL 已由各种规模的数百家组织用于生产环境中…”
请参阅 GraphQL 基础。
有关 GraphQL API 的更多信息,请参阅以下部分(以及多种其他资源):
位于 graphql.org:
位于 graphql.com:
GraphQL for AEM 实施基于标准 GraphQL Java 库。请参阅:
GraphQL 使用以下对象:
AEM 中的路径,对应于 GraphQL 查询,提供对 GraphQL 架构的访问。
有关更多详细信息,请参阅启用 GraphQL 端点。
请参阅 (GraphQL.org) GraphQL 简介获取全面的详细信息,包括最佳实践。
使用 GraphQL,您可以执行查询以返回:
单个条目
您还可以执行:
您可以使用 GraphiQL IDE 测试和调试 GraphQL 查询。
用例可以依赖于 AEM as a Cloud Service 环境的类型:
发布环境;用于:
创作环境;用于:
权限是访问 Assets 所需的权限。
GraphQL 是一种强类型的 API,这意味着数据必须有明确的结构并按类型整理。
GraphQL 规范提供了一系列准则,说明如何创建可靠的 API 用于询问特定实例上的数据。为执行此操作,客户端需要提取架构,其中包含查询所需的全部类型。
对于内容片段,GraphQL 架构(结构和类型)基于已启用内容片段模型及其数据类型。
所有 GraphQL 架构(派生自已启用的内容片段模型)可通过 GraphQL 端点读取。
这意味着您需要确保其中没有提供敏感数据,因为这种方式可能会导致泄露;例如,这包括可能在模型定义中作为字段名称呈现的信息。
例如,如果创建内容片段模型的用户调用 Article
,则 AEM 生成对象 article
,其类型为 ArticleModel
。此类型中的字段对应于在模型中定义的字段和数据类型。
内容片段模型:
对应的 GraphQL 架构(来自 GraphiQL 自动文档的输出):
这显示了生成的类型 ArticleModel
包含多个 字段。
其中三个由用户控制:author
、main
和 referencearticle
。
其他字段由 AEM 自动添加,表示用于提供有关特定内容片段的有用方法,在本例中为 _path
、_metadata
、_variations
。这些帮助程序字段使用前缀 _
标记,用于区分哪些字段由用户定义,哪些字段为自动生成。
用户基于 Article 模型创建内容片段之后,可以通过 GraphQL 询问该模型。例如,请参阅示例查询(基于用于 GraphQL 的示例内容片段结构)。
在 GraphQL for AEM 中,架构是灵活的。这意味着每次在创建、更新或删除内容片段模型时会自动生成架构。数据架构缓存还可在更新内容片段模型时刷新。
Sites GraphQL 服务监听(在后台)对内容片段模型所作的任何更改。检测到更新时,仅重新生成架构的该部分。此优化可节省时间并提供稳定性。
例如,如果您:
安装包含 Content-Fragment-Model-1
和 Content-Fragment-Model-2
的软件包:
Model-1
和 Model-2
的 GraphQL 类型。然后修改 Content-Fragment-Model-2
:
将只更新 Model-2
GraphQL 类型。
而 Model-1
将保持不变。
在您需要通过 REST api 或以其他方式批量更新内容片段模型时,这一点务必要注意。
架构通过与 GraphQL 查询相同的端点提供,客户端处理使用扩展 GQLschema
调用架构的实际情况。例如,在 /content/cq:graphql/global/endpoint.GQLschema
上执行简单的 GET
请求将导致架构的输出带有内容类型:text/x-graphql-schema;charset=iso-8859-1
。
当内容片段嵌套时,可能会出现的情况是发布了父内容片段模型,但未发布引用的模型。
AEM UI 可以防止出现这种情况,但是,如果以编程方式进行发布,或者使用内容包发布,则可能出现这种情况。
出现这种情况时,AEM 为父内容片段模型生成不完整的架构。这意味着依赖于未发布模型的片段引用会从架构中删除。
在架构中有两个基本类别的单独字段:
您生成的字段。
使用选择的一组字段类型,根据您配置内容片段模型的方式来创建字段。字段名称获取自数据类型的属性名称字段。
GraphQL for AEM 还生成多个帮助程序字段。
这些用于标识内容片段,或者获取有关内容片段的更多信息。
GraphQL for AEM 支持一个类型列表。所有支持的内容片段模型数据类型和对应的 GraphQL 类型呈现如下:
内容片段模型 - 数据类型 | GraphQL 类型 | 描述 |
---|---|---|
单行文本 | 字符串,[字符串] | 用于简单字符串,例如作者姓名、位置名称等 |
多行文本 | 字符串 | 用于输出文本,例如文章的正文 |
数值 | 浮点,[浮点] | 用于显示浮点数和常规数字 |
布尔型 | 布尔型 | 用于显示复选框 → 简单的 true/false 语句 |
日期和时间 | 日历 | 用于显示日期和时间,使用 ISO 8086 格式。根据选择的类型,有三种风格可用于 AEM GraphQL 中:onlyDate 、onlyTime 、dateTime |
枚举 | 字符串 | 用于显示在模型创建时定义的选项列表中的选项 |
标记 | [字符串] | 用于显示表示在 AEM 中所用标记的字符串列表 |
内容引用 | 字符串 | 用于显示指向 AEM 中其他资源的路径 |
片段引用 | 模型类型 | 用于引用特定模型类型的其他内容片段,在创建模型时定义 |
在用户生成的字段数据类型之外,GraphQL for AEM 还生成了多种帮助程序 字段,用于帮助标识内容片段,或者提供有关内容片段的额外信息。
路径字段用作 GraphQL 中的标识符。它代表 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]! |
每个标量类型表示一个名称-值对或者名称-值对数组,而该对的值是它所分组到的类型。
例如,如果您希望检索内容片段的标题,我们知道此属性是字符串属性,因此我们将查询所有字符串元数据:
要查询元数据,请执行以下操作:
{
personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
item {
_path
_metadata {
stringMetadata {
name
value
}
}
}
}
}
如果您查看生成的 GraphQL 架构,可以查看所有元数据 GraphQL 类型。所有模型类型具有相同的 TypedMetaData
。
普通和数组元数据之间的不同
请记住,StringMetadata
和 StringArrayMetadata
均引用存储在存储库中的内容,而非您如何检索它们。
举例而言,通过调用 stringMetadata
字段,您应该以 String
的形式收到存储在存储库中所有元数据的数组,如果您调用 stringArrayMetadata
,则会以 String[]
的形式收到存储在存储库中所有元数据的数组。
请参阅元数据的示例查询 - 列出标题为 GB 的奖励的元数据。
_variations
字段已实施以简化查询内容片段具有的变体。例如:
{
personByPath(_path: "/content/dam/path/to/fragment/john-doe") {
item {
_variations
}
}
}
GraphQL 允许在查询中放入变量。有关详细信息,请参阅 GraphQL 的变量文档。
例如,要获取具有特定变体的类型为 Article
的所有内容片段,您可以在 GraphiQL 中指定变量 variation
。
### query
query GetArticlesByVariation($variation: String!) {
articleList(variation: $variation) {
items {
_path
author
}
}
}
### in query variables
{
"variation": "Introduction"
}
在 GraphQL 中,可以更改基于变量的查询,这称为 GraphQL 指令。
例如,您可在针对所有 AdventureModels
、基于变量 includePrice
的查询中包含 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 扩展的详细信息
使用 GraphQL for AEM 的查询基本操作遵循标准 GraphQL 规范。对于用于 AEM 的 GraphQL 查询,有几个扩展:
如果您需要单个结果:
如果您需要结果列表:
List
添加到模型名称;例如,cityList
如果您希望使用逻辑 OR:
_logOp: OR
逻辑 AND 也可使用,不过(通常)是隐式的
您可以查询与内容片段模型中字段对应的字段名称
除了来自您模型的字段以外,还有一些系统生成的字段(以下划线为前缀):
对于内容:
_locale
:用于显示语言;基于语言管理器
_metadata
:用于显示片段的元数据
_model
:允许查询内容片段模型(路径和标题)
_path
:存储库中内容片段的路径
_reference
:用于显示引用,包括富文本编辑器中的内联引用
_variation
:用于显示内容片段中的特定变体
以及操作:
_operator
:应用特定运算符;EQUALS
、EQUALS_NOT
、GREATER_EQUAL
、LOWER
、CONTAINS
、STARTS_WITH
_apply
:用于应用特定条件,例如 AT_LEAST_ONCE
_ignoreCase
:在查询时忽略大小写
支持 GraphQL 合并类型:
... on
在查询嵌套片段时回退:
要从外部网站访问 GraphQL 端点,您需要配置:
请参阅对内容片段的远程 AEM GraphQL 查询的身份验证。
出现的问题:
问:适用于 AEM 的 GraphQL API 与查询生成器 API 有何不同?
正在寻找实践教程?请查看 AEM Headless 和 GraphQL 快速入门端到端教程,其中说明了在 Headless CMS 场景中,如何使用 AEM GraphQL API 构建和公开内容并由外部应用程序使用。