# 创建和管理数据发布

本页说明发布方如何把一个数据库中的指定表共享给一个或多个目标工作区，并在目标或表发生变化时更新数据发布。

## 前提条件

- 已准备 Product API Base URL、个人访问令牌和发布工作区 ID。
- 当前身份可以读取源数据库，并具有数据发布权限。
- 已取得源数据库 ID、数据库名称、要发布的表名和目标工作区 ID。

当前数据发布对象类型为数据库，`obj_type` 必须是 `db`。`tables` 中填写该数据库内的表名，不要填写其他数据库中的全限定名称。

## 数据发布流程

```text
确认源数据库和表
→ 解析并确认目标工作区
→ 检查数据发布名称
→ 创建数据发布并保存 publish_id
→ 列出或更新数据发布
→ 删除数据发布
```

## 解析目标工作区

如果调用方只保存了目标工作区 ID，可先解析显示名称，让用户在发布前确认接收方：

```bash
curl -X POST "$PRODUCT_API_BASE_URL/data-share/workspaces/resolve-names" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["<TARGET_WORKSPACE_ID>"]
  }'
```

该接口只返回工作区 ID 和名称。它用于确认目标，不会创建数据发布或授予权限。

## 检查数据发布名称

数据发布名称在当前发布工作区内不能重复：

```bash
curl --get "$PRODUCT_API_BASE_URL/data-share/publishes/check-name" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "name=orders-share"
```

只有响应中的 `data.available` 为 `true` 时，才继续创建。检查结果只反映本次请求时的状态；并发创建时仍可能发生名称冲突。

## 创建数据发布

```bash
curl -X POST "$PRODUCT_API_BASE_URL/data-share/publishes" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders-share",
    "obj_id": "<DATABASE_ID>",
    "obj_name": "sales",
    "obj_type": "db",
    "tables": ["orders"],
    "target_workspace_ids": ["<TARGET_WORKSPACE_ID>"],
    "remark": "供销售分析使用"
  }'
```

| 字段 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 是 | 数据发布名称，不得包含空格、引号或反引号。 |
| `obj_id` | string | 是 | 源数据库 ID。 |
| `obj_name` | string | 是 | 源数据库名称，应与 `obj_id` 指向同一对象。 |
| `obj_type` | string | 是 | 当前固定为 `db`。 |
| `obj_path` | string | 否 | 源对象路径；只有从数据目录（Catalog）响应取得明确路径时才发送。 |
| `tables` | string[] | 是 | 要纳入数据发布的表名，名称不能重复。 |
| `target_workspace_ids` | string[] | 是 | 接收工作区 ID，不能包含当前发布工作区，也不能重复。 |
| `remark` | string | 否 | 发布用途或维护说明。 |

成功响应返回数据发布对象：

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "<PUBLISH_ID>",
    "name": "orders-share",
    "obj_id": "<DATABASE_ID>",
    "obj_name": "sales",
    "obj_type": "db",
    "tables": ["orders"],
    "targets": [
      {
        "workspace_id": "<TARGET_WORKSPACE_ID>",
        "workspace_name": "<TARGET_WORKSPACE_NAME>"
      }
    ],
    "remark": "供销售分析使用"
  }
}
```

保存 `data.id` 作为 `publish_id`。`targets` 是服务确认后的接收方列表；创建后应使用它核对授权范围。

## 查询和更新数据发布

使用分页列表检查当前工作区的数据发布：

```bash
curl --get "$PRODUCT_API_BASE_URL/data-share/publishes" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20"
```

列表响应中的 `data.list` 保存数据发布对象，`data.total` 表示符合条件的总数。可使用 `keyword` 搜索数据发布名称或对象信息。

修改表、目标工作区或备注时，向 `PUT /data-share/publishes/{publish_id}` 发送需要改变的字段：

```bash
curl -X PUT "$PRODUCT_API_BASE_URL/data-share/publishes/$PUBLISH_ID" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": ["orders", "customers"],
    "remark": "增加客户表"
  }'
```

更新表或目标工作区会改变现有接收方可见的数据范围。修改前检查依赖该共享数据的查询、语义模型和工作流，并在更新后重新读取数据发布。

## 删除数据发布

```bash
curl -X DELETE "$PRODUCT_API_BASE_URL/data-share/publishes/$PUBLISH_ID" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

删除数据发布会影响目标工作区中的现有数据订阅。删除前先通知接收方，并确认下游查询和任务已经停止或迁移。请求失败时不要反复创建替代数据发布；先重新列出数据发布，判断原数据发布是否仍然存在。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 名称不可用 | 当前数据发布列表和名称拼写 | 复用已有数据发布或选择新名称。 |
| 创建参数无效 | `obj_type`、数据库 ID、表名和目标工作区 ID | 重新从数据目录和工作区接口取得标识，不手工猜测 ID。 |
| 目标工作区收不到数据发布 | 创建响应中的 `targets` | 确认目标工作区 ID，并检查接收方的数据订阅列表。 |
| 更新后部分表不可见 | `tables` 是否覆盖了原值 | 发送完整的目标表集合，再让接收方重新检查数据订阅。 |
| 删除发生冲突 | 数据发布是否正在更新或数据订阅状态正在变化 | 重新读取状态和列表，等待前一操作结束后再决定是否重试。 |

## 下一步

- [让目标工作区创建数据订阅](subscribe-data.md)
- [查找数据库和表 ID](../data-files-connectors/databases-tables.md)
- [了解分页和异步任务](../../common/pagination-async-idempotency.md)