创建和管理数据订阅

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

前提条件

  • 已准备 Product API Base URL、个人访问令牌和接收工作区 ID。

  • 发布方已把当前工作区加入目标列表。

  • 当前身份具有数据订阅权限，并已取得用于挂载共享数据库的目标数据目录 ID。

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

数据订阅流程

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

列出收到的数据订阅

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 包含数据发布来源、表列表和数据订阅状态：

{
  "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 搜索数据发布名称、对象和发布方信息。状态值以列表实际返回为准。

创建数据订阅

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

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。

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

{
  "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 状态码认定所有表都可查询。

取消订阅

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

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 和源数据发布状态

先读取数据目录元数据，再检查发布方是否更新或删除了数据发布。

无法取消

数据订阅是否正在创建、取消或已被发布方撤销

重新列出数据订阅，按最新状态决定是否重试。

下一步

最后更新于