Docs
文档目录

文件令牌 API

为 Storage 文件签发短时访问令牌(resource token):在不携带用户 Session 的场景(跨域 <img>、邮件链接、临时分享)下预览/下载文件。令牌以 token 查询参数附加到文件的 view / preview / download 端点(见 storage)。

服务与资源边界

文件令牌(File Tokens)服务用于在不暴露项目 API Key 且不要求浏览器建立登录 Session 的场景下(例如在企业智能客服会话中内联展示私有存储桶 agent_multimedia_bucket 中的工单截图,或向用户发送带时效的文档下载短链),为单个 Storage 文件({bucketId}:{fileId})签发可独立吊销的 JWT 短时访问凭证。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 scope:tokens.read(列出/读取令牌)、tokens.write(签发/更新/吊销)。令牌一旦签发,持有 secret 即可在有效期内按文件级权限读取该文件;签发与吊销务必要收紧。

端点总览

文件令牌服务提供 5 个 REST 端点,覆盖文件级令牌签发、按文件查询令牌列表、按令牌 ID 查询详情、延长/缩短过期时间及即时吊销。

端点清单

方法 + 路径用途
POST /tokens/buckets/{bucketId}/files/{fileId}为文件签发令牌
GET /tokens/buckets/{bucketId}/files/{fileId}列出该文件的令牌
GET /tokens/{tokenId}获取令牌
PATCH /tokens/{tokenId}更新有效期
DELETE /tokens/{tokenId}吊销令牌

端点详解

签发后的令牌以 ?token=<secret> 查询参数附加至 Storage API 的 /view、/preview 或 /download URL 尾部;服务端校验签名与 expire 有效期通过后直接放行该文件的读取操作,并在令牌的 accessedAt 字段记录最近访问时间(24 小时节流刷新)。

请求与响应

以下按端点逐个给出输入、输出、可复制的调用示例与响应示例。认证头与示例变量约定见 通用约定。

POST /v1/tokens/buckets/{bucketId}/files/{fileId}

为指定文件签发短时访问令牌(限流 60 次/分钟)。secret 拼到文件 URL 的 ?token= 上即可在该有效期内按文件级权限读取文件。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
fileIdpathstring是文件 ID
expirebodystring否过期时间(ISO 8601,如 2020-10-15T06:38:00.000+00:00);缺省为短默认时效

输出:201,返回 resourceToken 模型。完整字段表:

字段类型说明
$idstring令牌 ID
$createdAtstring签发时间(ISO 8601)
resourceIdstring受保护资源,格式 bucketId:fileId
resourceTypestring资源类型,恒为 files
expirestring过期时间(ISO 8601)
secretstring访问凭证(JWT 形态),以 ?token= 附加到文件读取端点
accessedAtstring最近一次用该令牌访问的时间(24 小时内不重复刷新)

调用示例:

curl \
  -X POST \
  "https://<your-endpoint>/v1/tokens/buckets/app-assets/files/66a9d9ab03c7d" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "expire": "2020-10-15T06:38:00.000+00:00"
}'

响应示例:

{
  "$id": "bb8ea5c16897e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "resourceId": "app-assets:66a9d9ab03c7d",
  "resourceType": "files",
  "expire": "2020-10-15T06:38:00.000+00:00",
  "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "accessedAt": "2020-10-15T06:38:00.000+00:00"
}

签发后即可拼 URL:/v1/storage/buckets/app-assets/files/66a9d9ab03c7d/view?token=<secret>(download / preview 同理)。

GET /v1/tokens/buckets/{bucketId}/files/{fileId}

列出该文件名下的全部访问令牌,用于审计与清理。

输入:

参数位置类型必填默认/枚举说明
bucketIdpathstring是桶 ID
fileIdpathstring是文件 ID
queriesquerystring[]否默认 []可过滤字段:expire;分页用 limit(n)/offset(n)
totalqueryboolean否默认 true传 false 跳过计数

输出:200,返回 resourceTokenList 模型:total + tokens[]。resourceToken 字段见 POST /v1/tokens/buckets/{bucketId}/files/{fileId}。

字段类型说明
totalinteger令牌总数
tokens[]resourceToken[]令牌对象

调用示例:

curl \
  'https://<your-endpoint>/v1/tokens/buckets/app-assets/files/66a9d9ab03c7d?queries[]=limit(25)&total=false' \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "total": 1,
  "tokens": [
    {
      "$id": "bb8ea5c16897e",
      "$createdAt": "2020-10-15T06:38:00.000+00:00",
      "resourceId": "app-assets:66a9d9ab03c7d",
      "resourceType": "files",
      "expire": "2020-10-15T06:38:00.000+00:00",
      "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
      "accessedAt": "2020-10-15T06:38:00.000+00:00"
    }
  ]
}

GET /v1/tokens/{tokenId}

按 ID 获取令牌详情(secret 为 JWT 形态)。

输入:

参数位置类型必填默认/枚举说明
tokenIdpathstring是令牌 ID

输出:200,返回 resourceToken 模型,字段见 POST /v1/tokens/buckets/{bucketId}/files/{fileId}。

调用示例:

curl \
  "https://<your-endpoint>/v1/tokens/bb8ea5c16897e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:

{
  "$id": "bb8ea5c16897e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "resourceId": "app-assets:66a9d9ab03c7d",
  "resourceType": "files",
  "expire": "2020-10-15T06:38:00.000+00:00",
  "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "accessedAt": "2020-10-15T06:38:00.000+00:00"
}

PATCH /v1/tokens/{tokenId}

更新令牌过期时间(限流 60 次/分钟)。只影响未来的访问判定,已用旧时效发出的 URL 在新过期时间生效前依然可用(延长的情形)或已失效(缩短的情形)。

输入:

参数位置类型必填默认/枚举说明
tokenIdpathstring是令牌 ID
expirebodystring否新过期时间(ISO 8601)

输出:200,返回 resourceToken(关注 expire 字段)。

调用示例:

curl \
  -X PATCH \
  "https://<your-endpoint>/v1/tokens/bb8ea5c16897e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "expire": "2020-10-15T06:38:00.000+00:00"
}'

响应示例:

{
  "$id": "bb8ea5c16897e",
  "$createdAt": "2020-10-15T06:38:00.000+00:00",
  "resourceId": "app-assets:66a9d9ab03c7d",
  "resourceType": "files",
  "expire": "2020-10-15T06:38:00.000+00:00",
  "secret": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "accessedAt": "2020-10-15T06:38:00.000+00:00"
}

DELETE /v1/tokens/{tokenId}

立即吊销令牌(限流 60 次/分钟):持有该 secret 的请求此后等效未授权。

输入:

参数位置类型必填默认/枚举说明
tokenIdpathstring是令牌 ID

输出:204 No Content,无响应体。

调用示例:

curl \
  -X DELETE \
  "https://<your-endpoint>/v1/tokens/bb8ea5c16897e" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

错误与边界

与 Server SDK 的对应

service.method端点
Tokens.createFileTokenPOST /tokens/buckets/{bucketId}/files/{fileId}
Tokens.listGET /tokens/buckets/{bucketId}/files/{fileId}
Tokens.getGET /tokens/{tokenId}
Tokens.updatePATCH /tokens/{tokenId}
Tokens.deleteDELETE /tokens/{tokenId}