数据 API 生成器中的扩展数据库对象

2024-06-07

数据 API 生成器支持视图和存储过程，作为映射到数据库表或容器的替代方法。这些不同的数据库对象需要自定义配置才能无缝映射到 REST 或 GraphQL 终结点。某些自定义配置需要使用具有视图和存储过程的数据 API 生成器。

本文详细介绍了如何将视图和存储过程与数据 API 生成器结合使用。

视图

视图可用于类似于在数据 API 生成器中使用表的方式。必须通过将实体的源类型指定为 view来定义视图用法。此外，还必须提供 key-fields 属性，以便数据 API 生成器知道它如何识别和返回单个项（如果需要）。

如果有视图，例如，可以使用以下 dab 命令公开视图 dbo.vw_books_details：

dab add BookDetail --source dbo.vw_books_details --source.type View --source.key-fields "id" --permissions "anonymous:read"

注意

通过 CLI 生成配置时，视图必须 --source.key-fields。

dab-config.json 文件类似于以下示例：

"BookDetail": {
  "source": {
    "type": "view",
    "object": "dbo.vw_books_details",
    "key-fields": [ "id" ]
  },
  "permissions": [{
    "role": "anonymous",
    "actions": [ "read" ]
  }]
}

注意

请注意，应相应地配置权限，以便视图可更新或不。如果视图不可更新，则只能允许基于该视图对实体的读取访问权限。

对视图的 REST 支持

从 REST 的角度来看，视图的行为类似于表。支持所有 REST 操作。

GraphQL 对视图的支持

从 GraphQL 的角度来看，视图的行为类似于表。支持所有 GraphQL 操作。

存储过程

存储过程可用作与数据 API 生成器公开的实体相关的对象。必须定义存储过程用法，以指定实体的源类型 stored-procedure。

注意

数据 API 生成器支持关系数据库的存储过程（即 MSSQL），但不支持非关系数据库（即 NoSQL）。

如果有存储过程，例如 dbo.stp_get_all_cowritten_books_by_author 可以使用以下 dab 命令公开它：

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "get" --graphql.operation "query"

dab-config.json 文件类似于以下示例：

"GetCowrittenBooksByAuthor": {
  "source": {
    "type": "stored-procedure",
    "object": "dbo.stp_get_all_cowritten_books_by_author",
    "parameters": {
      "searchType": "s"
    }
  },
  "rest": {
    "methods": [ "GET" ]
  },
  "graphql": {
    "operation": "query"
  },
  "permissions": [{
   "role": "anonymous",
    "actions": [ "execute" ]
  }]
}

parameters 定义应公开哪些参数，并提供要传递给存储过程参数的默认值（如果未在 HTTP 请求中提供这些参数）。

限制

数据 API 生成器仅使用存储过程返回的第一个结果集。
仅支持 sys.dm_exec_describe_first_result_set 描述的第一个结果集的元数据的存储过程。
对于 REST 和 GraphQL 终结点：在配置文件和 URL 查询字符串中同时指定存储过程参数时，URL 查询字符串中的参数优先。
存储过程支持的实体没有为表、集合或视图支持的实体自动提供的所有功能。
- 存储过程支持的实体不支持分页、排序或筛选。此类实体也不支持返回主键值指定的项。
- 不支持字段/参数级别授权规则。

对存储过程的 REST 支持

可以将存储过程支持的实体的 REST 终结点行为配置为支持一个或多个 HTTP 谓词（GET、POST、PUT、PATCH、DELETE）。实体的 REST 部分类似于以下示例：

"rest": {
  "methods": [ "GET", "POST" ]
}

使用配置中未列出的 HTTP 方法时，实体的任何 REST 请求都失败，HTTP 405 方法不允许。例如，执行 PUT 请求失败，错误代码为 405。如果从实体的 REST 配置中排除节，则会推断 POST 的默认方法。若要禁用此实体的 REST 终结点，请配置 "rest": false，并且存储过程实体上的任何 REST 请求都失败，HTTP 404 找不到。

如果存储过程接受参数，则使用 GET HTTP 谓词调用 REST 终结点时，可以在 URL 查询字符串中传递参数。例如：

GET http://<dab-server>/api/GetCowrittenBooksByAuthor?author=isaac%20asimov

使用其他 HTTP 谓词（例如 POST、PUT、PATCH、DELETE）执行的存储过程要求在请求正文中将参数作为 JSON 传递。例如：

POST http://<dab-server>/api/GetCowrittenBooksByAuthor

{
  "author": "isaac asimov"
}

对存储过程的 GraphQL 支持

可以使用存储过程支持的实体的 graphql 选项配置 GraphQL 中的存储过程执行。通过显式设置实体的操作，可以采用与存储过程的行为一致的方式在 GraphQL 架构中表示存储过程。

注意

GraphQL 要求架构中存在 Query 元素。如果只公开存储过程，请确保至少有一个存储过程支持 query 操作，否则会收到 GraphQL 错误，如 The object type Query has to at least define one field in order to be valid.

不为操作设置任何值会导致创建 mutation 操作。

例如，使用 operation 选项的值 query 会导致存储过程解析为 GraphQL 架构中的查询字段。

CLI 用法：

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "GET" --graphql.operation "query"

运行时配置：

"graphql": {
  "operation": "query"
}

GraphQL 架构组件：类型和查询字段：

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

在架构中，存储过程的查询和突变操作 execute 作为前缀。对于前面的存储过程，生成的确切查询名称字段将 executeGetCowrittenBooksByAuthor。生成的 GraphQL 类型为：

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

或者，可以将 operation 设置为 mutation，以便突变字段表示 GraphQL 架构中的存储过程。 dab update 命令可用于更改 operation：

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

运行时配置：

"graphql": {
  "operation": "mutation"
}

生成的 GraphQL 架构为：

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

如果存储过程接受参数，则可以将这些参数作为查询或突变的参数传递。例如：

query {
  executeGetCowrittenBooksByAuthor(author:"asimov")
   {
    id
    title
    pages
    year
  }
}

通过