在数据 API 生成器中托管 GraphQL 终结点
配置为通过 GraphQL 提供的实体在默认路径上可用:https://{base_url}//graphql
。 数据 API 生成器自动生成 GraphQL 架构,其中包含所有已配置的实体的查询和突变字段。 可以使用包含自动完成等功能的新式 GraphQL 客户端来探索 GraphQL 架构。
如果遵循 入门 示例,其中 books
和为 GraphQL 访问配置的 authors
实体,则可以了解如何轻松使用 GraphQL。
返回的结果是采用以下格式的 JSON 对象:
{
"data": {}
}
数据 API 生成器支持以下 GraphQL 根类型:
查询突变
每个实体都支持以下操作:
除非另有指定,否则数据 API 生成器将使用实体 单一 名称,只要查询应返回单个项。 相反,每当预期查询返回项列表时,数据 API 生成器都使用实体 复数 名称。 例如,book
实体具有:
-
book_by_pk()
:返回零个或一个实体
-
books()
:返回零个或多个实体的列表
返回零个或多个项的所有查询类型都支持分页:
{
books
{
items {
title
}
hasNextPage
endCursor
}
}
-
item
对象允许访问实体字段
- 如果返回更多项目,则
hasNextPage
设置为 true
-
endCursor
返回可用于 first
和 after
查询参数的不透明游标字符串,以获取项的下一组(或页面)。
每个实体都支持使用以下查询格式通过其主键检索特定项:
<entity>_by_pk(<pk_colum>:<pk_value>)
{
<fields>
}
例如:
{
book_by_pk(id:1010) {
title
}
}
每个实体还支持通用查询模式,以便可以使用以下参数仅按所需顺序请求所需的项:
例如:
{
authors(
filter: {
or: [
{ first_name: { eq: "Isaac" } }
{ last_name: { eq: "Asimov" } }
]
}
) {
items {
first_name
last_name
books(orderBy: { year: ASC }) {
items {
title
year
}
}
}
}
}
filter
参数的值是使用实体字段的谓词表达式(返回布尔值的表达式)。 只有表达式的计算结果为“True”的项才会包含在响应中。 例如:
{
books(filter: { title: { contains: "Foundation" } })
{
items {
id
title
authors {
items {
first_name
last_name
}
}
}
}
}
此查询返回标题中带有单词 Foundation
的所有书籍。
filter
参数支持的运算符包括:
算子 |
类型 |
描述 |
例 |
eq |
比较 |
平等 |
books(filter: { title: { eq: "Foundation" } }) |
neq |
比较 |
不等于 |
books(filter: { title: { neq: "Foundation" } }) |
gt |
比较 |
大于 |
books(filter: { year: { gt: 1990 } }) |
gte |
比较 |
大于或等于 |
books(filter: { year: { gte: 1990 } }) |
lt |
比较 |
小于 |
books(filter: { year: { lt: 1990 } }) |
lte |
比较 |
小于或等于 |
books(filter: { year: { lte: 1990 } }) |
isNull |
比较 |
为 null |
books(filter: { year: { isNull: true} }) |
contains |
字符串 |
包含 |
books(filter: { title: { contains: "Foundation" } }) |
notContains |
字符串 |
不包含 |
books(filter: { title: { notContains: "Foundation" } }) |
startsWith |
字符串 |
开头 |
books(filter: { title: { startsWith: "Foundation" } }) |
endsWith |
字符串 |
结尾 |
books(filter: { title: { endsWith: "Empire" } }) |
and |
逻辑 |
逻辑和 |
authors(filter: { and: [ { first_name: { eq: "Robert" } } { last_name: { eq: "Heinlein" } } ] }) |
or |
逻辑 |
逻辑或 |
authors(filter: { or: [ { first_name: { eq: "Isaac" } } { first_name: { eq: "Dan" } } ] }) |
orderby
的值设置返回结果集中项的顺序。 例如:
{
books(orderBy: {title: ASC} )
{
items {
id
title
}
}
}
此查询返回按 title
排序的书籍。
参数 first
限制返回的项数。 例如:
query {
books(first: 5)
{
items {
id
title
}
hasNextPage
endCursor
}
}
此查询返回前五本书。 如果未指定 orderBy
,则根据基础主键对项进行排序。 提供给 orderBy
的值必须是正整数。
如果 book
实体中的项数多于通过 first
请求的实体,则 hasNextPage
字段的计算结果为 true
,endCursor
将返回可用于 after
参数的字符串来访问下一项。 例如:
query {
books(first: 5, after: "W3siVmFsdWUiOjEwMDQsIkRpcmVjdGlvbiI6MCwiVGFibGVTY2hlbWEiOiIiLCJUYWJsZU5hbWUiOiIiLCJDb2x1bW5OYW1lIjoiaWQifV0=")
{
items {
id
title
}
hasNextPage
endCursor
}
}
对于每个实体,将自动创建支持创建、更新和删除操作的突变。 此突变操作使用以下名称模式创建:<operation><entity>
。 例如,对于 book
实体,突变为:
-
createbook
:创建新书籍
-
updatebook
:更新现有书籍
-
deletebook
:删除指定的书籍
若要创建所需实体的新元素,将提供 create<entity>
突变。 创建的突变需要 item
参数,其中指定了创建新项时要使用的实体必填字段的值。
create<entity>(item: <entity_fields>)
{
<fields>
}
例如:
mutation {
createbook(item: {
id: 2000,
title: "Leviathan Wakes"
}) {
id
title
}
}
若要更新所需实体的元素,将提供 update<entity>
突变。 更新突变需要两个参数:
-
<primary_key>
,主键列的键值列表和相关值,用于标识要更新的元素
-
item
:参数,包含实体的必填字段值,在更新指定项时使用
update<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,] item: <entity_fields>)
{
<fields>
}
例如:
mutation {
updatebook(id: 2000, item: {
year: 2011,
pages: 577
}) {
id
title
year
pages
}
}
若要删除所需实体的元素,将提供 delete<entity>
突变。 要删除的元素的主键是必需参数。
delete<entity>(<pk_colum>:<pk_value>, [<pk_colum>:<pk_value> ... <pk_colum>:<pk_value>,])
{
<fields>
}
例如:
mutation {
deletebook(id: 1234)
{
id
title
}
}
为了处理典型的 GraphQL 突变请求,数据 API 生成器将构造两个数据库查询。 其中一个数据库查询执行与突变关联的更新(或)插入(或)删除操作。
另一个数据库查询提取选择集中请求的数据。
数据 API 生成器在事务中执行两个数据库查询。 事务仅针对 SQL 数据库类型创建。
下表列出了为每个数据库类型创建事务的隔离级别。