为了: 管理员
使用管理密钥运行导入
创建导入,上传 CSV 文件并将其附加,然后检查每一行并重试失败的行。
在本文中9 个部分
开始之前
此页面介绍了如何使用管理密钥进行导入操作,这些导入方式与在 集成 › 导入 中描述的相同。这里的每个路径都位于 https://prd-api-manage.caseactive.com/v1/integration/<hub id> 之下。关于文件的各个列的具体信息,请参见 各导入操作所需的列 部分。
电话
| 称呼 | 它的作用 |
|---|---|
POST /imports | 创建导入功能 |
GET /drive/private?import_id=<id>&media_group=docs&media_extension=csv | 提供了一个地址,用于将文件上传到该地址。 |
PUT /imports/<import_id> | 将上传的文件附加到列表中,从而开始导入操作。 |
GET /imports | 列出您的已完成任务列表,按最新完成的任务排序,同时显示每项任务的进度。 |
GET /imports/<import_id> | 列出进口商品的各项信息 |
PUT /imports/<import_id>/<unique_id> | 尝试重新执行失败的行操作 |
1. 创建导入
| 场地 | 它的作用 | 必需的 |
|---|---|---|
name | 它的名称是:字母、数字、空格和破折号。 | 是的 |
source | 触发该操作的因素,例如claims-sync,在管理面板中会被标记为其来源。 | 是的 |
type | 以下列出的类型之一 | 是的 |
type | 屏幕 |
|---|---|
post_user | 添加用户 |
put_user | 修改用户信息 |
post_case | 创建案例 |
put_case | 修改案例 |
post_case_permission | 将用户分配至相应案例中 |
delete_case_permission | 移除被分配到特定案例的用户。 |
post_case_post | 创建案例帖子 |
curl -X POST https://prd-api-manage.caseactive.com/v1/integration/ca-7e6d5c4b3a2f10/imports \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "October claimants", "source": "claims-sync", "type": "post_user"}'
这回答了问题。 201 随着 import_id, 比如 import::20261002141503_3f9a1c2b7d4e60.
2. 上传文件
请求一个上传地址。 GET /drive/private?import_id=<import_id>&media_group=docs&media_extension=csv. 这回答了问题。 url 还有一套 fields. 将该文件作为邮件发送过去。 multipart/form-data POST,每个条目都如此 fields 完全按照给定的方式处理,文件也保持原有的顺序。 file:
curl -X POST "<url>" \
--form-string "key=<fields.key>" \
--form-string "<every other entry of fields, as given>" \
-F "file=@october-claimants.csv"
- 发送这些条目吧。
fields随着--form-string, 不-F: 有些是以……开始的<或者持有某物;, 哪个-F可以将其视为一个文件或一种选项。 - 这个地址可以正常使用一个小时。
- 请将该文件保存为CSV格式,使用UTF-8编码。列名请写在文件的第一行。
- 每个文件最多可以包含25,000行数据。如果文件行数超过这个数量,导入操作将无法完成,因为系统无法处理更多的数据。因此,建议将文件拆分为多个,每个文件都只包含25,000行或更少的数据,然后分别进行导入操作。
- 保留
fields.key:这是接下来用于附加文件的方式。
3. 附上文件
PUT /imports/<import_id> 随着上传关键信息的开始,导入过程也就开始了。这就是答案。 204.
{"media_key": "<fields.key>"}
只需一次性上传一个文件。如果导入失败,请修复该文件后重新尝试导入。
4. 检查进度
GET /imports 列出了你的进口商品,按照最新顺序排列,每个商品的 status、total、passed 和 failed 信息也一并列出。
QUEUED:已创建,或已附加,但尚未被读取。PROCESSED:该文件已读取到total行,这些行是依次处理的。当passed和failed的总和达到total时,处理过程即告完成。FAILED:该文件无法被读取,因为文件中没有行数据,或者文件中的行数超过了25,000条;而error_msg则指明了导入结果属于哪种情况:ImportFileUnreadableException、ImportFileEmptyException还是ImportFileTooLargeException。
在您的中心节点中,行数据的导入是每隔一行进行一次的。因此,对于较大的文件来说,处理时间会稍微长一些。当导入过程失败或第一次导入时出现问题,相关的管理员和管理者都会收到电子邮件通知。
GET /imports/<import_id>列出了所有已运行过的行,这些行按照它们在文件中的顺序排列。limit表示运行的次数,最多可达1000次;start_key则代表具体的运行记录。
{
"data": {
"items": [
{
"unique_id": "unique::20261002141503_3f9a1c2b7d4e60_0000002",
"line": 2,
"type": "post_user",
"status": "SUCCEEDED",
"data": {"username": "jane.sample@example.com", "given_name": "Jane", "family_name": "Sample", "host_ref_id": "cl-1042"},
"output": {"host_id": "ca-7e6d5c4b3a2f10", "user_id": "cu-4f1c2a9e8b7d60"}
}
],
"currentItemCount": 1,
"selfLink": "https://prd-api-manage.caseactive.com/v1/integration/ca-7e6d5c4b3a2f10/imports/import::20261002141503_3f9a1c2b7d4e60"
}
}
| 场地 | 它包含什么 |
|---|---|
line | 在您的文件中,这一行的编号。在电子表格中,行数是从1开始计数的,而列名则对应着不同的行号。 |
data | 所传输的行的单元格数据 |
status | 在重试期间可以使用 SUCCEEDED、FAILED 或 QUEUED,然后继续重试。 |
output | 它的作用:对于某个行来说,可以使用user_id、case_id,或者两者结合,就能让某人陷入困境。 |
schema_errors | 对于那个未能通过检查的细胞来说:就是那一列的数据,以及出现的问题。 |
error_msg | 为什么这个行会失败呢?作为一个错误名称,比如 CaseReferenceIdExistsException |
只有当某条记录成功完成相应的操作时,才算算作成功处理。如果某条记录的标签ID、引用ID或人员信息与其他记录冲突,那么该记录就会失败,并且会出现error_msg中的错误信息。此外,如果试图将用户分配给案例或创建关于已关闭案例的帖子时出现问题,也会出现{"_schema": ["Case is closed"]}和schema_errors中的错误信息。此时,请重新尝试操作,或者重新导入该记录。
一场争吵/争执 unique_id 该数据是根据进口方的识别码以及文件中行的编号来生成的,所以指的是文件中的第2行数据。 import::20261002141503_3f9a1c2b7d4e60 是 unique::20261002141503_3f9a1c2b7d4e60_0000002.
5. 重试一行
在轮到某个行执行操作时,如果PUT /imports/<import_id>/<unique_id>与{"retry": true}的尝试都失败了,那么这一行就会像之前一样被重新执行一遍。此时需要响应204,然后导入操作的failed计数就会减少一,直到该行终于能够成功执行为止。可以将此功能用于那些因某些原因而失败的行,比如当前处于繁忙状态的时候。如果某行的单元格数据有误,那么该行同样会再次失败:请修正文件中的错误,然后重新开始导入操作。
接下来会发生什么?
导入的功能与屏幕上的相同功能一致:添加的新人员不会通过电子邮件通知他们;通过邀请加入案件的人会直接收到通知;新的案件会根据你的“分配案件”规则进行处理;而新的帖子则会通知案件的参与人员。这种导入过程会被记录在你的中心界面上。 虚拟助手虚拟助手 一个自动化的团队成员,负责发布欢迎信息、签到信息和公司动态;其发布的帖子带有虚拟助理徽章。重复发送同一个文件会导致每一行都被处理一次:与第一次处理结果冲突的行会再次失败,从而导致信息被重复发布。为了解决屏幕上的失败情况,请参阅相关说明。 修复那些包含错误行的导入操作.
如果电话被拒绝
| 地位 | message | 为什么 |
|---|---|---|
| 400 | SchemaFieldsException | 某个字段缺失或无效,例如包含其他字符的name,或者没有任何内容可供上传的media_key。 |
| 403 | ImportFileAlreadyAttachedException | 当前导入已经包含了所需的文件,或者文件已经被读取:现在可以开始新的导入操作了。 |
| 403 | BotNotAllowedException | 你使用了/v1/<hub id>/imports而不是/v1/integration/<hub id>/imports。 |
| 404 | ItemNotFoundException | 该ID在您的中心中不存在,也没有任何记录。 |