# 数据发布与订阅

本页介绍如何通过 SDK 在源工作区发布指定数据库中的数据表，并在目标工作区查询与完成订阅。数据发布与订阅分别在源工作区和目标工作区下执行，各自返回独立的资源句柄和状态。

(sdk-ai-studio-data-share-flow)=
## 任务流程

```text
源工作区校验可发布表并创建发布 ──▶ 目标工作区查询待订阅列表 ──▶ 接受订阅并确认状态
```

(sdk-ai-studio-data-share-prepare)=
## 准备

1. 已按[使用 SDK](../../../quickstart/ai-studio/sdk.md)配置好客户端与个人访问令牌（`PRODUCT_API_BASE_URL`、`PRODUCT_API_KEY`），并分别取得源工作区 ID（`WORKSPACE_ID`）与目标工作区 ID（`TARGET_WORKSPACE_ID`）。
2. **源数据库 ID 与数据表 ID**：已通过[管理目录、数据库和表](管理目录、数据库和表.md)获取源数据库 ID（`SOURCE_DATABASE_ID`）及待发布的数据表 ID（`SOURCE_TABLE_ID`）；若已知源数据库 ID，也可在第 1 步读取可发布表清单时获取表 ID。
3. **发布名称、订阅名称与备注**：规划发布名称、目标工作区内的订阅名称及说明。本示例使用 `sdk_sales_publish` 与 `sdk_sales_subscription`，运行前请按实际业务修改。

在终端设置跨工作区分享所需的参数：

```bash
export TARGET_WORKSPACE_ID='<接收方工作区 ID>'
export SOURCE_DATABASE_ID='<源数据库 ID>'
export SOURCE_TABLE_ID='<待发布的表 ID>'
```

(sdk-ai-studio-data-share-publish-subscribe)=
## 1. 在源工作区创建数据发布

先读取源数据库的可发布表列表，确认目标表支持发布后，指定接收方工作区列表并创建数据发布。创建成功后，返回的发布句柄可用于后续更新发布范围、接收方工作区、备注或删除发布。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import os
import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"], os.environ["PRODUCT_API_KEY"]
)
source_workspace = client.workspace(os.environ["WORKSPACE_ID"])
target_workspace_id = os.environ["TARGET_WORKSPACE_ID"]
source_database_id = os.environ["SOURCE_DATABASE_ID"]
source_table_id = os.environ["SOURCE_TABLE_ID"]

source_tables = source_workspace.data_share_source_tables(source_database_id)
if source_table_id not in {item.id for item in source_tables.list}:
    raise ValueError("目标数据表不在可发布表列表中")

table_scope = sdk.DataShareScope(
    mode="selected",
    object_ids=[source_table_id],
)
publish, created = source_workspace.create_data_share_publish(
    "sdk_sales_publish",
    source_database_id,
    table_scope,
    [target_workspace_id],
    sdk.with_data_share_remark("SDK 数据分享示例"),
)
print("发布 ID:", publish.id, "发布名称:", created.name)
```

::::

::::{tab-item} Go
:sync: go

```go
package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"), os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	sourceWorkspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	targetWorkspaceID := os.Getenv("TARGET_WORKSPACE_ID")
	sourceDatabaseID := os.Getenv("SOURCE_DATABASE_ID")
	sourceTableID := os.Getenv("SOURCE_TABLE_ID")

	sourceTables, err := sourceWorkspace.DataShareSourceTables(ctx, sourceDatabaseID)
	if err != nil {
		panic(err)
	}
	shareable := false
	for _, table := range sourceTables.GetList() {
		if table.GetId() == sourceTableID {
			shareable = true
			break
		}
	}
	if !shareable {
		panic(fmt.Sprintf("目标数据表 %q 不在可发布表列表中", sourceTableID))
	}

	tableScope := &sdk.DataShareScope{
		Mode:      "selected",
		ObjectIds: []string{sourceTableID},
	}
	publish, created, err := sourceWorkspace.CreateDataSharePublish(
		ctx,
		"sdk_sales_publish",
		sourceDatabaseID,
		tableScope,
		[]string{targetWorkspaceID},
		sdk.WithDataShareRemark("SDK 数据分享示例"),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println("发布 ID:", publish.ID(), "发布名称:", created.GetName())
}
```

::::

:::::

## 2. 在目标工作区查询并完成订阅

切换到目标工作区句柄，列出可见的订阅记录并按发布名称定位对应的订阅项，随后调用订阅方法并确认返回状态为 `subscribed`。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
target_workspace = client.workspace(target_workspace_id)
subscriptions = target_workspace.data_share().subscriptions()
subscription_id = next(
    (item.id for item in subscriptions.list if item.pub_name == created.name),
    "",
)
if not subscription_id:
    raise RuntimeError("在目标工作区未找到对应的待订阅记录")

subscription = target_workspace.data_share_subscription(subscription_id)
subscribed = subscription.subscribe("sdk_sales_subscription")
if subscribed.status != "subscribed":
    raise RuntimeError(f"订阅状态异常: {subscribed.status}")
print("订阅完成，状态:", subscribed.status)
```

::::

::::{tab-item} Go
:sync: go

```go
targetWorkspace, err := client.Workspace(targetWorkspaceID)
if err != nil {
	panic(err)
}
subscriptions, err := targetWorkspace.DataShare().Subscriptions(ctx)
if err != nil {
	panic(err)
}
subscriptionID := ""
for _, item := range subscriptions.GetList() {
	if item.GetPubName() == created.GetName() {
		subscriptionID = item.GetId()
		break
	}
}
if subscriptionID == "" {
	panic(fmt.Sprintf("在目标工作区未找到发布 %q 对应的订阅记录", created.GetName()))
}

subscription, err := targetWorkspace.DataShareSubscription(subscriptionID)
if err != nil {
	panic(err)
}
subscribed, err := subscription.Subscribe(ctx, "sdk_sales_subscription")
if err != nil {
	panic(err)
}
if subscribed.GetStatus() != "subscribed" {
	panic(fmt.Sprintf("订阅状态异常: %s", subscribed.GetStatus()))
}
fmt.Println("订阅完成，状态:", subscribed.GetStatus())
```

::::

:::::

(sdk-ai-studio-data-share-result)=
(sdk-ai-studio-data-share-limit)=
订阅完成后，可在目标工作区重新读取订阅列表，核对订阅状态与生成的目标数据库信息。对外发布数据前，请仔细核实所选数据表范围、接收方工作区 ID 及当前账户的访问权限。

(sdk-ai-studio-data-share-next)=
## 下一步

- [管理目录、数据库和表](管理目录、数据库和表.md)：查看目标工作区订阅生成的数据库与表对象。
- [执行 SQL 查询](../数据处理/执行SQL查询.md)：在目标工作区查询已订阅的数据表。
