选择与数据类型匹配的表示形式
对象上传操作接受放在 `content` 中的文本,或放在 `contentBase64` 中的编码二进制数据。Markdown 说明或 JSON 文档等文本可以直接作为 content 传入。
对于 PDF、图片或其他二进制文件,如果 API 需要字符串载荷,Base64 可以保留字节序列。
Base64 是编码方式,不是加密或压缩。除非操作明确要求,否则不要把普通文本转成 Base64。
如果将 Base64 字符串作为 `content` 传入,对象中可能保存的是编码字符,而非原始二进制文件。
保持类型、路径和数据完整性
请选择能说明文件用途的对象键,并在客户端支持时设置适当的内容类型,例如 `application/pdf` 或 `image/png`。内容类型只告诉软件如何解释对象,不会转换其字节。
对象键和类型应与实际文件一致。
上传后请检查返回的键和大小,并下载或打开对象确认有效。需要逐字节保持一致时,可比较文件大小或校验和。
不要将完整 Base64 载荷写入日志,因为它可能很大并泄露私人文件内容;诊断时记录对象键、类型、大小及脱敏错误即可。