# 接入扣子 Coze

在扣子智能体或工作流中调用 AskTable 查询数据。

扣子（Coze）是字节跳动的智能体搭建平台。把 AskTable 的官方插件加进去，你的扣子机器人就能用自然语言查 AskTable 上已经连好的数据源。插件背后调的是 AskTable 的 REST 接口，所以凭证和数据范围仍然在 AskTable 这一侧管。

## 开始前

- 一个 AskTable 项目，里面已有连好的数据源，并记下它的 ID（形如 `ds_xxxxxxxx`）。还没有数据源就先去[连接数据源](https://docs.asktable.com/data/connect)。
- 一个 `asker` 类型的项目 API-Key：左侧主导航 → 「设置」 → 「API-Key」 → 「创建 API-KEY」，在类型里选 `asker`。完整值形如 `ASKER_xxxxxxxx`，只在创建时显示一次。
- 一个扣子账号。
- 插件按最小权限用：不要用 `admin` Key。

## 操作步骤

**确认官方插件**

在扣子插件商店搜索 **AskTable**，选[一句话查 Excel 或数据库](https://www.coze.cn/store/plugin/7407079384349343784)。它查的是你已经连在 AskTable 里的数据源，Excel 和数据库都行。

**在智能体里添加插件**

打开扣子，创建一个智能体，填好基本信息。在智能体编辑页找到「插件」区，点「+」，搜索 AskTable，把「一句话查 Excel 或数据库」加进来。

**建两个变量**

在智能体的「变量」里建两个：

| 变量名        | 值                                         |
| ---------- | ----------------------------------------- |
| `at_auth`  | `Bearer YOUR_API_KEY`，注意 `Bearer` 后面有一个空格 |
| `at_ds_id` | 你的数据源 ID，形如 `ds_xxxxxxxx`                 |

**把插件参数绑到变量**

在插件的参数配置里：

- `Authorization` 绑定变量 `at_auth`。
- `datasource_ids` 是数组，添加一个数组项，值绑定变量 `at_ds_id`。要一次查多个数据源，就添加多个数组项，每项填一个数据源 ID。

**用预览调试**

用预览功能提一个数据问题，确认能返回结果。插件不传角色，所以数据范围等于这些数据源的全部内容；挑数据源时按最小够用原则来。

**工作流或对话流里同样配置**

在工作流或对话流里加一个 AskTable 插件节点，参数用同一套变量绑定：`Authorization` 保持 `Bearer YOUR_API_KEY` 的格式，`datasource_ids` 的数组项绑定 `at_ds_id`。

## 关键约束

| 项目               | 值或默认                    | 在哪里改                                  |
| ---------------- | ----------------------- | ------------------------------------- |
| API-Key 类型       | `asker`（最小权限）           | 扣子变量 `at_auth` 的值；源头在「设置」 → 「API-Key」 |
| `at_auth` 值格式    | `Bearer` 加一个空格，再接 Key   | 扣子「变量」                                |
| `at_ds_id` 值格式   | 数据源 ID，形如 `ds_xxxxxxxx` | 扣子「变量」                                |
| `datasource_ids` | 数组，可放多个数据源              | 扣子插件参数配置                              |
| 是否按角色限制数据范围      | 插件不传角色，范围等于所选数据源全集      | 靠选哪些数据源来控制                            |
| 数据源 ID 的来源       | 「数据源」页里复制               | 左侧主导航 → 「更多」 → 「数据源」                  |
| 项目 API-Key 数量    | 每个项目最多 10 个             | 「设置」 → 「API-Key」                      |

## 出问题怎么判断

| 现象           | 判定条件                                  | 处理                                                   |
| ------------ | ------------------------------------- | ---------------------------------------------------- |
| 插件调用报认证失败    | `at_auth` 的值缺 `Bearer ` 前缀，或 Key 已被删除 | 按 `Bearer YOUR_API_KEY` 的格式补齐；必要时到「设置」 → 「API-Key」重建 |
| 插件报数据源不存在    | `at_ds_id` 填的不是数据源 ID，或该 ID 属于别的项目    | 到「数据源」页复制正确的 ID                                      |
| 插件返回空结果      | 数据源里没有匹配的数据，或问题里没给够筛选条件               | 先确认同一个问题在网页「对话」里能问出结果，再改扣子里的问法                       |
| 预览时被拒        | 用的是 `admin` Key，或 Key 属于别的项目          | 换成目标项目的 `asker` Key                                  |
| 工作流节点报参数错误   | `datasource_ids` 不是数组，或数组项没绑定变量       | 把 `datasource_ids` 配成数组，逐项绑定 `at_ds_id`              |
| 换了一个数据源但回答没变 | `at_ds_id` 改了但插件参数仍指向旧变量              | 确认数组项绑的是 `at_ds_id`，改的是变量的值而不是插件的常量                  |

## 下一步

- 想按角色限制数据范围，自己传 `role_id`：[OpenAPI](https://docs.asktable.com/integrations/openapi)
- 让 AI 客户端直接调用 AskTable 的更多能力：[MCP](https://docs.asktable.com/integrations/mcp)
- 先把数据源连好：[连接数据源](https://docs.asktable.com/data/connect)