为了: 管理员
使用集线器密钥上传和附加文件
获取上传地址,上传文件,将其附加到帖子、笔记、任务、表单或电子签名中,并下载案件文件。
在本文中10 个部分
开始之前
此页面介绍了如何向案例上传文件、附加文件以及使用中心密钥下载文件。文件路径位于https://prd-api-app.caseactive.com/v1/<hub id>/<case id>之下。
工作原理
一个文件需要完成三个步骤:首先获取该项目的上传地址;然后将文件上传到该地址;最后将上传好的文件附加到该项目上。
| 物品 | 上传地址 | 附 | 消除 |
|---|---|---|---|
| 一篇帖子 | GET /posts/<post_id>/drive | PUT /posts/<post_id>/media | DELETE /posts/<post_id>/media |
| 一张便条 | GET /notes/<note_id>/drive | PUT /notes/<note_id>/media | DELETE /notes/<note_id>/media |
| 一项任务 | GET /tasks/<task_id>/drive | PUT /tasks/<task_id>/media | DELETE /tasks/<task_id>/media |
| 一项儿童任务 | GET /subtasks/<subtask_id>/drive | PUT /subtasks/<subtask_id>/media | DELETE /subtasks/<subtask_id>/media |
| 任何形式的文件、电子签名或便条 | GET /<forms, signs or notes>/<id>/drive 与 media_group=schemas | PUT /<forms, signs or notes>/<id>/schema/media | — |
- 该功能允许钥匙仅将文件附加到由虚拟助手创建的帖子中。它可以将文件附加到任何笔记、任务或子任务上。
- 要将文件附加到评论上,请使用
/drive来获取文件的地址,然后使用PUT /<posts, signs, tasks or subtasks>/<id>/comments/<comment_id>/media来进行附件操作。一个密钥只能附加到自己创建的评论上。 - 一种表单或电子签名方式仅能存储一份文件,不能包含其他文件。一旦成功存储了所需的文件,除非第一份文件无法转换,否则就不会再尝试存储其他文件了。
1. 获取上传地址
| 范围 | 它的作用 | 必需的 | 默认 |
|---|---|---|---|
media_group | 文件类型应为:docs、images、audios、videos或files,对于表单、电子签名或备注类文档则应为schemas。 | 是的 | — |
media_extension | 文件的扩展名,例如pdf。这个扩展名必须是该文件所支持的格式之一;files则支持任何类型的扩展名。 | 是的 | — |
tag_id | 文件的保存名称,应使用字母、数字和连字符组合而成,例如 repair-estimate | 是的 | — |
| 种类 | 扩展 |
|---|---|
docs和schemas | CSV、DOC、DOCX、ODT、PDF、PPT、PPTX、RTF、TXT、XLS、XLSX |
images | BMP、GIF、JPEG、JPG、PNG、SVG、TIFF、WebP |
audios | AAC、AIFF、AMR、FLAC、M4A、MP3、OGA、OPUS、WAV、WMA,以及一些不太常见的音频格式 |
videos | 3GP、AVI、FLV、M4V、MP4、MOV、MPG、OGG、WEBM、WMV等常见视频格式,以及一些不太常见的视频格式。 |
files | 任何 |
curl "https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate" \
-H "Authorization: Bearer YOUR_API_KEY"
它包含了要上传的地址 url,以及随文件一起发送的表单字段 fields。文件将被保存在 fields.key 这个位置。该地址的有效期为一小时。
2. 上传文件
发送一个 multipart/form-data 发送帖子/消息 url, 在每一个条目中 fields 根据所给信息,那么该文件的顺序应该是最后一位。 file. fields 手中握着空杯子/空容器 Content-Type: 填写文件的类型信息,例如: application/pdf, 与其发送第二个请求,不如直接将其发送到文件存储中,而不是通过API进行传输。因此,这个调用不需要任何密钥即可完成。
curl -X POST "<url>" \
--form-string "key=<fields.key>" \
--form-string "Content-Type=application/pdf" \
--form-string "<every other entry of fields, as given>" \
-F "file=@repair-estimate.pdf"
发送这些条目吧。 fields 随着 --form-string, 不 -F: 有些是以……开始的 <, 哪个 -F 被当作一个文件来读取。
这回答了201的问题。最大的文件大小是虚拟助手角色对该类型的文件的限制值,默认为5,000 MB;管理员可以在设置›角色设置中将其降低。超过这个限制的文件将被文件存储系统拒绝处理。而从未被上传过的文件则会在三天后被删除。
3. 把它装上去
curl -X PUT https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"media": [{"media_key": "<fields.key>"}]}'
{
"data": {
"items": [{"media_key": "hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf", "media_id": "20261002154512_5f4e3d2c1b0a99"}],
"currentItemCount": 1
}
}
media可以一次性处理多个文件。这些文件的地址都必须与这个项目中的某个地址一致。- “附加”功能用于添加文件;它并不会取代原有的文件。
- 在一条帖子上,每个文件的
add_post_media都会被附加在一起,而关于该帖子的电子邮件则会统计其中的文件数量。
连接后
在附加这些文件之后,它们将被进行处理:图片会被调整大小,音频和视频会被处理以方便播放,而文档则会被转换为PDF格式,并包含页面图像。这类文件的处理方式就是这样。 files 它们保持原样被保存着。
每个项目的读取次数,例如GET /posts/<post_id>,其文件列表显示在media.<kind>.items.<media_id>下:
| 场地 | 它包含什么 |
|---|---|
execution_status | RUNNING 在它被处理之后,接着是 SUCCEEDED 或 FAILED |
original | 上传的文件已准备好。 |
pdf | 已转换为PDF格式的文档,现在可以使用了。 |
flat | 一旦所有人都签署了电子文件,那么这份文件就已经成为受保护的副本了。 |
tag_id, content_type, media_size | 它的名称、类型以及字节大小 |
当某个文件仍在处理中时,界面上会显示该文件的encoding信息。在文档准备就绪之前,无法发布任何形式的电子文档或签名内容。
下载文件
从https://privcdn.caseactive.com/下载文件,文件名使用original、pdf或flat格式表示。请将您的密钥与每次调用时相同的头部信息一起发送过去。
curl "https://privcdn.caseactive.com/hosts/ca-7e6d5c4b3a2f10/cases/cc-1a2b3c4d5e6f70/posts/post::20261002154134_b0accfaac139a9/media/docs/20261002154512_5f4e3d2c1b0a99/20261002154512_5f4e3d2c1b0a99.pdf" \
-H "Authorization: Bearer YOUR_API_KEY" -o repair-estimate.pdf
该密钥的验证规则与所有调用情况相同,其IP范围也适用于此类验证。此外,该密钥可以从虚拟助手功能所能访问的任何位置进行数据下载。
删除文件
DELETE /<item>/media接受一个JSON体,该体中包含文件的media_id和media_group信息,然后返回200。在POST请求中,你的Web钩子会接收delete_post_media信息。而表单、电子签名或注释中的文档是无法被删除的——必须直接删除相关项目才行。
例如:新帖子的 PDF 文件
- 使用
POST /posts来发布帖子,而帖子则通过message进行发布。帖子会立即被发布,同时还会收到一个门户通知;大约30秒后,邮件就会发送出去,此时已经可以查看附件了,所以请务必在这段时间内附加附件。 GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate。- 将文件上传到
url,使用fields作为路径。 PUT /posts/<post_id>/media与fields.key。- 继续阅读
GET /posts/<post_id>,直到文件的execution_status达到SUCCEEDED或FAILED。
如果电话被拒绝
| 地位 | message | 为什么 |
|---|---|---|
| 400 | SchemaFieldsException | 某个参数缺失或无效,例如接受的扩展名不正确,或者使用了带有空格的tag_id标签;而errors标签所指向的内容则不存在。在media.<n>.media_key处,上传操作未能成功,可能是因为它针对的是另一个项目;而在/schema/media处,上传的内容并非以schemas的形式呈现;此外,如果正在上传的项目实际上并不存在,也会出现这种情况。请求中没有任何内容被上传到服务器上。 |
| 403 | ItemUpdateFailedException | 文件已经附上,或者相关表格、电子签名或说明都已经包含所需的文档内容。 |
| 403 | ItemAuthorOnlyException | 那个关键人物试图将某个文件附加到其他人撰写的帖子或评论上。 |
| 403 | CaseClosedException | 此案已经结案。 |
| 404 | ItemNotFoundException | 当您尝试获取该物品的上传地址时,该物品并不存在;或者,试图删除的文件也根本不存在。 |
上传结果以文件存储系统自身的格式进行表示:对于超过限制的文件,返回EntityTooLarge;而当地址过期时,则返回AccessDenied。关于API的错误信息以及其他代码含义,请参考处理API错误和状态代码部分的内容。