导入接口介绍
您可以发送请求至<gdb-endpoint>:<port>/loader
终端,实现将数据文件从OSS的Bucket中导入至图数据库GDB实例,还可以查看任务状态和删除导入任务。本文介绍添加导入任务(POST)、查看导入任务状态(GET)和删除导入任务(DELETE)的应用示例。
前提条件
已创建与目标数据库GDB实例,创建方法请参见创建实例。
说明如果Bucket是在对象存储控制台创建,请确保图数据库GDB实例和Bucket在同一地域。
已将数据文件上传至Bucket中,上传方法请参见使用OSS控制台上传数据文件或使用ossutil工具上传。
添加导入任务
使用HTTP POST请求发送至<gdb-endpoint>:<port>/loader
终端,将数据从OSS的Bucket导入至图数据库GDB实例中。
MIME类型必须为application/json。
请求语法
{ "source" : "${OSS-Path}", "format" : "csv", "ramRoleArn" : "string", "accessKey" : "string", "secretKey" : "string", "mode": "NEW|RESUME|AUTO", "failOnError" : "TRUE/FALSE", "parallelism" : "HIGH/MEDIUM/LOW" }
请求参数
参数
类型
说明
source
string
OSS的Bucket中存储数据文件的文件夹URI。
可指向单个文件或文件夹的URI。如果指定文件夹,图数据库GDB实例将加载文件夹中的每个数据文件,但不包含子文件夹下的文件。
文件夹中可以包含多个点文件和多个边文件。
加载过程中先加载点文件,且会自动跳过边文件和非点文件。
URI可以采用以下两种格式:
(推荐)oss://<bucket-name>/<object-key-name>
http://<endpoint-name>/<bucket-name>/<object-key-name>
说明<bucket-name>
:请替换为Bucket的名称。<object-key-name>
:请替换为数据文件名称。<endpoint-name>
:请替换为Bucket所在地域对应的服务接入地址。您需要确保图数据库GDB实例与Bucket所属同一地域。
format
string
固定为csv。
ramRoleArn
string
请替换为将数据文件导入Bucket时进行的授权ARN信息,查看方法请参见图数据库GDB控制台一键授权。
说明使用
ramRoleArn
方法进行数据导入时,导入任务受临时安全令牌(STS)有效时间的限制,不能超过10小时,超过会导致任务中断(即数据不能全部导入)。如果您需要导入的数据量较大,建议您采用accessKey
或secretKey
的方法导入。accessKey
string
请替换为您的阿里云账号AccessKey信息的AccessKey ID,查看方法请参见通过访问控制台授权。
说明配置
accessKey
和secretKey
中的任意一个参数即可。secretKey
string
请替换为您的阿里云账号AccessKey信息的AccessKey Secret,查看方法请参见通过访问控制台授权。
说明配置
accessKey
和secretKey
中的任意一个参数即可。mode
string
加载任务模式。取值如下:
NEW:将创建新的加载任务,可用于图数据库GDB清除旧数据后重新加载数据。
RESUME:检查系统是否已经存在当前加载任务(通过
source
判断)。如果当前加载任务存在,则当该加载任务出现终止现象时,系统会自动恢复加载。如果不存在则会停止加载。注意加载程序会避免重新加载已经成功完成的任务,并且只会尝试处理失败的文件。
目前不支持RESUME模式,不能恢复失败的加载任务。
AUTO:判断是否存在相同的加载任务,并在发现一个时恢复加载,与RESUME模式相似。如果不存在相同的加载任务,则创建一个新的加载任务,与NEW模式相似。
默认值:AUTO
failOnError
string
加载任务异常时是否完全停止。取值如下:
TRUE:会完全停止,但错误点之前的数据仍然存在。
FALSE:不会完全停止,加载程序尝试加载所有数据并跳过出错的条目。
注意当设置为FALSE时,会尝试加载解析完成的每条记录,如果记录
id
对应的点或边存在,会尝试更新属性。
默认值:FALSE
parallelism
string
加载任务的并发数。取值如下:
说明您需要升级图数据库GDB实例至v1.0.20或以上版本才能使用该选项。
限制加载任务占用的系统资源,可降低加载数据时对线上请求的影响。
HIGH:加载程序的并发数是实例CPU核数量的2倍。
MEDIUM:加载程序的并发数与实例CPU核数量相等。
LOW:加载程序的并发数是实例CPU核数量的1/2。
默认值:HIGH
响应语法
{ "status" : "200 OK", "payload" : { "loadId" : "<loaderId>" } }
查询成功将返回“200 OK”,其他错误返回可以查看错误信息列表。
说明<loaderId>
:当前导入任务的ID。当错误出现后,响应体中将返回JSON对象。其中,message对象包含对错误的描述。
查看导入任务
使用HTTP GET请求发送到<gdb-endpoint>:<port>/loader
终端,查看导入任务的状态。
查看指定导入任务的状态,必须包含<loaderId>
作为URL参数,也可将<loaderId>
追加到URL路径。
请求语法
#查看导入任务 GET <gdb-endpoint>:<port>/loader #查看指定的导入任务 #方法一: GET <gdb-endpoint>:<port>/loader/<loaderId> #方法二: GET <gdb-endpoint>:<port>/loader?loaderId=<loaderId>
说明<gdb-endpoint>
:请替换为目标数据库GDB实例的连接地址(内网地址或外网地址)。<port>
:请替换为目标数据库GDB实例连接地址对应的端口(内网端口或外网端口)。<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" }
返回参数
参数
类型
说明
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
加载任务的任务ID。
errors
List
错误日志列表。
最多保留1000条记录,读取后清空。
查询成功将返回“200 OK”,其他错误返回可以查看错误信息列表。
取消导入任务
使用HTTP DELETE请求发送到<gdb-endpoint>:<port>/loader
终端,取消导入任务。
取消导入任务,必须包含<loaderId>
作为URL参数,也可将<loaderId>
追加到URL路径。
请求语法
DELETE <gdb-endpoint>:<port>/loader?loaderId=<loaderId> DELETE <gdb-endpoint>:<port>/loader/<loaderId>
说明<gdb-endpoint>
:请替换为图数据库GDB实例的连接地址(内网地址或外网地址)。<port>
:请替换为图数据库GDB实例连接地址对应的端口(内网端口或外网端口)。<loaderId>
:请替换为需要取消的导入任务ID。
取消任务请求完成时,服务端会清理该任务的记录信息。对于取消失败的任务,您可以在查明原因并进行修复后重新进行取消。
响应语法
no response body
通过HTTP状态码反馈请求执行结果。查询成功将返回“200 OK”,其他错误返回可以查看错误信息列表。