# Appwrite TypeScript SDK ## 安装 # 网页 npm 安装 appwrite # 反应本机 npm 安装react-native-appwrite # Node.js / Deno npm 安装node-appwrite ## 设置客户端 ### 客户端（Web / React Native） // 网页从“appwrite”导入{客户端、帐户、TablesDB、存储、ID、查询}； // 反应本机从“react-native-appwrite”导入{客户端、帐户、TablesDB、存储、ID、查询}；常量客户端 = 新客户端() .setEndpoint('https://.cloud.appwrite.io/v1') .setProject('[PROJECT_ID]'); ### 服务器端（Node.js / Deno）从“node-appwrite”导入{客户端、用户、TablesDB、存储、函数、ID、查询}；常量客户端 = 新客户端() .setEndpoint('https://.cloud.appwrite.io/v1') .setProject(process.env.APPWRITE_PROJECT_ID) .setKey(process.env.APPWRITE_API_KEY); ## 代码示例 ### 身份验证（客户端） const 帐户 = 新帐户（客户端）； // 邮件注册等待帐户.创建({ userId: ID.unique(), 电子邮件：'user@example.com'，密码：'密码123', 名称：'用户名' }); // 邮箱登录 const session = 等待 account.createEmailPasswordSession({ 电子邮件：'user@example.com'，密码：'密码123' }); // OAuth 登录（Web）帐户.createOAuth2Session({ 提供者：OAuthProvider.Github，成功：'https://example.com/success', 失败：'https://example.com/fail'， scopes: ['repo', 'user'] // 可选 — 特定于提供者的范围 }); // 获取当前用户 const user = wait account.get(); // 注销等待 account.deleteSession({ sessionId: 'current' }); ### OAuth 2 登录（React Native） > **重要提示：** `createOAuth2Session()` 在 React Native 上**不起作用**。您必须使用具有深层链接的“createOAuth2Token()”。 #### 设置安装所需的依赖项： npx expo 安装react-native-appwrite React-native-url-polyfill npm install expo-auth-session expo-web-browser expo-linking 在“app.json”中设置 URL 方案： { “博览会”：{ “方案”：“appwrite-callback-[PROJECT_ID]” } } #### OAuth 流程从 'react-native-appwrite' 导入 { Client, Account, OAuthProvider }; 从'expo-auth-session'导入{makeRedirectUri}；从“expo-web-browser”导入 * 作为 WebBrowser；常量客户端 = 新客户端() .setEndpoint('https://.cloud.appwrite.io/v1') .setProject('[PROJECT_ID]'); const 帐户 = 新帐户（客户端）；异步函数 oauthLogin(provider: OAuthProvider) { // 创建适用于 Expo 环境的深层链接 const deepLink = new URL(makeRedirectUri({ PreferredLocalhost: true })); const schema = `${deepLink.protocol}//`; // 例如'exp://' 或 'appwrite-callback-[PROJECT_ID]://' // 获取OAuth登录URL const loginUrl = 等待 account.createOAuth2Token({ 提供者, 成功：`${deepLink}`，失败：`${deepLink}`， }); // 打开浏览器并监听方案重定向 const result =等待WebBrowser.openAuthSessionAsync（`$ {loginUrl}`，scheme）; if (result.type !== '成功') return; // 从重定向 URL 中提取凭据 const url = 新 URL(结果.url); const Secret = url.searchParams.get('秘密'); const userId = url.searchParams.get('userId'); // 使用 OAuth 凭据创建会话等待 account.createSession({ userId, Secret }); } // 用法等待 oauthLogin(OAuthProvider.Github); 等待 oauthLogin(OAuthProvider.Google); ### 用户管理（服务器端） const 用户 = 新用户（客户端）； // 创建用户 const 用户 = 等待用户.create({ userId: ID.unique(), 电子邮件：'user@example.com'，密码：'密码123', 名称：'用户名' }); // 列出用户 const list = wait users.list({ 查询: [Query.limit(25)] }); // 获取用户 const fetched = wait users.get({ userId: '[USER_ID]' }); // 删除用户等待 users.delete({ userId: '[USER_ID]' }); ### 数据库操作 > **注意：** 对所有新代码使用“TablesDB”（而不是已弃用的“Databases”类）。仅当现有代码库已经依赖它或用户明确请求它时才使用“数据库”。 > > **提示：** 对于所有 SDK 方法调用，首选对象参数调用风格（例如，`{databaseId: '...' }`）。仅当现有代码库已使用位置参数或用户明确请求时才使用位置参数。 const tableDB = new TablesDB(客户端); // 创建数据库（仅服务器端） const db =等待tablesDB.create({databaseId: ID.unique(), name: '我的数据库' }); // 创建表（仅限服务器端） const col =等待tablesDB.createTable({ 数据库ID：'[DATABASE_ID]'， tableId: ID.unique(), 名称：“我的桌子” }); // 创建行 const doc = 等待tablesDB.createRow({ 数据库ID：'[DATABASE_ID]'，表 ID: '[TABLE_ID]', rowId: ID.unique(), data: { title: 'Hello World', content: '示例内容' } }); // 列出带有查询的行 const 结果=等待tablesDB.listRows({ 数据库ID：'[DATABASE_ID]'，表 ID: '[TABLE_ID]', 查询：[Query.equal('status', 'active'), Query.limit(10)] }); // 获取行 const row =等待tablesDB.getRow({ 数据库ID：'[DATABASE_ID]'，表 ID: '[TABLE_ID]', 行 ID：'[ROW_ID]' }); // 更新行等待表DB.updateRow({ 数据库ID：'[DATABASE_ID]'，表 ID: '[TABLE_ID]', rowId: '[ROW_ID]', data: { title: '更新的标题' } }); // 删除行等待表DB.deleteRow({ 数据库ID：'[DATABASE_ID]'，表 ID: '[TABLE_ID]', 行 ID：'[ROW_ID]' }); #### 字符串列类型 > **注意：** 旧的“string”类型已弃用。对所有新列使用显式列类型。类型 |最大字符数 |索引 |存储 ---|---|---|--- `varchar` | 16,383 | 16,383完整索引（如果大小 ≤ 768）|行内内联 `文本` | 16,383 | 16,383仅前缀 |离页 `中文本` | 4,194,303 | 4,194,303仅前缀 |离页 `长文本` | 1,073,741,823 | 1,073,741,823仅前缀 |离页 * `varchar` 内联存储并计入 64 KB 行大小限制。更喜欢简短的索引字段，例如名称、别名或标识符。 * `text`、`mediumtext` 和 `longtext` 存储在页外（行中只有 20 字节指针），因此它们不会消耗行大小预算。这些类型不需要“size”。 // 创建具有显式字符串列类型的表等待表DB.createTable({ 数据库ID：'[DATABASE_ID]'， tableId: ID.unique(), name: '文章', 列：[ { key: 'title', type: 'varchar', size: 255, required: true }, // 内联，完全可索引 { key: 'summary', type: 'text', required: false }, // 离页，仅前缀索引 { key: 'body', type: 'mediumtext', required: false }, // 最多 ~4 M 字符 { key: 'raw_data', type: 'longtext', required: false }, // 最多 ~1 B 字符 ] }); #### TypeScript 泛型从“appwrite”导入{模型}； // 服务器端：从 'node-appwrite' 导入 // 为行数据定义类型化接口界面待办事项{ 标题：字符串；完成：布尔值；优先级：数字； } // listRows 默认返回 Models.DocumentList // 对类型化结果进行强制转换或使用泛型 const 结果=等待tablesDB.listRows({ 数据库ID：'[DATABASE_ID]'，表 ID: '[TABLE_ID]', 查询：[Query.equal('done', false)] }); // 每个文档都包含内置字段和数据 const doc = results.documents[0]; 文档.$id; // string — 唯一行 ID doc.$createdAt； // string — ISO 8601 创建时间戳 doc.$updatedAt; // 字符串 — ISO 8601 更新时间戳文档$权限； // string[] — 权限字符串 doc.$databaseId; // 字符串 doc.$collectionId; // 字符串 // 常用模型类型 // Models.User — 用户帐户 // Models.Session — 身份验证会话 // Models.File — 存储文件元数据 // Models.Team — 团队对象 // Models.Execution — 函数执行结果 // Models.DocumentList — 包含总计数的分页列表 ### 查询方法 // 过滤 Query.equal('field', 'value') // field == value（或为 IN 传递数组） Query.notEqual('field', 'value') // 字段 != 值 Query.lessThan('field', 100) // 字段 < 值 Query.lessThanEqual('field', 100) // 字段 <= 值 Query.greaterThan('field', 100) // 字段 > 值 Query.greaterThanEqual('field', 100) // 字段 >= 值 Query. Between('field', 1, 100) // 1 <= 字段 <= 100 Query.isNull('field') // 字段为空 Query.isNotNull('field') // 字段不为空 Query.startsWith('field', 'prefix') // 字符串以前缀开头 Query.endsWith('field', 'suffix') // 字符串以后缀结尾 Query.contains('field', 'substring') // 字符串/数组包含值 Query.search('field', 'keywords') // 全文搜索（需要全文索引） // 排序 Query.orderAsc('field') // 升序排序 Query.orderDesc('field') // 降序排序 // 分页 Query.limit(25) // 返回的最大行数（默认 25，最大 100） Query.offset(0) // 跳过 N 行 Query.cursorAfter('[ROW_ID]') // 在此行 ID 后分页（大型数据集首选） Query.cursorBefore('[ROW_ID]') // 在此行 ID 之前分页 // 选择 Query.select(['field1', 'field2']) // 只返回指定字段 // 逻辑 Query.or([Query.equal('a', 1), Query.equal('b', 2)]) // OR 条件 Query.and([Query.greaterThan('age', 18), Query.lessThan('age', 65)]) // 显式 AND （查询默认为 AND） ### 文件存储 const 存储 = 新存储（客户端）； // 上传文件（客户端 - 来自文件输入） const 文件 = 等待 storage.createFile({ 桶 ID: '[BUCKET_ID]', fileId: ID.unique(), 文件： document.getElementById('file-input').files[0] }); // 上传文件（服务器端——来自路径）从“node-appwrite/file”导入{InputFile}； const file2 = 等待 storage.createFile({ 桶 ID: '[BUCKET_ID]', fileId: ID.unique(), 文件：InputFile.fromPath('/path/to/file.png', 'file.png') }); // 列出文件 const 文件=等待 storage.listFiles({ bucketId: '[BUCKET_ID]' }); // 获取文件预览（图像）常量预览 = storage.getFilePreview({ 桶 ID: '[BUCKET_ID]', 文件 ID: '[FILE_ID]', 宽度：300，高度：300 }); // 下载文件 const download = 等待 storage.getFileDownload({ 桶 ID: '[BUCKET_ID]', 文件 ID：'[FILE_ID]' }); // 删除文件等待 storage.deleteFile({ bucketId: '[BUCKET_ID]', fileId: '[FILE_ID]' }); #### 输入文件工厂方法（服务器端）从“node-appwrite/file”导入{InputFile}； InputFile.fromPath('/path/to/file.png', 'file.png') // 来自文件系统路径 InputFile.fromBuffer(buffer, 'file.png') // 来自缓冲区 InputFile.fromStream(readableStream, 'file.png', size) // 来自 ReadableStream（所需大小以字节为单位） InputFile.fromPlainText('Hello world', 'hello.txt') // 来自字符串内容 ### 团队 const team = new Teams(客户端); // 创建团队 const team =等待teams.create({ teamId: ID.unique(), name: '工程' }); // 列出团队 const list =等待teams.list(); // 创建会员资格（通过电子邮件邀请用户） const 会员资格 = 等待 team.createMembership({ teamId: '[TEAM_ID]', 角色：['编辑']，电子邮件：'user@example.com'， }); // 列出会员资格 const Members =等待teams.listMemberships({ teamId: '[TEAM_ID]' }); // 更新成员角色等待团队.updateMembership({ teamId: '[TEAM_ID]', 会员 ID：'[MEMBERSHIP_ID]'，角色：['管理员']， }); // 删除队伍等待 team.delete({ teamId: '[TEAM_ID]' }); > **基于角色的访问：** 设置权限时，对所有团队成员使用 `Role.team('[TEAM_ID]')` 或对特定团队角色使用 `Role.team('[TEAM_ID]', 'editor')`。 ### 实时订阅（客户端） // 订阅行变化 const unsubscribe = client.subscribe('databases.[DATABASE_ID].tables.[TABLE_ID].rows', (response) => { console.log(响应.事件); // 例如['数据库.*.表.*.行.*.创建'] console.log(响应.payload); // 受影响的资源 }); // 订阅文件更改 client.subscribe('buckets.[BUCKET_ID].files', (response) => { console.log(响应.payload); }); // 订阅多个频道客户端.订阅([ '数据库。[DATABASE_ID].表。[TABLE_ID].行', 'buckets.[BUCKET_ID].files', ], (响应) => { /* ... */ }); // 取消订阅取消订阅（）； **可用渠道：** 频道|描述 ---|--- `帐户` |对经过身份验证的用户帐户的更改 `数据库.[DB_ID].表.[TABLE_ID].行` |表中的所有行 `数据库.[DB_ID].表.[TABLE_ID].行.[ROW_ID]` |特定行 `buckets.[BUCKET_ID].files` |存储桶中的所有文件 `buckets.[BUCKET_ID].files.[FILE_ID]` |特定文件 `团队` |用户所属团队的更改 `团队。[TEAM_ID]` |特定团队的变更 `会员资格` |用户团队成员身份的更改 `会员资格。[MEMBERSHIP_ID]` |特定会员资格 `函数。[FUNCTION_ID].executions` |函数的执行更新 “response”对象包括：“events”（事件字符串数组）、“payload”（受影响的资源）、“channels”（匹配的通道）和“timestamp”（ISO 8601）。 ### 无服务器函数（服务器端） const 函数 = 新函数（客户端）； // 执行函数 const 执行=等待函数.createExecution({ 函数 ID: '[FUNCTION_ID]', body: JSON.stringify({ key: 'value' }) }); // 列出执行情况 const 执行=等待functions.listExecutions({ functionId: '[FUNCTION_ID]' }); #### 编写函数处理程序（Node.js 运行时）部署自己的 Appwrite 函数时，入口点文件必须导出默认的异步函数： // src/main.js （或 src/main.ts）导出默认 async ({ req, res, log, error }) => { // 请求属性 // req.body — 原始请求正文（字符串） // req.bodyJson — 解析的 JSON 正文（对象，如果不是 JSON，则为未定义） // req.headers — 请求标头（对象） // req.method — HTTP 方法（GET、POST、PUT、DELETE、PATCH） // req.path — URL 路径（例如 '/hello'） // req.query — 解析后的查询参数（对象） // req.queryString — 原始查询字符串 log('处理请求：' + req.method + ' ' + req.path); if (req.method === 'GET') { return res.json({ message: '来自 Appwrite 函数的你好！' }); } const 数据 = req.bodyJson; if (!data?.name) { 错误（'缺少名称字段'）； return res.json({ error: '名称为必填项' }, 400); } // 响应方法返回 res.json({ 成功: true }); // JSON（自动设置Content-Type） // 返回 res.text('Hello'); // 纯文本 // 返回 res.empty(); // 204 无内容 // 返回 res.redirect('https://example.com'); // 302 重定向 // 返回 res.send('data', 200, { 'X-Custom': '1' }); // 自定义正文、状态、标题 }; ### 服务器端渲染 (SSR) 身份验证 SSR 应用程序（Next.js、SvelteKit、Nuxt、Remix、Astro）使用 **服务器 SDK**（`node-appwrite`）来处理身份验证。您需要两个客户： * **管理客户端** — 使用 API 密钥、创建会话、绕过速率限制（可重用单例） * **会话客户端** — 使用会话 cookie，代表用户执行操作（根据请求创建，从不共享）从 'node-appwrite' 导入 { Client, Account, OAuthProvider }; // 管理客户端（可重用） const adminClient = 新客户端() .setEndpoint('https://.cloud.appwrite.io/v1') .setProject('[PROJECT_ID]') .setKey(process.env.APPWRITE_API_KEY); // 会话客户端（根据请求创建） const sessionClient = 新客户端() .setEndpoint('https://.cloud.appwrite.io/v1') .setProject('[PROJECT_ID]'); const session = req.cookies['a_session_[PROJECT_ID]']; 如果（会话）{ sessionClient.setSession(会话); } #### 电子邮件/密码登录 app.post('/login', async (req, res) => { const 帐户 = 新帐户(adminClient); const session = 等待 account.createEmailPasswordSession({ 电子邮件：req.body.email，密码：req.body.密码， }); // Cookie 名称必须是 a_session_ res.cookie('a_session_[PROJECT_ID]', session.secret, { httpOnly：正确，安全：真实， sameSite: '严格', 过期：新日期（session.expire），路径：'/'， }); res.json({ 成功: true }); }); #### 经过身份验证的请求 app.get('/user', async (req, res) => { const session = req.cookies['a_session_[PROJECT_ID]']; if (!session) return res.status(401).json({ error: '未经授权' }); // 每个请求创建一个新的会话客户端 const sessionClient = 新客户端() .setEndpoint('https://.cloud.appwrite.io/v1') .setProject('[PROJECT_ID]') .setSession(会话); const 帐户 = 新帐户(sessionClient); const user = wait account.get(); res.json(用户); }); #### OAuth2 SSR 流程 // 第 1 步：重定向到 OAuth 提供者 app.get('/oauth', async (req, res) => { const 帐户 = 新帐户(adminClient); const redirectUrl = 等待 account.createOAuth2Token({ 提供者：OAuthProvider.Github，成功：'https://example.com/oauth/success', 失败：'https://example.com/oauth/failure'， }); res.redirect(redirectUrl); }); // 第 2 步：处理回调 — 交换会话令牌 app.get('/oauth/success', async (req, res) => { const 帐户 = 新帐户(adminClient); const 会话 = 等待 account.createSession({ 用户Id：req.query.userId，秘密：req.query.secret， }); res.cookie('a_session_[PROJECT_ID]', session.secret, { httpOnly: true, secure: true, sameSite: 'strict', 过期：新日期（session.expire），路径：'/'， }); res.json({ 成功: true }); }); > **Cookie 安全性：** 始终使用 `httpOnly`、`secure` 和 `sameSite: 'strict'` 来防止 XSS。 Cookie 名称必须是“a_session_”。 > **转发用户代理：** 调用 `sessionClient.setForwardedUserAgent(req.headers['user-agent'])` 记录最终用户的浏览器信息以进行调试和安全。 ## 错误处理从“appwrite”导入{AppwriteException}； // 服务器端：从 'node-appwrite' 导入尝试{ const doc = 等待tablesDB.getRow({ 数据库ID：'[DATABASE_ID]'，表 ID: '[TABLE_ID]', rowId: '[ROW_ID]', }); } 捕获（错误）{ if (err实例AppwriteException) { console.log(错误.消息); // 人类可读的错误消息 console.log(错误代码); // HTTP 状态码（数字） console.log(err.type); // 应用写入错误类型字符串（例如“document_not_found”） console.log(err.response); // 完整的响应主体（对象） } } **常见错误代码：** 代码|含义 ---|--- `401` |未经授权 - 会话/API 密钥丢失或无效 `403` |禁止 — 没有足够的权限执行此操作 `404` |未找到 — 资源不存在 `409` |冲突 — 重复 ID 或违反唯一约束 `429` |速率受限 — 请求过多，退避后重试 ## 权限和角色（关键） Appwrite 使用权限字符串来控制对资源的访问。每个权限将一个操作（“读取”、“更新”、“删除”、“创建”或“写入”，授予创建 + 更新 + 删除权限）与角色目标配对。默认情况下，**没有用户具有访问权限**，除非在文档/文件级别显式设置权限或从集合/存储桶设置继承权限。权限是使用“Permission”和“Role”帮助器构建的字符串数组。从'appwrite'导入{权限，角色}； // 服务器端：从 'node-appwrite' 导入 ### 具有权限的数据库行 const doc = 等待tablesDB.createRow({ 数据库ID：'[DATABASE_ID]'，表 ID: '[TABLE_ID]', rowId: ID.unique(), 数据：{标题：'你好世界'}，权限：[ Permission.read(Role.user('[USER_ID]')), // 特定用户可以读取 Permission.update(Role.user('[USER_ID]')), // 特定用户可以更新 Permission.read(Role.team('[TEAM_ID]')), // 所有团队成员都可以读取 Permission.read(Role.any()), // 任何人（包括访客）都可以读取 ] }); ### 具有权限的文件上传 const 文件 = 等待 storage.createFile({ 桶 ID: '[BUCKET_ID]', fileId: ID.unique(), 文件： document.getElementById('file-input').files[0], 权限：[ Permission.read(Role.any()), Permission.update(Role.user('[USER_ID]')), Permission.delete(Role.user('[USER_ID]')), ] }); > **何时设置权限：** 当您需要按资源访问控制时设置文档/文件级权限。如果集合中的所有文档共享相同的规则，请在集合/存储桶级别配置权限并将文档权限留空。 > **常见错误：** > > * **忘记权限** — 所有用户（包括创建者）都无法访问该资源 > * **`Role.any()` 与 `write`/`update`/`delete`** — 允许任何用户（包括未经身份验证的访客）修改或删除资源 > * **`Permission.read(Role.any())` 对敏感数据** — 使资源公开可读 >

应用写入打字稿

包含技能