agentbase-docs

组织项目治理(不活跃查询 / 批量删除 / 恢复)

这是什么 / 何时用

组织 Owner 的一组项目生命周期治理能力:查询本组织不活跃项目、dry run 预检后批量发起延迟删除、查询处于删除生命周期的项目、恢复仍处于 pending_purge 状态的项目。2.6.0 的 agentbase-web-sdk@2.8.0 与 agentbase-node-sdk@2.8.0 均包含对应方法(Web/Node 的 Projects service);无 SDK 的受控集成可用同形 REST。

前置

项说明
角色当前账号必须是目标组织 Owner;普通组织成员无权限
认证Owner Session(交互首选)、短期 Owner JWT(自动化首选,account.createJWT 签发,默认 15 分钟);Organization API Key 仅当目标环境已交付且具备 projects.read/projects.write
客户端管理面请求指向 Console project(setProject('console') 或环境实际 Console project ID),并 setOrganization(teamId) 声明组织(X-Appwrite-Organization 头)
Scope查询类(不活跃、删除列表)需 projects.read;批量删除与恢复需 projects.write

普通项目 API Key 不能替代组织级凭据;SDK 中存在组织 Key 方法不代表目标实例开放对应创建入口。Key 不可用时不阻塞治理,改用 Session / JWT。

使用骨架

固定流程(删除是高风险操作,不要自动化到「查询结果直接删」):

Console 等价入口:组织「项目清理」页 <console-origin>/console/organization-{organizationId}/project-cleanup;Console 直接提交正式删除(展示全部/部分接受/拒绝与失败摘要),需要逐项目预检结果时用 SDK / REST。

关键参数与返回

方法与 REST 对照

操作SDK 方法(Web/Node Projects)RESTScope
查询不活跃项目listInactiveByOrganizationGET /v1/teams/{teamId}/projects/inactiveprojects.read
预检 / 批量删除batchReleaseByOrganizationPOST /v1/teams/{teamId}/projects/batch-releaseprojects.write
查询删除生命周期listDeletionsByOrganizationGET /v1/teams/{teamId}/projects/deletionsprojects.read
恢复待删除项目restoreDeletionByOrganizationDELETE /v1/teams/{teamId}/projects/{projectId}/deletionprojects.write

参数要点

返回与活跃度语义

错误与边界

SDK 类别差异

各语言调用示例

以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。

查询不活跃项目

listInactiveByOrganization 分页拉取候选,人工核对后固定清单。

const { Account, Client, Projects } = require('agentbase-node-sdk');

const teamId = process.env.APPBASE_ORGANIZATION_TEAM_ID;   // canonical Team ID
const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT)
    .setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID || 'console');  // 管理面指向 Console project

const account = new Account(client);
const session = await account.createEmailPasswordSession({  // 当前账号必须是组织 Owner
    email: process.env.APPBASE_OWNER_EMAIL,
    password: process.env.APPBASE_OWNER_PASSWORD
});
client.setSession(session.secret).setOrganization(teamId);  // 或 setJWT(shortLivedOwnerJwt)
const projects = new Projects(client);

const page = await projects.listInactiveByOrganization({
    teamId,
    inactiveDays: 90,      // 必填,1-365
    graceDays: 7,          // 可选,默认 7
    limit: 50              // 可选,1-500,默认 100
    // cursor: 上一页 nextCursor 原样回传
});
// page: { inactiveDays, projects[], total, scanned, nextCursor? }
// total 是本次有界扫描(每请求最多扫 50 个项目)的匹配数,不是组织级精确总数

dry run 预检与批量删除

batchReleaseByOrganization:Owner 固定 1–50 个项目 ID 与审计原因,先 dryRun: true,二次确认后 dryRun: false。

// client / projects 初始化见上一卡;projectIds 由 Owner 圈定固定清单(1-50 个),不从查询结果直接全选
const fixedProjectIds = ['project-a', 'project-b'];
const reason = '长期无资源活动,业务负责人已确认';

const preview = await projects.batchReleaseByOrganization({
    teamId, projectIds: fixedProjectIds, dryRun: true, reason
});
// preview: { requestId, results[], summary: { accepted, rejected, skipped } }
if (preview.summary.rejected > 0 || preview.summary.skipped > 0) {
    throw new Error('预检未全部通过,重新核对固定清单');
}

const submitted = await projects.batchReleaseByOrganization({
    teamId, projectIds: fixedProjectIds, dryRun: false, reason   // 二次确认后同一清单正式提交
});

删除生命周期与恢复

listDeletionsByOrganization 按 deletedAt 倒序查看 pending_purge / purging / purge_failed;仅 pending_purge 可由 Owner 指定单个项目恢复。

// client / projects 初始化见第一卡
const deletions = await projects.listDeletionsByOrganization({ teamId, limit: 25, offset: 0 });
// deletions.projects[]: { projectId, name, teamId, deletionStatus, deletedAt, purgeAt, ... }

const selectedProjectId = 'project-id-confirmed-by-owner';   // Owner 明确指定,不要自动选列表首个
const selected = deletions.projects.find((p) => p.projectId === selectedProjectId);
if (!selected || selected.deletionStatus !== 'pending_purge') {
    throw new Error('指定项目不在当前页,或已不可恢复');
}

const restored = await projects.restoreDeletionByOrganization({ teamId, projectId: selectedProjectId });
// 成功返回 { status: 'restored', projectId, requestId };409 表示状态已变化,重新查询不要重试

示例指引

事实源