如何调用 GraphQL 终结点

使用数据 API 生成器 （DAB） 中的 GraphQL 终结点，可以精确查询和修改数据。 每个查询都准确声明所需的字段，并支持用于筛选、排序和分页结果的参数。

默认情况下，DAB 在以下位置托管其 GraphQL 终结点：

https://{base_url}/graphql

通过配置公开的实体会自动包含在 GraphQL 架构中。 例如，如果你有 books 实体和 authors 实体，则两者都显示为架构中的根字段。

注释

若要浏览架构和自动完成字段，请使用任何新式 GraphQL 客户端或 IDE（如 Apollo、Insomnia 或 Visual Studio Code GraphQL 扩展程序）。

数据 API 生成器支持的关键字

概念 GraphQL Purpose
投影 物品 选择要返回的字段
Filtering 滤波器 按条件限制行
排序 orderBy 定义排序顺序
页面大小 第一 限制每页的项目数
继续 后 从最后一页继续

基本结构

每个 GraphQL 查询都以表示实体的根字段开头。 所有 GraphQL 请求都使用 POST 向 /graphql 终结点发送，其中 JSON 正文包含查询。

{
  books {
    items {
      id
      title
      year
      pages
    }
  }
}

响应是一个 JSON 对象，其形状与选择集相同。 仅在适用情况下，才会显示分页和错误详细信息。

注释

默认情况下，除非另有配置（runtime.pagination.default-page-size）否则，DAB 每个查询最多返回 100 个项目。

POST https://localhost:5001/graphql
Content-Type: application/json

{
  "query": "{ books { items { id title year pages } } }"
}

成功：

{
  "data": {
    "books": {
      "items": [
        { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
        { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
      ]
    }
  }
}

分页成功：

{
  "data": {
    "books": {
      "items": [
        { "id": 1, "title": "Dune", "year": 1965, "pages": 412 },
        { "id": 2, "title": "Foundation", "year": 1951, "pages": 255 }
      ],
      "hasNextPage": true,
      "endCursor": "eyJpZCI6Mn0="
    }
  }
}

错误：

{
  "errors": [
    {
      "message": "Could not find item with the given key.",
      "locations": [{ "line": 1, "column": 3 }],
      "path": ["book_by_pk"]
    }
  ]
}

查询类型

每个实体支持两个标准根查询：

查询 说明
entity_by_pk 按主键返回一条记录
entities 返回与筛选器匹配的记录列表

返回一条记录的示例：

{
  book_by_pk(id: 1010) {
    title
    year
  }
}

返回多个示例：

{
  books {
    items {
      id
      title
    }
  }
}

筛选结果

filter使用参数限制返回的记录。

{
  books(filter: { title: { contains: "Foundation" } }) {
    items { id title }
  }
}

此查询返回其标题包含“Foundation”的所有书籍。

筛选器可以将比较与逻辑运算符组合在一起：

{
  authors(filter: {
    or: [
      { first_name: { eq: "Isaac" } }
      { last_name: { eq: "Asimov" } }
    ]
  }) {
    items { first_name last_name }
  }
}

请参阅筛选器参数参考以获取支持的运算符，例如eq、neq、lt、lte和isNull。

对结果进行排序

该 orderBy 参数定义记录的排序方式。

{
  books(orderBy: { year: DESC, title: ASC }) {
    items { id title year }
  }
}

这会返回按 year 降序排序的书籍，然后返回按降序排列的 title书籍。

有关详细信息，请参阅 orderBy 参数引用。

限制结果

该 first 参数限制单个请求中返回的记录数。

{
  books(first: 5) {
    items { id title }
  }
}

这会返回前五本书，默认情况下按主键排序。 您还可以使用 first: -1 来请求配置的最大页面大小。

在 第一个参数参考中了解详细信息。

后续结果

若要提取下一页，请使用上一个查询的游标参数after。

{
  books(first: 5, after: "eyJpZCI6NX0=") {
    items { id title }
  }
}

after 标记符号表示上一页结束的位置。 有关详细信息，请参阅 后的参数引用。

字段选择（投影）

在 GraphQL 中，选择在响应中确切显示哪些字段。 没有像 SELECT * 这样的通配符。 仅请求所需内容。

{
  books {
    items { id title price }
  }
}

还可以使用别名重命名响应中的字段：

{
  books {
    items {
      bookTitle: title
      cost: price
    }
  }
}

有关详细信息，请参阅 字段投影参考 。

修改数据

GraphQL 突变允许根据实体权限创建、更新和删除记录。

突变 Action
createEntity 创建新项
updateEntity 更新现有项
deleteEntity 删除一个项

注释

后 _by_pk 缀仅适用于 查询 （例如， book_by_pk）。 突变名称不包括此后缀-使用 updateBook 和 deleteBook，而不是 updateBook_by_pk 或 deleteBook_by_pk。

重要

GraphQL 突变需要活动数据库连接池。 如果您的连接字符串设置了Pooling=False 或MultipleActiveResultSets=False，突变将因错误Implicit distributed transactions have not been enabled 而失败。 为数据库提供程序设置 Pooling=True 和 MultipleActiveResultSets=True （SQL Server）或等效项。

小窍门

对于通过 GraphQL 公开的存储过程，DAB 将实体名称 execute作为前缀。 例如，命名 GetBookById 的存储过程实体将出现在 executeGetBookById 架构中。 有关详细信息，请参阅 存储过程。

创建新记录

使用create变更添加新项。

POST https://localhost:5001/graphql
Content-Type: application/json

{
  "query": "mutation { createBook(item: { id: 2000, title: \"Leviathan Wakes\", year: 2011, pages: 577 }) { id title year pages } }"
}

更新现有记录

使用update突变功能来修改现有项的特定字段。

POST https://localhost:5001/graphql
Content-Type: application/json

{
  "query": "mutation { updateBook(id: 2000, item: { title: \"Leviathan Wakes\", year: 2011, pages: 577 }) { id title year pages } }"
}

删除记录

使用delete变更来通过主键删除项目。

POST https://localhost:5001/graphql
Content-Type: application/json

{
  "query": "mutation { deleteBook(id: 2000) { id title } }"
}
  • 上次更新时间为