OSS数据导入接口
导入程序支持导入任务的增、删、查操作,启动一个导入任务后,任务在GDB后台执行,您可以查询任务的详细执行情况,包括完成进度、出错信息等,同时您也可以删掉一个任务,无论任务是否正在执行。
增加一个导入任务
将数据从OSS的bucket导入到GDB实例中,使用HTTP POST请求发送到 ${gdb-endpoint}:8182/loader
终端节点。请求的参数需要在POST正文中发送。
注意
- MIME 类型必须为 application/json
- 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’表示成功,其他错误返回可以查看错误信息列表。
版权声明
本文仅代表作者观点,不代表本站立场。
本文系作者授权发表,未经许可,不得转载。
评论