全部产品

OSS数据导入接口

更新时间:2020-09-17 16:02:57

导入程序支持导入任务的增、删、查操作,启动一个导入任务后,任务在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", 
   "parallelism" : "HIGH/MEDIUM/LOW"}

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

请求参数

  • source,OSS URI。

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

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

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

但推荐使用前一种格式。使用后面一种时需要确保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对应的点或边存在,会尝试更新属性。

  • parallelism

用于指示加载任务的并发数,限制加载任务占用的系统资源,可降低加载数据时对线上请求的影响。

如果设置为HIGH,加载程序的并发数是实例CPU核数量的2倍。

如果设置为MEDIUM,加载程序的并发数与实例CPU核数量相等。

如果设置为LOW,加载程序的并发数是实例CPU核数量的1/2。

默认值:HIGH

注意

您需要升级GDB实例到v1.0.20或以上版本才能使用该选项。

响应语法

{    
   "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=${loade

${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’表示成功,其他错误返回可以查看错误信息列表