用于内容片段的 AEM GraphQL API

了解如何在Adobe Experience Manager (AEM)中将内容片段与AEM GraphQL API一起使用来投放Headless内容。

与内容片段一起使用的AEM GraphQL API很大程度上基于标准的开源GraphQL API。

在 AEM 中使用 GraphQL API 可以在 Headless CMS 实施中，高效地将内容片段投放到 JavaScript 客户端：

• 避免 REST 中的迭代 API 请求，
• 确保将投放限制到特定要求，
• 允许作为对单个 API 查询的响应，批量精确投放所需呈现的内容。

前提条件

使用GraphQL的客户应安装AEM内容片段以及GraphQL索引包1.0.5。请参阅 发行说明 了解更多详细信息。

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 和 CND）

持久查询是推荐用于发布实例的方法：

• 它们被缓存
• 它们由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 操作。

权限

访问Assets需要权限。

GraphQL查询是在基础请求的AEM用户的权限下运行的。 如果用户对某些片段（存储为资产）没有读取权限，它们不会成为结果集的一部分。

此外，用户必须有权访问GraphQL端点才能运行GraphQL查询。

架构生成

GraphQL是一种类型的API，这意味着数据必须结构明确且按类型组织。

GraphQL 规范提供了一系列准则，说明如何创建可靠的 API 用于询问特定实例上的数据。要完成这些准则，客户端必须获取 架构，其中包含查询所需的所有类型。

对于内容片段，GraphQL 架构（结构和类型）基于​已启用内容片段模型及其数据类型。

例如，如果创建内容片段模型的用户调用 Article，则 AEM 生成 GraphQL 类型 ArticleModel。此类型中的字段对应于在模型中定义的字段和数据类型。此外，它还为操作此类型的查询创建一些入口点，例如 articleByPath 或 articleList。

1. 内容片段模型：

   

2. 对应的 GraphQL 架构（来自 GraphiQL 自动文档的输出）：
   

   此图像显示了生成的类型 ArticleModel 包含多个 字段.

   • 其中三个由用户控制： author， main、和 referencearticle.

   • 其他字段由AEM自动添加，表示用于提供有关特定内容片段的有用方法。在此示例中， 帮助程序字段) _path， _metadata， _variations.

3. 用户基于 Article 模型创建内容片段之后，可以通过 GraphQL 询问该模型。例如，请参阅示例查询（基于用于 GraphQL 的示例内容片段结构）。

在 GraphQL for AEM 中，架构是灵活的。这种灵活性意味着每次创建、更新或删除内容片段模型时都会自动生成模型。 数据架构缓存还可在更新内容片段模型时刷新。

Sites GraphQL 服务监听（在后台）对内容片段模型所作的任何更改。检测到更新时，仅重新生成架构的该部分。此优化可节省时间并提供稳定性。

例如，如果您：

1. 安装包含 Content-Fragment-Model-1 和 Content-Fragment-Model-2 的软件包：

   1. GraphQL类型 Model-1 和 Model-2 生成。

2. 然后修改 Content-Fragment-Model-2：

   1. 仅 Model-2 GraphQL类型将更新。

   2. 而 Model-1 保持不变。

架构通过与 GraphQL 查询相同的端点提供，客户端处理使用扩展 GQLschema 调用架构的实际情况。例如，执行简单 GET 请求日期 /content/cq:graphql/global/endpoint.GQLschema 导致输出具有内容类型的架构： text/x-graphql-schema;charset=iso-8859-1.

架构生成 – 未发布的模型

当内容片段嵌套时，可能会出现的情况是发布了父内容片段模型，但未发布引用的模型。

发生这种情况时，AEM会生成 未完成 父内容片段模型的架构。 这意味着依赖于未发布模型的片段引用将从架构中删除。

字段

在架构中，有两个基本类别的单独字段：

• 您生成的字段。

  使用选择的一组数据类型，根据您配置内容片段模型的方式来创建字段。字段名称获取自​数据类型​的​属性名称​字段。

  • 还有 呈现为 设置，因为用户可以配置某些数据类型。 例如，通过选择将单行文本字段配置为包含多个单行文本 multifield 从下拉菜单中查找。

• GraphQL for AEM还生成多个 帮助程序字段.

  这些字段用于标识内容片段，或获取有关内容片段的更多信息。

数据类型

GraphQL for AEM 支持一个类型列表。所有支持的内容片段模型数据类型和对应的 GraphQL 类型呈现如下：

内容片段模型 – 数据类型	GraphQL 类型	描述
单行文本	String、[String]	用于简单字符串，例如作者名称和位置名称。
多行文本	String	用于输出文本，例如文章的正文
数字	Float, [Float]	用于显示浮点数和常规数字
布尔型	Boolean	用于显示复选框 → 简单的 true/false 语句
日期和时间	Calendar	用于显示日期和时间，使用 ISO 8086 格式。根据选择的类型，有三种风格可用于 AEM GraphQL 中：onlyDate、onlyTime、dateTime
枚举	String	用于显示在模型创建时定义的选项列表中的选项
标记	[String]	用于显示表示在 AEM 中所用标记的字符串列表
内容引用	String	用于显示指向 AEM 中其他资源的路径
片段引用	模型类型 单个字段：Model-模型类型，直接引用 多字段，具有一个引用类型：[Model]-数组类型Model，直接从数组中引用 多字段，带有多个引用类型；[AllFragmentModels]-所有模型类型的数组，从具有合并类型的数组中引用	用于引用创建模型时定义的特定模型类型的一个或多个内容片段

帮助程序字段

除了用户生成的字段的数据类型之外，GraphQL for AEM还生成多个字段 辅助函数 帮助标识内容片段或提供有关内容片段的附加信息的字段。

这些帮助程序字段使用前缀 _ 标记，用于区分哪些字段由用户定义，哪些字段为自动生成。

路径

路径字段用作 AEM GraphQL 中的标识符。它代表 AEM 存储库中内容片段资源的路径。此路径被选为内容片段的标识符，因为它：

• 在 AEM 中唯一
• 可以轻松地提取

以下代码显示基于内容片段模型创建的所有内容片段的路径 Person.

{
  personList {
    items {
      _path
    }
  }
}

要检索特定类型的单个内容片段，您还必须首先确定其路径。 例如：

{
  authorByPath(_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。

请参阅元数据的示例查询 – 列出标题为 GB 的奖励的元数据。

变体

_variations 字段已实施以简化查询内容片段具有的变体。例如：

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

请参阅示例查询 – 具有指定变量的所有城市。

GraphQL 变量

GraphQL 允许在查询中放入变量。有关更多信息，请参阅 变量的GraphQL文档.

例如，要获取具有特定变体的类型为 Article 的所有内容片段，您可以在 GraphiQL 中指定变量 variation。

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

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

GraphQL 指令

在GraphQL中，可以根据变量更改查询，这称为GraphQL指令。

例如，您可在针对所有 AdventureModels、基于变量 includePrice 的查询中包含 adventurePrice 字段。

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

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

筛选

您还可以筛选 GraphQL 查询以返回特定数据。

筛选使用基于逻辑运算符和表达式的语法。

最原子的部分是可以应用于特定字段内容的单个表达式。它将字段的内容与给定的常量值进行比较。

例如，以下表达式会将字段的内容与值进行比较 some text，如果内容等于该值，则成功。 否则，表达式将失败。：

{
  value: "some text"
  _op: EQUALS
}

以下运算符可用于将字段与特定值进行比较：

运算符	类型	如果…，则表达式成功
EQUALS	String、ID、Boolean	…该值与该字段的内容相同
EQUALS_NOT	String、ID	… 该值与该字段的内容​不​完全相同
CONTAINS	String	…字段的内容包含值({ value: "mas", _op: CONTAINS } 匹配 Christmas， Xmas， master， …)
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 匹配 TIME， time， tImE， …
_sensitiveness	Float	允许有一定的余地，将 float 值视为相同（以解决由于 float 值的内部表示引起的技术限制；应该避免，因为此选项可能有负面影响对性能的影响

表达式可以在逻辑运算符 (_logOp) 的帮助下组合成一个集合：

• OR — 如果至少有一个表达式成功，则表达式集成功
• AND — 如果所有表达式都成功，则表达式集将成功（默认）

每个字段都可以通过其自己的一组表达式进行过滤。过滤器参数中提到的所有字段的表达式集最终由其自己的逻辑运算符组合。

过滤器定义（作为 filter 参数传递给查询）包含：

• 每个字段的子定义(可通过其名称访问该字段，例如，有一个 lastName 的过滤器中的字段 lastName 字段类型)
• 每个子定义包含 _expressions 数组，提供表达式集和 _logOp 定义表达式应与之组合的逻辑运算符的字段
• 每个表达式由值（value 字段）和运算符（_operator 字段）定义，字段的内容应该与之进行比较

您可以省略 _logOp 如果要将项目与 AND 和 _operator 如果要检查是否相等，因为这些值是默认值。

以下示例演示了一个完整的查询，该查询过滤所有 lastName 为 Provo 或包含 sjö 的人员，与大小写无关：

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

虽然您也可以对嵌套字段进行筛选，但不建议这样做，因为这可能会导致性能问题。

有关更多示例，请参阅：

• GraphQL for AEM 扩展的详细信息

• 使用此示例内容和结构的示例查询

  • 以及准备用于示例查询的示例内容和结构

• 基于 WKND 项目的示例查询

排序

此功能允许您根据指定字段对查询结果进行排序。

排序标准：

• 是以逗号分隔的值列表，表示字段路径
  • 列表中的第一个字段定义主要排序顺序
    • 如果主要排序标准的两个值相等，则使用第二个字段
    • 如果前两个标准相等，则使用第三个字段，依此类推。
  • 点分符号，即field1.subfield.subfield等……
• 带有可选的订单方向
  • ASC（升序）或 DESC（降序）；作为默认 ASC 应用
  • 可以按字段指定方向；这种能力意味着您可以对一个字段进行升序排序，对另一个字段进行降序排序(name， firstName DESC)

例如：

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

也可以：

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

您还可以使用 nestedFragmentname.fieldname 的格式对嵌套片段中的字段进行排序。

例如：

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

分页

此功能允许您对返回列表的查询类型执行分页。提供了两种方法：

• 在 List 查询中的 offset 和 limit
• 在 Paginated 查询中的 first 和 after

列表查询 – 偏移和限制

在 ...List 查询中，您可以使用 offset 和 limit 返回特定的结果子集：

• offset：指定要返回的第一个数据集
• limit：指定返回的最大数据集数

例如，要输出最多包含五篇文章的结果页面，从​完整​结果列表中的第五篇文章开始：

query {
   articleList(offset: 5, limit: 5) {
    items {
      authorFragment {
        lastName
        firstName
      }
    }
  }
}

分页查询 – 先和后

...Paginated 查询类型重用了大部分 ...List 查询类型功能（过滤、排序），但没有使用 offset/limit 参数，它使用 first/after 参数，正如 GraphQL 光标连接规范所定义。您可以在 GraphQL 介绍 中找到不太正式的介绍。

• first：n要返回的第一个项目。
  默认为 50。最大值为 100。
• after：确定所请求页面开始的光标。游标所表示的项目不包括在结果集中。 项目的光标由 cursor 字段 edges 结构。

例如，输出包含最多五次冒险的结果页面，从​完整​结果列表中的给定光标项开始：

query {
    adventurePaginated(first: 5, after: "ODg1MmMyMmEtZTAzMy00MTNjLThiMzMtZGQyMzY5ZTNjN2M1") {
        edges {
          cursor
          node {
            title
          }
        }
        pageInfo {
          endCursor
          hasNextPage
        }
    }
}

GraphQL for AEM – 执行摘要

使用 GraphQL for AEM 的查询基本处理遵循标准 GraphQL 规范。对于使用AEM的GraphQL查询，有几个扩展：

• 如果您需要单个结果：

  • 使用模型名称；例如city

• 如果您需要结果列表：

  • 将 List 添加到模型名称；例如，cityList
  • 请参阅示例查询 – 关于所有城市的所有信息

  稍后您可以：

  • 对结果进行排序

    • ASC : 升序
    • DESC : 降序

  • 使用以下任一方法返回一页结果：

    • 带有偏移和限制的列表查询
    • 带有“先”和“后”的分页查询

  • 请参阅示例查询 – 关于所有城市的所有信息

• 筛选条件 includeVariations 包含在 List 查询类型。 要在查询结果中检索内容片段变体，请 includeVariations 筛选器必须设置为 true.

  注意

  筛选条件 includeVariations 不能与系统生成的字段一起使用 _variation.

• 如果您希望使用逻辑 OR：

  • 使用 _logOp: OR
  • 请参阅示例查询 – 所有名为“Jobs”或“Smith”的人

• 逻辑 AND 也可使用，不过（通常）是隐式的

• 您可以查询与内容片段模型中字段对应的字段名称

  • 请参阅示例查询 – 公司的 CEO 和员工的完整详细信息

• 除了来自您模型的字段以外，还有一些系统生成的字段（以下划线为前缀）：

  • 对于内容：

    • _locale：用于显示语言；基于语言管理器

      • 请参阅给定区域设置的多个内容片段的示例查询

    • _metadata：用于显示片段的元数据

      • 请参阅元数据的示例查询 – 列出标题为 GB 的奖励的元数据

    • _model：允许查询内容片段模型（路径和标题）

      • 请参阅来自模型的内容片段模型的示例查询

    • _path：存储库中内容片段的路径

      • 请参阅示例查询 – 一个特定城市片段

    • _reference：用于显示引用，包括富文本编辑器中的内联引用

      • 请参阅具有预获取引用的多个内容片段的示例查询

    • _variation：用于显示内容片段中的特定变体

      注意

      如果内容片段不存在给定的变量，则主控变量将作为（回退）默认值返回。

      注意

      系统生成的字段 _variation 不能与过滤器一起使用 includeVariations.

      • 请参阅示例查询 – 具有指定变体的所有城市

    • _tags ：用于显示包含标记的内容片段或变体的ID；此列表由多个 cq:tags 标识符。

      • 参见 示例查询 — 标记为城市分隔符的所有城市的名称
      • 参见 附加了特定标记的给定模型的内容片段变体示例查询
      注意

      标记也可以通过列出内容片段的元数据来查询。

      * 以及操作：

    • _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. 问：适用于 AEM 的 GraphQL API 与查询生成器 API 有何不同？

   • 答：
     AEM GraphQL API 提供了对 JSON 输出的全面控制，是用于查询内容的行业标准。
     将来，AEM计划投资于AEM GraphQL API。”

教程 – AEM Headless 和 GraphQL 快速入门

正在寻找实践教程？签出 AEM Headless和GraphQL快速入门 端到端教程，其中演示了如何在Headless CMS场景中使用AEM GraphQL API构建和公开内容并由外部应用程序使用。