账号资料、会话与偏好
这是什么 / 何时用
已登录用户对自己账号的读写面:资料(姓名、邮箱、手机号)、密码、偏好(preferences)、登录日志、推送目标(push target)、身份关联(identities),以及 2.6.0 新增的账号级最近 30 天用量聚合。适合做「个人中心」「账号设置」「设备/会话管理」页面。
前置
- 任一登录方式建立的可用用户 Session(见 authentication.md)。
- Client SDK(用户 Session)即可完成本页绝大多数操作;个别管理视角(封禁、labels、跨用户)属于 Server SDK 用户管理面,见 users.md。
使用骨架
- 读取当前账号:
account.get();未登录抛 401,前端据此走登录流程。 - 修改资料:
updateName/updateEmail(视场景要求password) /updatePhone/updatePassword(需旧凭据校验)。 - 偏好:
account.getPrefs()读取、account.updatePrefs()合并写入任意 JSON 键值(前端展示偏好、语言等);业务鉴权字段不要放 preferences。 - 会话管理:
account.listSessions列出全部活跃会话(含当前),account.getSession查单条,account.updateSession刷新指定会话,account.deleteSessions全部登出、account.deleteSession('current')登出当前。 - 登录日志:
account.listLogs审计登录与敏感操作。 - 推送目标:
createPushTarget/updatePushTarget/deletePushTarget维护消息推送目的地(配合 Messaging 使用)。 - 身份关联:
account.listIdentities查看已绑定的 OAuth/外部身份,account.deleteIdentity解绑。 - 邮箱/手机验证:
account.createEmailVerification(url)→ 邮件确认回调调account.updateEmailVerification({ userId, secret });Phone 对应createPhoneVerification/updatePhoneVerification。 - 密码找回:
account.createRecovery(url)→account.updateRecovery({ userId, secret, password })。 - 账号用量(2.6.0):
account.getUsageAggregates()返回当前账号最近 30 个 UTC 日的四类标准 Meter 聚合(storage_bytes、bandwidth_bytes、function_executions、users_total),每个 Meter-Day 带quantity/complete/freshnessAt/reason;quantity: null表示缺失,不得当 0 展示。
关键参数与返回
| 调用 | 关键参数 | 返回 | |
|---|---|---|---|
get / updateName | name? | Models.User($id、email、name、labels、prefs 等) | |
updateEmail / updatePhone | phone、password?` | User(匿名转正时 password 即新密码) | |
updatePassword | newPassword、oldPassword? | User | |
updatePrefs | 任意键值对象(合并语义) | User | |
listSessions / getSession / updateSession / deleteSession(s) | sessionId(当前会话用 'current') | Session 列表 / Session | |
listLogs | queries?(分页/过滤) | 日志列表 | |
createPushTarget 等 | targetId、providerId、identifier | PushTarget | |
getUsageAggregates(2.6.0) | 无(固定最近 30 个 UTC 日,range: '30d') | MeterUsageList(四 Meter、coverage、freshness) |
错误与边界
- 401:未登录或 Session 失效;409 / 400:邮箱手机已占用、密码策略不满足、验证
secret无效或过期。 updatePrefs是合并写入;清空某个键要显式置null,不存在「整体替换」语义。deleteSessions会连当前会话一起注销;只登出当前设备用deleteSession('current')。- 解绑最后一个身份前确认仍有可用登录方式,避免锁号。
- 用量聚合的时间窗固定、不可自选区间;旧的项目 / 存储 / TablesDB usage 查询是另一套口径,不要混用。
SDK 类别差异
- Client SDK(Web 为主):本页主体;Session 由 SDK Cookie / header / fallback 三层恢复,见 client-sdk/web.md。
- Server SDK:同名用户管理面是管理员视角(跨用户查询、状态、labels、MFA 重置),不是「自己改自己」,见 users.md。
- Console SDK:Console 账号自身的资料与会话是管理面边界,与应用用户账号无关。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
资料与偏好
本页主体是用户 Session 自助面:Java / Python / Go 经用户态 client 装载 Session 后同构调用同名 Account 方法;REST 回放登录下发的 Session Cookie。
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const me = await account.get(); // 未登录抛 401,按未登录处理跳登录
await account.updateName({ name: '新昵称' });
await account.updatePassword({ newPassword: '<new-password>', oldPassword: '<old-password>' });
await account.updatePrefs({ theme: 'dark', lang: 'zh-CN' }); // 合并写入;清键显式置 null
const prefs = await account.getPrefs();// 用户态 client 装载 Session 后同构调用(位置参数与源码一致)
account.updateName("新昵称");
account.updatePassword("<new-password>", "<old-password>"); // 签名为 (password, oldPassword)
account.updatePrefs(Map.of("theme", "dark", "lang", "zh-CN"));
Object prefs = account.getPrefs();# 用户态 client 装载 Session 后同构调用(snake_case)
account.update_name(name='新昵称')
account.update_password(password='<new-password>', old_password='<old-password>') # 参数名 password / old_password
account.update_prefs({'theme': 'dark', 'lang': 'zh-CN'})
prefs = account.get_prefs()account := agentbase.NewAccount(cl) // 用户态 client:agentbase.NewClient(agentbase.WithSession(secret), ...) 装载 Session
_, _ = account.Get() // 未登录抛 401,按未登录处理跳登录
_, _ = account.UpdateName("新昵称")
_, _ = account.UpdatePassword("<new-password>",
account.WithUpdatePasswordOldPassword("<old-password>"))
_, _ = account.UpdatePrefs(map[string]interface{}{"theme": "dark", "lang": "zh-CN"}) // 合并写入;清键显式置 null
prefs, err := account.GetPrefs()# $APPBASE_ENDPOINT 含 /v1;以下均回放登录下发的 Session Cookie
curl -sS -b cookies.txt "$APPBASE_ENDPOINT/account" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
curl -sS -b cookies.txt -X PATCH "$APPBASE_ENDPOINT/account/name" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"name":"新昵称"}'
curl -sS -b cookies.txt -X PATCH "$APPBASE_ENDPOINT/account/password" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-d '{"password":"<new-password>","oldPassword":"<old-password>"}'
# 邮箱:PATCH /account/email(body: email, password?)会话管理
sessionId 当前会话用 'current';REST 回放 Session Cookie。
- Web(用户 Session)
- Java
- Python
- Go
- REST(curl)
const sessions = await account.listSessions(); // 全部活跃会话(含当前)
await account.updateSession('current'); // 刷新指定会话
await account.deleteSession('current'); // 只登出当前设备
await account.deleteSessions(); // 连当前会话一起注销// 用户态 client 装载 Session;当前会话 sessionId 用 "current"
Object sessions = account.listSessions();
account.updateSession("current");
account.deleteSession("current");
account.deleteSessions();# 用户态 client 装载 Session(snake_case)
sessions = account.list_sessions()
account.update_session(session_id='current')
account.delete_session('current')
account.delete_sessions()sessions, err := account.ListSessions() // 全部活跃会话(含当前)
_, _ = account.UpdateSession("current") // 刷新指定会话
_, _ = account.DeleteSession("current") // 只登出当前设备
_, _ = account.DeleteSessions() // 连当前会话一起注销curl -sS -b cookies.txt "$APPBASE_ENDPOINT/account/sessions" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
curl -sS -b cookies.txt -X PATCH "$APPBASE_ENDPOINT/account/sessions/current" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
curl -sS -b cookies.txt -X DELETE "$APPBASE_ENDPOINT/account/sessions/current" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"
curl -sS -b cookies.txt -X DELETE "$APPBASE_ENDPOINT/account/sessions" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID"登录日志
listLogs 审计登录与敏感操作;REST 端点未列入 API 参考,走 SDK。
- Web(用户 Session)
- Java
- Python
- Go
const logs = await account.listLogs(); // queries 可分页/过滤var logs = account.listLogs(null, null); // 签名 listLogs(queries, total)logs = account.list_logs()logs, err := account.ListLogs() // queries 可分页/过滤推送目标
createPushTarget / updatePushTarget / deletePushTarget 维护消息推送目的地(配合 Messaging 使用);REST 端点未列入 API 参考,走 SDK。
- Web(用户 Session)
- Java
- Python
- Go
await account.createPushTarget({ targetId: ID.unique(), providerId: '<providerId>', identifier: '<device-token>' });
await account.updatePushTarget({ targetId: '<targetId>', identifier: '<device-token>' });
await account.deletePushTarget({ targetId: '<targetId>' });import io.agentbase.ID;
// PushTarget 方法在 console-java 的 io.agentbase.console.services.Account
// (server-java.7.0 的 Account 无 create/update/deletePushTarget,源码核验);
// API 路径 /account/targets/push 为用户态,参数序 targetId、identifier、providerId(providerId 在最后)
account.createPushTarget(ID.unique(), "<device-token>", "<providerId>");
account.updatePushTarget("<targetId>", "<device-token>");
account.deletePushTarget("<targetId>");# server-python@release-2.6.0 的 app_base/services/account.py 无 push target 方法
# (create_push_target / update_push_target / delete_push_target 源码核验缺失);
# 本操作走 Web SDK。// server-go@release-2.6.0 的 account 包无 PushTarget 方法(源码核验);本操作走 Web SDK。身份关联
listIdentities 查看已绑定的 OAuth/外部身份,deleteIdentity 解绑;解绑最后一个身份前确认仍有可用登录方式。REST 端点未列入 API 参考,走 SDK。
- Web(用户 Session)
- Java
- Python
- Go
const identities = await account.listIdentities();
await account.deleteIdentity({ identityId: '<identityId>' });var identities = account.listIdentities(null, null); // 签名 listIdentities(queries, total)
account.deleteIdentity("<identityId>");identities = account.list_identities()
account.delete_identity(identity_id='<identityId>')identities, err := account.ListIdentities()
_, _ = account.DeleteIdentity("<identityId>") // 解绑最后一个身份前确认仍有可用登录方式,避免锁号验证与密码找回
邮箱/手机验证与密码找回都是「发起 → 邮件/短信回调页凭 userId + secret 确认」两步;REST 端点未列入 API 参考,走 SDK。
- Web(用户 Session)
- Java
- Python
- Go
// 邮箱验证;手机对应 createPhoneVerification / updatePhoneVerification
await account.createEmailVerification('https://example.com/verify');
await account.updateEmailVerification({ userId: '<userId>', secret: '<secret>' });
// 密码找回:回调页直接设置新密码
await account.createRecovery('https://example.com/recovery');
await account.updateRecovery({ userId: '<userId>', secret: '<secret>', password: '<new-password>' });// 邮箱验证;手机对应 createPhoneVerification / updatePhoneVerification
account.createEmailVerification("https://example.com/verify");
account.updateEmailVerification("<userId>", "<secret>");
// 密码找回:回调页直接设置新密码
account.createRecovery("user@example.com", "https://example.com/recovery"); // 签名为 (email, url)
account.updateRecovery("<userId>", "<secret>", "<new-password>");# 邮箱验证;手机对应 create_phone_verification / update_phone_verification
account.create_email_verification(url='https://example.com/verify')
account.update_email_verification(user_id='<userId>', secret='<secret>')
# 密码找回:回调页直接设置新密码
account.create_recovery(email='user@example.com', url='https://example.com/recovery') # 签名为 (email, url)
account.update_recovery(user_id='<userId>', secret='<secret>', password='<new-password>')// 邮箱验证;手机对应 CreatePhoneVerification / UpdatePhoneVerification
_, _ = account.CreateEmailVerification("https://example.com/verify")
_, _ = account.UpdateEmailVerification("<userId>", "<secret>")
// 密码找回:Recovery 邮件签发,CreateRecovery 传 Email + Url;回调页直接设置新密码
_, _ = account.CreateRecovery("user@example.com", "https://example.com/recovery")
_, _ = account.UpdateRecovery("<userId>", "<secret>", "<new-password>")账号用量(2.6.0)
getUsageAggregates 返回当前账号最近 30 个 UTC 日的四类标准 Meter 聚合;时间窗固定、不可自选区间。REST 端点未列入 API 参考,走 SDK。
- Web(用户 Session)
- Java
- Python
- Go
const usage = await account.getUsageAggregates(); // quantity: null 表示缺失,不得当 0 展示var usage = account.getUsageAggregates(); // 返回 io.agentbase.models.MeterUsageList# server-python@release-2.6.0 的 app_base/services/account.py 无 get_usage_aggregates
# (/account/usage/aggregates 方法源码核验缺失);本操作走 Web SDK。// server-go@release-2.6.0 的 account/account.go 无 GetUsageAggregates(源码核验);本操作走 Web SDK。示例指引
- 各语言写法集中在语言树
examples/;React Hook 组合(useAuth:account.get+deleteSession('current'))见 authentication.md 的登录方式与skills/ob-agentbase/references/client-sdks/web.md「认证 API」。
事实源
skills/ob-agentbase/references/client-sdks/web.md(「认证 API」小节)skills/ob-agentbase/references/usage-metering.md(账号级 30 天聚合语义)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs