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。

使用骨架

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

  1. 查询候选:Projects.listInactiveByOrganization 分页拉取不活跃项目,人工核对。

  2. 固定清单:由 Owner 明确圈定 1–50 个项目 ID 与审计原因。

  3. dry run 预检:batchReleaseByOrganization({ dryRun: true }),核对逐项目 results 与 summary(accepted / rejected / skipped)。

  4. 二次确认后正式提交:dryRun: false,同一清单、同一原因。

  5. 跟踪删除生命周期:listDeletionsByOrganization 按 deletedAt 倒序查看 pending_purge / purging / purge_failed。

  6. 恢复(可选):重新读取最新状态,确认目标项目仍为 pending_purge,由 Owner 指定单个 projectId 调 restoreDeletionByOrganization;恢复成功清除删除元数据。

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

关键参数与返回

方法与 REST 对照

操作RESTScope
查询不活跃项目GET /v1/teams/{teamId}/projects/inactiveprojects.read
预检 / 批量删除POST /v1/teams/{teamId}/projects/batch-releaseprojects.write
查询删除生命周期GET /v1/teams/{teamId}/projects/deletionsprojects.read
恢复待删除项目DELETE /v1/teams/{teamId}/projects/{projectId}/deletionprojects.write

对应的 SDK 方法见下方各操作说明,均属于 Web/Node SDK 的 Projects 服务。

参数要点

所有方法都必须传入 teamId,值为组织对应的 canonical Team ID;不能直接使用 Console 公开的 organizationId。下表只列各方法的其他参数,并单独说明是否必填。

不活跃项目查询参数

调用方法:Projects.listInactiveByOrganization。

参数是否必填说明
inactiveDays是无活动时间阈值,范围 1–365 天。
graceDays否项目创建后的宽限期,默认 7 天。
limit否每页数量,范围 1–500,默认 100。
cursor否继续翻页时,将上一页的 nextCursor 原样回传。

仅配置以上参数,不传 criteria、signals、preset 等筛选。返回候选项目与分页信息;活跃度判定和 total 的含义见下方“返回与活跃度语义”。

预检与批量删除参数

调用方法:Projects.batchReleaseByOrganization。

参数是否必填说明
projectIds是项目 ID 数组,每次 1–50 个,使用 Owner 已确认的固定清单。
dryRun否传 true 预检,传 false 正式提交。本页流程要求每次显式传值,先预检、确认后再提交。
reason否审计原因,按上文流程填写;预检与正式提交使用同一原因。

返回结果包含请求编号 requestId、逐项目结果 results 和汇总 summary。汇总区分接受、拒绝和跳过,不能仅凭请求成功就认定全部项目已接受。

删除生命周期查询参数

调用方法:Projects.listDeletionsByOrganization。

参数是否必填说明
limit否每页数量,范围 1–100,默认 25。
offset否分页偏移量。

返回处于删除生命周期的项目列表。列表中的项目不一定可恢复,须检查其 deletionStatus。

待删除项目恢复参数

调用方法:Projects.restoreDeletionByOrganization。

参数是否必填说明
projectId是Owner 明确指定的单个项目,当前状态必须为 pending_purge。

成功返回的 status 为 restored,并包含 projectId 和 requestId。

返回与活跃度语义

错误与边界

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 表示状态已变化,重新查询不要重试

示例指引