帮助中心集成

为了: 管理员

使用集线器密钥上传和附加文件

获取上传地址,上传文件,将其附加到帖子、笔记、任务、表单或电子签名中,并下载案件文件。

在本文中10 个部分

开始之前

此页面介绍了如何向案例上传文件、附加文件以及使用中心密钥下载文件。文件路径位于https://prd-api-app.caseactive.com/v1/<hub id>/<case id>之下。

工作原理

一个文件需要完成三个步骤:首先获取该项目的上传地址;然后将文件上传到该地址;最后将上传好的文件附加到该项目上。

物品上传地址附消除
一篇帖子GET /posts/<post_id>/drivePUT /posts/<post_id>/mediaDELETE /posts/<post_id>/media
一张便条GET /notes/<note_id>/drivePUT /notes/<note_id>/mediaDELETE /notes/<note_id>/media
一项任务GET /tasks/<task_id>/drivePUT /tasks/<task_id>/mediaDELETE /tasks/<task_id>/media
一项儿童任务GET /subtasks/<subtask_id>/drivePUT /subtasks/<subtask_id>/mediaDELETE /subtasks/<subtask_id>/media
任何形式的文件、电子签名或便条GET /<forms, signs or notes>/<id>/drive 与 media_group=schemasPUT /<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和schemasCSV、DOC、DOCX、ODT、PDF、PPT、PPTX、RTF、TXT、XLS、XLSX
imagesBMP、GIF、JPEG、JPG、PNG、SVG、TIFF、WebP
audiosAAC、AIFF、AMR、FLAC、M4A、MP3、OGA、OPUS、WAV、WMA,以及一些不太常见的音频格式
videos3GP、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_statusRUNNING 在它被处理之后,接着是 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 文件

  1. 使用POST /posts来发布帖子,而帖子则通过message进行发布。帖子会立即被发布,同时还会收到一个门户通知;大约30秒后,邮件就会发送出去,此时已经可以查看附件了,所以请务必在这段时间内附加附件。
  2. GET /posts/<post_id>/drive?media_group=docs&media_extension=pdf&tag_id=repair-estimate。
  3. 将文件上传到 url,使用 fields 作为路径。
  4. PUT /posts/<post_id>/media与fields.key。
  5. 继续阅读GET /posts/<post_id>,直到文件的execution_status达到SUCCEEDED或FAILED。

如果电话被拒绝

地位message为什么
400SchemaFieldsException某个参数缺失或无效,例如接受的扩展名不正确,或者使用了带有空格的tag_id标签;而errors标签所指向的内容则不存在。在media.<n>.media_key处,上传操作未能成功,可能是因为它针对的是另一个项目;而在/schema/media处,上传的内容并非以schemas的形式呈现;此外,如果正在上传的项目实际上并不存在,也会出现这种情况。请求中没有任何内容被上传到服务器上。
403ItemUpdateFailedException文件已经附上,或者相关表格、电子签名或说明都已经包含所需的文档内容。
403ItemAuthorOnlyException那个关键人物试图将某个文件附加到其他人撰写的帖子或评论上。
403CaseClosedException此案已经结案。
404ItemNotFoundException当您尝试获取该物品的上传地址时,该物品并不存在;或者,试图删除的文件也根本不存在。

上传结果以文件存储系统自身的格式进行表示:对于超过限制的文件,返回EntityTooLarge;而当地址过期时,则返回AccessDenied。关于API的错误信息以及其他代码含义,请参考处理API错误和状态代码部分的内容。

相关文章

了解 API 的功能了解管理密钥和中心密钥各自的权限范围,为什么每个密钥都充当虚拟助手,以及完整的技术清单在哪里。集成使用中心密钥添加帖子和评论作为虚拟助手,您可以使用自己的软件向案件动态添加帖子、回复评论、阅读、编辑或删除帖子。集成使用中心密钥发送电子签名和读取签名从模板创建案例的电子签名,选择每个字段的签名人,发布以供签名,并在所有人签名后下载锁定副本。集成处理 API 错误和状态码阅读错误正文,了解 400、401、403、404、500 和 503 的含义,以及为什么您的密钥无法查看的项目会返回 404。集成