导入程序支持导入任务的增、删、查操作，启动一个导入任务后，任务在GDB后台执行，您可以查询任务的详细执行情况，包括完成进度、出错信息等，同时您也可以删掉一个任务，无论任务是否正在执行。

增加一个导入任务

将数据从OSS的bucket导入到GDB实例中，使用HTTP POST请求发送到 ${gdb-endpoint}:8182/loader 终端节点。请求的参数需要在POST正文中发送。

注意

1. MIME 类型必须为 application/json
2. OSS的bucket必须与GDB实例位于相同region

请求语法

{ 
  "source" : "${OSS-Path}",
  "format" : "csv",
  "ramRoleArn" : "string",
  "accessKey" : "string",
  "secretKey" : "string",
  "mode": "NEW|RESUME|AUTO",
  "failOnError" : "TRUE/FALSE"
}

其中ramRoleArn对应导入授权的角色代入参数，而accessKey和secretKey是您创建的OSS访问权限的账号AcceccKey，在请求时只需要保留一组授权参数即可。

请求参数

• source，OSS URI。

可指向单个文件或文件夹的OSS URI。如果指定文件夹，GDB将加载文件夹中每个数据文件，但是不包含子文件夹下的文件。

文件夹可以包含多个顶点文件和多个边文件，并且总是先加载顶点文件。自动跳过非顶点文件和边文件。

URI可以采用以下两种格式。

• oss://bucket-name/object-key-name
• http://endpoint-name/bucket-name/object-key-name

但推荐使用前一种格式。使用后面一种时需要确保OSS的endpoint与数据库实例是同一region的VPC网络地址。

• format

目前只支持csv(Gremlin)。

• ramRoleArn

GDB数据库实例要为对OSS的bucket访问权限而代入的RAM角色的资源名称。在完成OSS导入授权后，从RAM访问控制的角色管理， AliyunGDSAccessingOSSRole 详情可以查看 ARN ，对应上节导入授权中的角色代入参数。

• accessKey

OSS访问权限账号的AccessKey中的AccessKeyID参数，对应上节导入授权中直接读取的参数。

• secretKey

与上述accessKey配对的密码AccessKeySecret。

注意

导入授权参数只需要提供一种，推荐使用角色导入而不是直接设置AccessKey，当然GDB实例不会保存上述参数内容，只在执行时做认证使用。

• mode

加载任务模式。

RESUME模式会检查系统是否已经存在当前加载任务(通过source字段判断)，发现存在且意外终止时恢复加载。如果没找到则停止加载。加载程序会避免重新加载已经成功完成的任务，并且只会尝试处理失败的文件。

NEW模式将创建新的加载任务，此模式可用于GDB清除之前的数据后重新加载数据。

AUTO模式先判断是否存在相同的加载任务，并在发现一个时恢复加载，类似RESUME模式。如果不存在相同的加载任务，则创建一个新的加载任务，类似NEW模式。

默认值：AUTO

注意

目前不支持RESUME模式，不能恢复失败的加载任务。

• failOnError

用于指示加载任务在遇到错误时是否完全停止。

如果设置为FALSE，则加载程序尝试加载所有数据并跳过出错的条目。

如果设置为TRUE，则加载程序在遇到错误时中止，错误点之前的数据仍然存在。

默认值：FALSE

注意

当设置为FALSE时，会尝试加载解析完成的每条记录，如果记录id对应的点或边存在，会尝试更新属性。

响应语法

{
    "status" : "200 OK",
    "payload" : {
        "loadId" : "${loaderId}"
    }
}

任务成功启动的加载任务将返回’200 OK’代码。

响应错误参数

当错误出现后，响应的 BODY 中将返回 JSON 对象。message 对象包含对错误的描述。错误信息的详细解释可以参考错误信息列表

错误 400

语法错误将返回 400 错误请求错误。此消息描述错误。

错误 500

无法处理的有效请求返回 500 内部服务器错误。此消息描述错误。

查看导入任务

查询加载任务状态，使用HTTP GET请求发送到 ${gdb-endpoint}:8182/loader 终端节点。查询特定加载请求的状态，必须包含 loaderId 作为 URL 参数，也可将 loaderId 追加到 URL 路径。

请求语法

GET ${gdb-endpoint}:8182/loader
GET ${gdb-endpoint}:8182/loader/${loaderId}
GET ${gdb-endpoint}:8182/loader?loaderId=${loaderId}

${loaderId}为指定的特定任务ID，如果不指定，则返回所有加载任务的ID列表。

响应语法

{
  "payload":{
    "datatypeMismatchErrors": long,
    "errors":[],
    "fullUri": "${OSS-Path}",
    "insertErrors": long,
    "loaderId": "${loaderId}",
    "parsingErrors": long,
    "retryNumber": long,
    "runNumber": long,
    "status": "LOAD_COMPLETED",
    "totalDuplicates": long,
    "totalRecords": long,
    "totalTimeSpent": long
  },
  "status": "200 OK"
}

查询成功将返回’200 OK’，其他错误返回可以查看错误信息列表。

响应参数

• fullUri，string，加载文件的URI。
• runNumber，long，加载任务运行编号，重新启动时增加。
• retryNumber，long，加载任务重试编号，运行期间自动重试时增加。
• status，string，加载任务当前状态，LOAD_COMPLETED指示加载成功。
• totalTimeSpent，long，加载任务耗费的时间(ms)，包括提取文件列表、解析及下载文件和加载到数据库实例的时间。
• totalRecords，long，已经加载的记录总数。
• totalDuplicates，long，遇到重复记录的数量。
• parsingErrors，long，遇到解析错误的数量。
• datatypeMismatchErrors，long，数据类型与指定数据不匹配的记录的数量。
• insertErrors，long，由于错误而无法插入的记录数量。
• loaderId，string，加载任务loaderId。
• errors，List，错误日志列表，最多保留1000条记录，读取后清空

取消导入任务

取消一个加载任务，使用HTTP DELETE请求发送到 ${gdb-endpoint}:8182/loader 终端节点。必须包含 loaderId 作为 URL 参数，也可将 loaderId 追加到 URL 路径。

请求语法

DELETE ${gdb-endpoint}:8182/loader?loadId=${loadId}
DELETE ${gdb-endpoint}:8182/loader/${loadId}

取消任务需要指定任务ID，阻塞等待服务端处理完成才回复响应消息。

取消任务请求完成时服务端会清理该任务的记录信息，针对失败的任务可以查明原因修复后取消任务再重新增加任务。

响应语法

no response body

通过HTTP状态码反馈请求执行结果。’200 OK’表示成功，其他错误返回可以查看错误信息列表。