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

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

如果你按照 入门 示例进行操作，其中配置了用于 GraphQL 访问的 books 实体和 authors 实体，你就可以看到使用 GraphQL 是多么简单。

结果集格式

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

{
    "data": {}    
}

支持的根类型

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

查询突变

查询

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

• 分页
• 按主键查询
• 泛型查询

除非另有指定，否则 Data 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
  }
}

泛型查询

每个实体还支持通用查询模式，以便可以使用以下参数仅按所需顺序请求所需的项：

• filter：筛选返回的项目
• orderBy：定义如何对返回的数据进行排序
• first 和 after：仅返回顶部 n 项

例如：

{
  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 运算符包括：

orderBy

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

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

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

first 和 after

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 数据库类型创建。

[!INCLUDE[数据库隔离级别。./includes/database-isolation-levels.md]]