Mud Tools

Appearance

租户任务清单动态订阅 - (IFeishuTenantV2TaskActivitySubscriptions) ​

功能描述 ​

任务清单动态订阅功能，允许为任务清单创建和管理订阅，当清单发生相应事件时会向订阅者发送通知消息。该接口使用租户令牌进行认证，适用于企业管理员对组织内任务清单的统一管理。

参考文档 ​

https://open.feishu.cn/document/task-v2/tasklist-activity_subscription/create

函数列表 ​

函数名称功能描述认证方式HTTP 方法
CreateActivitySubscriptionsAsync为一个清单创建一个订阅，包含1个或多个订阅者租户令牌POST
GetActivitySubscriptionsByIdAsync获取指定订阅的详细信息，包括名称、订阅者、可通知的event key列表等租户令牌GET
GetActivitySubscriptionsListByIdAsync获取指定清单的所有订阅信息，按照订阅的创建时间排序租户令牌GET
UpdateActivitySubscriptionsByIdAsync更新指定清单的动态订阅信息租户令牌PATCH
DeleteActivitySubscriptionsByIdAsync删除指定的动态订阅，删除后的数据不可恢复租户令牌DELETE

函数详细内容 ​

创建动态订阅 ​

函数签名：

csharp
Task<FeishuApiResult<TasklistActivitySubscriptionResult>?> CreateActivitySubscriptionsAsync(
    [Path] string tasklist_guid,
    [Body] CreateActivitySubscriptionsRequest createActivitySubscriptionsRequest,
    [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

  • ✅ tasklist_guid (string): 任务清单全局唯一GUID，示例值："d300a75f-c56a-4be9-80d1-e47653028ceb"
  • ✅ createActivitySubscriptionsRequest (CreateActivitySubscriptionsRequest): 创建动态订阅请求体
  • ⚪ user_id_type (string): 用户ID类型，默认值为Consts.User_Id_Type
  • ⚪ cancellationToken (CancellationToken): 取消操作令牌对象

响应：

json
{
  "code": 0,
  "data": {
    "activity_subscription": {
      "activity_subscription_guid": "33991879-704f-444f-81d7-55a6aa7be80c",
      "name": "项目任务订阅",
      "tasklist_guid": "d300a75f-c56a-4be9-80d1-e47653028ceb",
      "subscribers": [
        {
          "subscriber_id": "chat_123",
          "subscriber_type": "chat",
          "name": "项目组群聊"
        }
      ],
      "event_keys": ["task.created", "task.completed"]
    }
  },
  "msg": "success"
}

说明：为一个清单创建一个订阅。每个订阅可以包含1个或多个订阅者（目前只支持普通群组）。订阅创建后，如清单发生相应的事件，则会向订阅里的订阅者发送通知消息。一个清单最多可以创建50个订阅。每个订阅最大支持50个订阅者。

代码示例：

typescript
const createActivitySubscriptionsRequest = {
  name: "项目进度订阅",
  subscribers: [
    {
      subscriber_id: "chat_project_team",
      subscriber_type: "chat"
    },
    {
      subscriber_id: "chat_managers",
      subscriber_type: "chat"
    }
  ],
  event_keys: [
    "task.created",
    "task.completed",
    "task.due_date_changed"
  ]
};

const response = await feishuTenantClient.createActivitySubscriptions(
  "d300a75f-c56a-4be9-80d1-e47653028ceb",
  createActivitySubscriptionsRequest
);

console.log("动态订阅创建成功:", response.data.activity_subscription);

获取动态订阅详情 ​

函数签名：

csharp
Task<FeishuApiResult<TasklistActivitySubscriptionResult>?> GetActivitySubscriptionsByIdAsync(
   [Path] string tasklist_guid,
   [Path] string activity_subscription_guid,
   [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

  • ✅ tasklist_guid (string): 任务清单全局唯一GUID，示例值："d300a75f-c56a-4be9-80d1-e47653028ceb"
  • ✅ activity_subscription_guid (string): 订阅GUID，示例值："33991879-704f-444f-81d7-55a6aa7be80c"
  • ⚪ user_id_type (string): 用户ID类型，默认值为Consts.User_Id_Type
  • ⚪ cancellationToken (CancellationToken): 取消操作令牌对象

响应：

json
{
  "code": 0,
  "data": {
    "activity_subscription": {
      "activity_subscription_guid": "33991879-704f-444f-81d7-55a6aa7be80c",
      "name": "项目任务订阅",
      "tasklist_guid": "d300a75f-c56a-4be9-80d1-e47653028ceb",
      "subscribers": [
        {
          "subscriber_id": "chat_123",
          "subscriber_type": "chat",
          "name": "项目组群聊"
        }
      ],
      "event_keys": ["task.created", "task.completed"],
      "created": "2024-01-01T10:00:00Z",
      "updated": "2024-01-01T15:30:00Z"
    }
  },
  "msg": "success"
}

说明：提供一个清单的GUID和一个订阅的GUID，获取该订阅的详细信息，包括名称，订阅者，可通知的event key列表等。

代码示例：

typescript
const response = await feishuTenantClient.getActivitySubscriptionsById(
  "d300a75f-c56a-4be9-80d1-e47653028ceb",
  "33991879-704f-444f-81d7-55a6aa7be80c"
);

console.log("订阅详情:", response.data.activity_subscription);
console.log("订阅者数量:", response.data.activity_subscription.subscribers.length);
console.log("监听事件:", response.data.activity_subscription.event_keys);

获取动态订阅列表 ​

函数签名：

csharp
Task<FeishuApiListResult<TasklistActivitySubscriptionInfo>?> GetActivitySubscriptionsListByIdAsync(
   [Path] string tasklist_guid,
   [Query("limit")] int limit = 50,
   [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
   CancellationToken cancellationToken = default);

认证：租户令牌

参数：

  • ✅ tasklist_guid (string): 任务清单全局唯一GUID，示例值："d300a75f-c56a-4be9-80d1-e47653028ceb"
  • ⚪ limit (int): 返回结果的最大数量，默认值：50
  • ⚪ user_id_type (string): 用户ID类型，默认值为Consts.User_Id_Type
  • ⚪ cancellationToken (CancellationToken): 取消操作令牌对象

响应：

json
{
  "code": 0,
  "data": {
    "items": [
      {
        "activity_subscription_guid": "33991879-704f-444f-81d7-55a6aa7be80c",
        "name": "项目任务订阅",
        "tasklist_guid": "d300a75f-c56a-4be9-80d1-e47653028ceb",
        "subscriber_count": 2,
        "event_count": 3,
        "created": "2024-01-01T10:00:00Z",
        "updated": "2024-01-01T15:30:00Z"
      },
      {
        "activity_subscription_guid": "44992980-815g-555g-92e8-66b7bb8cf91d",
        "name": "紧急任务订阅",
        "tasklist_guid": "d300a75f-c56a-4be9-80d1-e47653028ceb",
        "subscriber_count": 1,
        "event_count": 2,
        "created": "2024-01-02T09:15:00Z",
        "updated": "2024-01-02T09:15:00Z"
      }
    ]
  },
  "msg": "success"
}

说明：给定一个清单的GUID，获取其所有的订阅信息。结果按照订阅的创建时间排序。

代码示例：

typescript
// 获取清单的所有订阅
const response = await feishuTenantClient.getActivitySubscriptionsListById(
  "d300a75f-c56a-4be9-80d1-e47653028ceb",
  {
    limit: 100 // 获取最多100个订阅
  }
);

console.log("清单订阅列表:", response.data.items);

// 统计订阅信息
const totalSubscriptions = response.data.items.length;
const totalSubscribers = response.data.items.reduce((sum, sub) => sum + sub.subscriber_count, 0);

console.log(`清单共有 ${totalSubscriptions} 个订阅，涉及 ${totalSubscribers} 个订阅者`);

// 按创建时间排序查看订阅
const sortedByCreated = response.data.items.sort((a, b) => 
  new Date(a.created).getTime() - new Date(b.created).getTime()
);

console.log("按创建时间排序的订阅:", sortedByCreated);

更新动态订阅 ​

函数签名：

csharp
Task<FeishuApiListResult<TasklistActivitySubscriptionResult>?> UpdateActivitySubscriptionsByIdAsync(
      [Path] string tasklist_guid,
      [Path] string activity_subscription_guid,
      [Body] UpdateActivitySubscriptionsRequest updateActivitySubscriptionsRequest,
      [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
      CancellationToken cancellationToken = default);

认证：租户令牌

参数：

  • ✅ tasklist_guid (string): 任务清单全局唯一GUID，示例值："d300a75f-c56a-4be9-80d1-e47653028ceb"
  • ✅ activity_subscription_guid (string): 订阅GUID，示例值："33991879-704f-444f-81d7-55a6aa7be80c"
  • ✅ updateActivitySubscriptionsRequest (UpdateActivitySubscriptionsRequest): 更新动态订阅请求体
  • ⚪ user_id_type (string): 用户ID类型，默认值为Consts.User_Id_Type
  • ⚪ cancellationToken (CancellationToken): 取消操作令牌对象

响应：

json
{
  "code": 0,
  "data": [
    {
      "activity_subscription_guid": "33991879-704f-444f-81d7-55a6aa7be80c",
      "name": "更新后的项目订阅",
      "tasklist_guid": "d300a75f-c56a-4be9-80d1-e47653028ceb",
      "subscribers": [
        {
          "subscriber_id": "chat_new_team",
          "subscriber_type": "chat",
          "name": "新项目组群聊"
        }
      ],
      "event_keys": ["task.created", "task.completed", "task.due_date_changed", "task.assigned"],
      "created": "2024-01-01T10:00:00Z",
      "updated": "2024-01-02T14:20:00Z"
    }
  ],
  "msg": "success"
}

说明：提供一个清单的GUID和一个动态订阅的GUID，对其进行更新。更新时，将update_fields字段中填写所有要修改的字段名，同时在activity_subscription字段中填写要修改的字段的新值即可。

代码示例：

typescript
const updateActivitySubscriptionsRequest = {
  update_fields: ["name", "subscribers", "event_keys"],
  activity_subscription: {
    name: "更新后的项目订阅",
    subscribers: [
      {
        subscriber_id: "chat_new_team",
        subscriber_type: "chat"
      },
      {
        subscriber_id: "chat_backup_team",
        subscriber_type: "chat"
      }
    ],
    event_keys: [
      "task.created",
      "task.completed", 
      "task.due_date_changed",
      "task.assigned",
      "task.deleted"
    ]
  }
};

const response = await feishuTenantClient.updateActivitySubscriptionsById(
  "d300a75f-c56a-4be9-80d1-e47653028ceb",
  "33991879-704f-444f-81d7-55a6aa7be80c",
  updateActivitySubscriptionsRequest
);

console.log("订阅更新成功:", response.data[0]);
console.log("更新后的订阅者数量:", response.data[0].subscribers.length);
console.log("更新后监听的事件:", response.data[0].event_keys);

删除动态订阅 ​

函数签名：

csharp
Task<FeishuNullDataApiResult?> DeleteActivitySubscriptionsByIdAsync(
  [Path] string tasklist_guid,
  [Path] string activity_subscription_guid,
  [Query("user_id_type")] string user_id_type = Consts.User_Id_Type,
  CancellationToken cancellationToken = default);

认证：租户令牌

参数：

  • ✅ tasklist_guid (string): 任务清单全局唯一GUID，示例值："d300a75f-c56a-4be9-80d1-e47653028ceb"
  • ✅ activity_subscription_guid (string): 订阅GUID，示例值："33991879-704f-444f-81d7-55a6aa7be80c"
  • ⚪ user_id_type (string): 用户ID类型，默认值为Consts.User_Id_Type
  • ⚪ cancellationToken (CancellationToken): 取消操作令牌对象

响应：

json
{
  "code": 0,
  "data": null,
  "msg": "success"
}

说明：给定一个清单的GUID和一个订阅的GUID，将其删除。删除后的数据不可恢复，请谨慎操作。

代码示例：

typescript
const response = await feishuTenantClient.deleteActivitySubscriptionsById(
  "d300a75f-c56a-4be9-80d1-e47653028ceb",
  "33991879-704f-444f-81d7-55a6aa7be80c"
);

if (response.code === 0) {
  console.log("动态订阅删除成功");
} else {
  console.log("删除失败:", response.msg);
}

// 删除前可以先检查订阅是否存在
try {
  const checkResponse = await feishuTenantClient.getActivitySubscriptionsById(
    "d300a75f-c56a-4be9-80d1-e47653028ceb",
    "33991879-704f-444f-81d7-55a6aa7be80c"
  );
  
  console.log("订阅存在，准备删除:", checkResponse.data.activity_subscription.name);
  
  const deleteResponse = await feishuTenantClient.deleteActivitySubscriptionsById(
    "d300a75f-c56a-4be9-80d1-e47653028ceb",
    "33991879-704f-444f-81d7-55a6aa7be80c"
  );
  
  console.log("订阅删除成功");
} catch (error) {
  console.log("订阅不存在或已被删除");
}

管理场景示例 ​

完整的订阅管理流程 ​

typescript
// 1. 创建多个订阅
const tasklistGuid = "d300a75f-c56a-4be9-80d1-e47653028ceb";

// 创建项目主要订阅
const mainSubscription = await feishuTenantClient.createActivitySubscriptions(
  tasklistGuid,
  {
    name: "项目主要订阅",
    subscribers: [
      { subscriber_id: "chat_project_team", subscriber_type: "chat" }
    ],
    event_keys: ["task.created", "task.completed", "task.due_date_changed"]
  }
);

// 创建紧急任务订阅
const urgentSubscription = await feishuTenantClient.createActivitySubscriptions(
  tasklistGuid,
  {
    name: "紧急任务订阅",
    subscribers: [
      { subscriber_id: "chat_managers", subscriber_type: "chat" }
    ],
    event_keys: ["task.created", "task.completed"]
  }
);

// 2. 查看所有订阅
const allSubscriptions = await feishuTenantClient.getActivitySubscriptionsListById(
  tasklistGuid,
  { limit: 100 }
);

console.log("当前所有订阅:", allSubscriptions.data.items);

// 3. 更新主要订阅
const updateMainSubscription = await feishuTenantClient.updateActivitySubscriptionsById(
  tasklistGuid,
  mainSubscription.data.activity_subscription.activity_subscription_guid,
  {
    update_fields: ["subscribers"],
    activity_subscription: {
      subscribers: [
        { subscriber_id: "chat_project_team", subscriber_type: "chat" },
        { subscriber_id: "chat_developers", subscriber_type: "chat" }
      ]
    }
  }
);

// 4. 清理不需要的订阅
const deleteUrgentSubscription = await feishuTenantClient.deleteActivitySubscriptionsById(
  tasklistGuid,
  urgentSubscription.data.activity_subscription.activity_subscription_guid
);

// 5. 最终检查
const finalSubscriptions = await feishuTenantClient.getActivitySubscriptionsListById(
  tasklistGuid
);

console.log("最终订阅状态:", finalSubscriptions.data.items);