导入接口介绍

更新时间: 2021-12-24 18:41:45

您可以发送请求至<gdb-endpoint>:<port>/loader终端,实现将数据文件从OSS的Bucket中导入至图数据库GDB实例,还可以查看任务状态和删除导入任务。本文介绍添加导入任务(POST)、查看导入任务状态(GET)和删除导入任务(DELETE)的应用示例。

前提条件

添加导入任务

使用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小时,超过会导致任务中断(即数据不能全部导入)。如果您需要导入的数据量较大,建议您采用accessKeysecretKey的方法导入。

    accessKey

    string

    请替换为您的阿里云账号AccessKey信息的AccessKey ID,查看方法请参见通过访问控制台授权

    说明

    配置accessKeysecretKey中的任意一个参数即可。

    secretKey

    string

    请替换为您的阿里云账号AccessKey信息的AccessKey Secret,查看方法请参见通过访问控制台授权

    说明

    配置accessKeysecretKey中的任意一个参数即可。

    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”,其他错误返回可以查看错误信息列表

上一篇: 将OSS数据导入至图数据库GDB 下一篇: 使用curl命令导入数据文件
阿里云首页 图数据库 相关技术圈