在数据 API 生成器中托管 GraphQL 终结点

配置为通过 GraphQL 提供的实体在默认路径上可用:https://{base_url}//graphql。 数据 API 生成器自动生成 GraphQL 架构,其中包含所有已配置的实体的查询和突变字段。 可以使用包含自动完成等功能的新式 GraphQL 客户端来探索 GraphQL 架构。

如果遵循 入门 示例,其中 books 和为 GraphQL 访问配置的 authors 实体,则可以了解如何轻松使用 GraphQL。

结果集格式

返回的结果是采用以下格式的 JSON 对象:

{
    "data": {}    
}

备注

默认情况下,仅返回前 100 个项目。

支持的根类型

数据 API 生成器支持以下 GraphQL 根类型:

查询突变

查询

每个实体都支持以下操作:

除非另有指定,否则数据 API 生成器将使用实体 单一 名称,只要查询应返回单个项。 相反,每当预期查询返回项列表时,数据 API 生成器都使用实体 复数 名称。 例如,book 实体具有:

  • book_by_pk():返回零个或一个实体
  • books():返回零个或多个实体的列表

分页

返回零个或多个项的所有查询类型都支持分页:

{
  books
  {
    items {
      title
    }
    hasNextPage
    endCursor
  }
}
  • item 对象允许访问实体字段
  • 如果返回更多项目,则 hasNextPage 设置为 true
  • endCursor 返回可用于 firstafter 查询参数的不透明游标字符串,以获取项的下一组(或页面)。

按主键查询

每个实体都支持使用以下查询格式通过其主键检索特定项:

<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

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

orderby 的值设置返回结果集中项的顺序。 例如:

{
  books(orderBy: {title: ASC} )
  {
    items {
      id
      title
    }
  }
}

此查询返回按 title排序的书籍。

firstafter

参数 first 限制返回的项数。 例如:

query {
  books(first: 5)
  {
    items {
      id
      title
    }
    hasNextPage
    endCursor
  }
}

此查询返回前五本书。 如果未指定 orderBy,则根据基础主键对项进行排序。 提供给 orderBy 的值必须是正整数。

如果 book 实体中的项数多于通过 first请求的实体,则 hasNextPage 字段的计算结果为 trueendCursor 将返回可用于 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 数据库类型创建。

下表列出了为每个数据库类型创建事务的隔离级别。

数据库类型 隔离级别 详细信息
Azure SQL (或) SQL Server 已提交读取 Azure SQL
MySQL 可重复读取 MySQL
PostgreSQL 已提交读取 PostgreSQL