快速入门：将数据 API 生成器与 NoSQL 配合使用

2025-06-11

在本快速入门中，你将生成一组数据 API 生成器配置文件，以面向 Azure Cosmos DB for NoSQL 模拟器。

先决条件

Docker
.NET 8
数据管理客户端
- 如果没有安装客户端，请安装 Azure Data Studio

小窍门

或者，在 GitHub Codespaces 中打开本快速入门，其中包含已安装的所有开发人员先决条件。只需自带 Azure 订阅即可。 GitHub 帐户包括使用免费的存储和核心小时数的权利。有关详细信息，请参阅包含的 GitHub 帐户存储和核心小时数。

安装数据 API 生成器 CLI

将 NuGet 中的 Microsoft.DataApiBuilder 包安装为 .NET 工具。

使用dotnet tool install来安装带有--global参数的Microsoft.DataApiBuilder的最新版本。
```
dotnet tool install --global Microsoft.DataApiBuilder
```
注释

如果包已安装，请改用 dotnet tool update更新包。
```
dotnet tool update --global Microsoft.DataApiBuilder
```
请使用--global参数验证工具dotnet tool list是否已安装。
```
dotnet tool list --global
```

配置本地数据库

首先运行本地模拟器。然后，可以使用示例数据为新容器设定种子。

从 Docker Hub 获取最新容器镜像 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest。
```
docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest
```

通过发布端口 8081 和端口范围 10250-10255 启动 docker 容器。

docker run \
    --publish 8081:8081 \
    --publish 10250-10255:10250-10255 \
    --detach \
    mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

下载模拟器的自签名证书

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt

使用适用于 Linux 的 Bash 步骤或适用于 Windows 的 PowerShell 步骤安装自签名证书。

sudo cp ~/emulatorcert.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

certutil -f -addstore "Root" emulatorcert.crt

使用首选数据管理环境连接到本地数据库。示例包括但不限于： Azure Data Studio 和用于 Visual Studio Code 的 Azure 数据库扩展。

小窍门

模拟器的默认连接字符串为 AccountEndpoint=https://localhost:8081;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;。
创建新的 bookshelf 数据库和 authors 容器。

使用此基本 JSON 数据为容器设定种子。

[
  {
    "id": "01",
    "firstName": "Henry",
    "lastName": "Ross"
  },
  {
    "id": "02",
    "firstName": "Jacob",
    "middleName": "A.",
    "lastName": "Hancock"
  },
  {
    "id": "03",
    "firstName": "Sydney",
    "lastName": "Mattos"
  },
  {
    "id": "04",
    "firstName": "Jordan",
    "lastName": "Mitchell"
  },
  {
    "id": "05",
    "firstName": "Victoria",
    "lastName": "Burke"
  },
  {
    "id": "06",
    "firstName": "Vance",
    "lastName": "DeLeon"
  },
  {
    "id": "07",
    "firstName": "Reed",
    "lastName": "Flores"
  },
  {
    "id": "08",
    "firstName": "Felix",
    "lastName": "Henderson"
  },
  {
    "id": "09",
    "firstName": "Avery",
    "lastName": "Howard"
  },
  {
    "id": "10",
    "firstName": "Violet",
    "lastName": "Martinez"
  }
]

小窍门

用于初始化数据的方法很大程度上取决于数据管理工具。对于 Azure Data Studio，可以将此 JSON 数组保存为 .json 文件，然后使用 “导入 ”功能。

创建配置文件

使用 DAB CLI 创建基线配置文件。然后，使用当前凭据添加开发环境配置文件。

使用此架构内容创建名为 schema.graphql 的新文件。

type Author @model {
  id: ID!
  firstName: String!
  middleName: String
  lastName: String!
}

使用 dab init.. 创建典型配置文件。添加--connection-string参数，该参数具有模拟器的默认连接字符串。

dab init --database-type "cosmosdb_nosql" --host-mode "Development" --cosmosdb_nosql-database bookshelf --graphql-schema schema.graphql --connection-string "AccountEndpoint=https://localhost:8081;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;"

使用 dab add 添加一个 Author 实体。

dab add Author --source "authors" --permissions "anonymous:*"

使用本地数据库测试 API

现在，启动数据 API 生成器工具，验证配置文件在开发过程中是否已合并。

使用 dab start 来运行该工具并为您的实体创建 API 终结点。
```
dab start
```
该工具的输出应包含用于导航到正在运行的 API 的地址。
```
      Successfully completed runtime initialization.
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: <http://localhost:5000>
info: Microsoft.Hosting.Lifetime[0]
```
小窍门

在此示例中，应用程序在端口 5000 上运行localhost。正在运行的应用程序可能有不同的地址和端口。
导航到 /graphql 并运行此操作，从而访问 GraphQL 终结点。
```
query {
  authors {
    items {
      id
      firstName
      lastName
    }
  }
}
```
小窍门

在此示例中，URL 为 https://localhost:5000/graphql. 可以使用 Web 浏览器导航到此 URL。

后续步骤

快速入门：将数据 API 生成器部署到 Azure

通过