文件分享

如何创建、查看和撤销分享，口令、过期、次数限制的工作方式，以及一次性下载票据的机制。

分享与公开发布不同

分享使用随机 token，可以设置口令、过期时间和次数限制。目前应用没有专门的分享接收页面，接收者需要用运营者提供的 API 客户端交换 token，不能自己拼出 /s/ 链接。token 不应进入公开索引。没有口令的分享链接本身就是访问凭据；有口令也不意味着文件内容经过了端到端加密。

目前个人中心没有分享创建和管理面板。下面的操作需要文件所有者通过已认证 API 完成，接收同样需要 API 客户端。如果你想让文件出现在匿名可见的目录里，请看公开发布。

POST /api/v1/files/{fileId}/shares，请求体可以是 {}，也可以带以下字段：

字段	规则
`password`	非空字符串，UTF-8 最多 1024 字节；不设置就不需要口令
`expiresAt`	将来的规范 UTC ISO 时间，格式为 `YYYY-MM-DDTHH:mm:ss.sssZ`
`maxDownloads`	1 到 2147483647 的整数；省略表示不设此项上限

成功返回 201。创建响应中的原始 token 只在这次返回，服务端保存的是摘要，分享列表不会帮你找回原始 token。请安全保存创建结果，只发给你预期的接收者，不要记录在公开日志里。

GET /api/v1/files/{fileId}/shares 可以查看该文件的分享记录。用返回记录的 shareId 调用 POST /api/v1/shares/{shareId}/revoke 撤销，成功返回 204。注意 shareId 和接收链接用的 token 是不同的值。

接收者用运营者提供的客户端，按需输入口令并申请下载。客户端调用 POST /api/v1/shares/{token}/download-ticket；有口令时请求体里带 password。票据签发时，share 的 downloadCount 就增加一次。

这意味着 maxDownloads 限制的是成功签发下载票据的次数，不是完整下载到本地的次数。即使之后连接中断了，也可能已经消耗了一次。不要通过预取或自动重试票据请求来探测分享是否可用。

拿到的 downloadGrant 有效 60 秒且只能用一次，用它去请求返回的 objectKey 对应的对象。分享签发票据时会选择当时的当前版本，不能把长期分享当成固定的历史版本链接。

口令错误、过期、次数耗尽、被撤销或文件不可用，通常都会统一返回 404 share unavailable——这是有意不透露具体原因。接收者遇到这种情况应该联系发送者核对，不要据此断定文件已删除。

撤销会阻止后续票据签发，但不保证能撤回已经签发且仍有效的 grant，也没办法删除别人已经保存的副本。如果需要更改限制条件或者原始 token 丢了，可以由所有者重新创建一个合适的分享，再撤销旧记录。