导入接口介绍

前提条件

• 已创建与目标数据库GDB实例，创建方法请参见创建实例。

  说明

  如果Bucket是在对象存储控制台创建，请确保图数据库GDB实例和Bucket在同一地域。

• 已将数据文件上传至Bucket中，上传方法请参见使用OSS控制台上传数据文件或使用ossutil工具上传。

添加导入任务

使用HTTP POST请求发送至<gdb-endpoint>:<port>/loader终端，将数据从OSS的Bucket导入至图数据库GDB实例中。

• 请求语法

  {   
     "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终端，查看导入任务的状态。

• 请求语法

  #查看导入任务
  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终端，取消导入任务。

• 请求语法

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