# 创建和管理数据订阅

本页说明接收方如何查看其他工作区发来的数据发布，创建数据订阅并把共享数据挂载到自己的数据目录（Catalog），或在不再使用时取消订阅。

## 前提条件

- 已准备 Product API Base URL、个人访问令牌和接收工作区 ID。
- 发布方已把当前工作区加入目标列表。
- 当前身份具有数据订阅权限，并已取得用于挂载共享数据库的目标数据目录 ID。

数据订阅操作使用数据订阅列表返回的 `subscription_id`，不是发布方保存的 `publish_id`。`location_id` 必须是当前接收工作区中的有效数据目录 ID。

## 数据订阅流程

```text
列出收到的数据订阅
→ 选择未订阅项并保存 subscription_id
→ 确认目标数据目录和本地数据库名
→ 创建数据订阅
→ 检查 status、sub_location_id 和 sub_name
→ 使用共享数据库或取消订阅
```

## 列出收到的数据订阅

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

成功响应中的 `data.list` 包含数据发布来源、表列表和数据订阅状态：

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "list": [
      {
        "id": "<SUBSCRIPTION_ID>",
        "pub_name": "orders-share",
        "obj_name": "sales",
        "obj_type": "db",
        "tables": ["orders"],
        "source_workspace_id": "<SOURCE_WORKSPACE_ID>",
        "source_workspace_name": "<SOURCE_WORKSPACE_NAME>",
        "status": "unsubscribed"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}
```

保存所选项的 `id`。在接受前，向用户展示 `source_workspace_name`、`pub_name`、`obj_name` 和 `tables`，避免只根据名称相似度挂载错误的数据。

可使用 `status` 筛选数据订阅，或使用 `keyword` 搜索数据发布名称、对象和发布方信息。状态值以列表实际返回为准。

## 创建数据订阅

选择本地数据库名和目标数据目录后发送：

```bash
curl -X POST "$PRODUCT_API_BASE_URL/data-share/subscriptions/$SUBSCRIPTION_ID/subscribe" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_name": "shared_sales",
    "location_id": "<CATALOG_ID>"
  }'
```

| 字段 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `subscription_id` | string | 是 | 路径参数，从数据订阅列表的 `id` 取得。必须是正整数格式的规范 ID。 |
| `sub_name` | string | 是 | 共享数据在接收工作区中的本地数据库名，不得包含空格、引号或反引号。 |
| `location_id` | string | 是 | 接收工作区中的目标数据目录 ID，使用正整数格式的规范 ID。 |

成功响应返回更新后的数据订阅：

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "<SUBSCRIPTION_ID>",
    "pub_name": "orders-share",
    "status": "subscribed",
    "sub_name": "shared_sales",
    "sub_location_id": "<CATALOG_ID>",
    "sub_location_path": "<CATALOG_PATH>",
    "subscribed_by": "<USER_ID>"
  }
}
```

以 `status`、`sub_name` 和 `sub_location_id` 判断挂载关系是否符合预期。请求成功后，再通过数据目录或 SQL 接口读取共享数据库；不要仅凭 HTTP 状态码认定所有表都可查询。

## 取消订阅

取消前检查查询、语义模型和工作流是否仍然引用共享数据库。确认后发送：

```bash
curl -X POST "$PRODUCT_API_BASE_URL/data-share/subscriptions/$SUBSCRIPTION_ID/unsubscribe" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

取消成功后重新列出数据订阅，确认其 `status` 已改变，并且 `sub_name` 和挂载位置已清除。取消订阅不会删除发布方的源数据库，也不会删除数据发布。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 列表中找不到数据发布 | 当前工作区 ID 和发布方的目标列表 | 让发布方核对创建响应中的 `targets`。 |
| 创建请求提示参数无效 | `subscription_id` 和 `location_id` 是否为正整数格式 | 从数据订阅列表和数据目录列表重新取得 ID。 |
| 已经订阅 | 列表中的 `status`、`sub_name` 和挂载位置 | 使用现有挂载，不重复提交接受请求。 |
| 数据订阅成功但无法查询 | 目标数据目录、表权限、数据发布的 `tables` 和源数据发布状态 | 先读取数据目录元数据，再检查发布方是否更新或删除了数据发布。 |
| 无法取消 | 数据订阅是否正在创建、取消或已被发布方撤销 | 重新列出数据订阅，按最新状态决定是否重试。 |

## 下一步

- [查询共享数据库的元数据](../sql/metadata-history.md)
- [运行 SQL 并读取结果](../sql/execute-results.md)
- [检查 Product API 身份认证](../../common/authentication.md)