Neptune 加载程序命令 - Amazon Neptune

Neptune 加载程序命令

将数据从 Amazon S3 存储桶加载到 Neptune 数据库实例中。

要加载数据,必须将 HTTP POST 请求发送到 https://your-neptune-endpoint:port/loader 终端节点。loader 请求的参数可在 POST 正文中或作为 URL 编码的参数发送。

重要

MIME 类型必须为 application/json

S3 存储桶必须与集群位于同一 AWS 区域。

注意

在使用 Amazon S3 SSE-S3 模式加密的情况下,您可从 Amazon S3 加载加密数据。在这种情况下,Neptune 能够模拟您的凭证并代表您发出 s3:getObject 调用。

只要您的 IAM 角色包括访问 AWS KMS 的必要权限,您还可以从 Amazon S3 加载使用 SSE-KMS 模式加密的加密数据。如果没有适当的 AWS KMS 权限,批量加载操作将失败并返回 LOAD_FAILED 响应。

Neptune 当前不支持加载使用 SSE-C 模式加密的 Amazon S3 数据。

您不必等待一个加载作业完成就可以开始另一个加载作业。Neptune 可以一次对多达 64 个作业请求进行排队,前提是它们的 queueRequest 参数都设置为 "TRUE"。另一方面,如果您不希望对某个加载作业排队,则可以将其 queueRequest 参数设置为 "FALSE"(默认值),这样,如果另一个加载作业已在进行中,该加载作业将失败。

您可以使用 dependencies 参数对只有在队列中指定的先前作业成功完成后才能运行的作业进行排队。如果执行此操作,并且这些指定的任何作业失败,则您的作业将不会运行,其状态将设置为 LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED

Neptune 加载程序请求语法

{ "source" : "string", "format" : "string", "iamRoleArn" : "string", "mode": "NEW|RESUME|AUTO" "region" : "us-east-1", "failOnError" : "string", "parallelism" : "string", "parserConfiguration" : { "baseUri" : "http://base-uri-string", "namedGraphUri" : "http://named-graph-string" }, "updateSingleCardinalityProperties" : "string", "queueRequest" : "TRUE", "dependencies" : ["load_A_id", "load_B_id"] }

Neptune 加载程序请求参数

  • source   – 一个 Amazon S3 URI。

    SOURCE p参数接受指向单个文件或文件夹的 Amazon S3 URI。如果指定文件夹,Neptune 将加载所指定文件夹中的每个数据文件。

    文件夹可包含多个顶点文件和多个边缘文件。

    URI 可以采用以下任意格式。

    • s3://bucket_name/object-key-name

    • https://s3.amazonaws.com/bucket_name/object-key-name

    • https://s3-us-east-1.amazonaws.com/bucket_name/object-key-name

  • format – 数据的格式。有关 Neptune Loader 命令的数据格式的更多信息,请参阅使用 Amazon Neptune 批量加载器收集数据

    允许的值csv (Gremlin)、ntriplesnquadsrdfxmlturtle (RDF)。

  • iamRoleArn – Neptune 数据库实例 为访问 S3 存储桶而代入的 IAM 角色的 Amazon 资源名称 (ARN)。有关创建对 Amazon S3 具有访问权限的角色,然后将其 Neptune 集群关联的信息,请参阅先决条件:IAM 角色和 Amazon S3 访问权限

  • regionregion 参数必须与集群和 S3 存储桶的 AWS 区域匹配。

    以下区域提供 Amazon Neptune:

    • 美国东部(弗吉尼亚北部):   us-east-1

    • 美国东部(俄亥俄州):   us-east-2

    • 美国西部(俄勒冈):   us-west-2

    • 加拿大 (中部):   ca-central-1

    • 欧洲(斯德哥尔摩):   eu-north-1

    • 欧洲(爱尔兰):   eu-west-1

    • 欧洲(伦敦):   eu-west-2

    • 欧洲(巴黎):   eu-west-3

    • 欧洲(法兰克福):   eu-central-1

    • 中东(巴林):   me-south-1

    • 亚太区域(东京):   ap-northeast-1

    • 亚太区域(首尔):   ap-northeast-2

    • 亚太区域(新加坡):   ap-southeast-1

    • 亚太区域(悉尼):   ap-southeast-2

    • 亚太地区(孟买):   ap-south-1

    • 中国 (宁夏):   cn-northwest-1

    • AWS GovCloud (US-West):   us-gov-west-1

    • AWS GovCloud(美国东部):   us-gov-east-1

  • mode – 加载作业模式。

    允许的值RESUMENEWAUTO

    默认值AUTO

    • RESUME – 在 RESUME 模式下,加载程序查找来自此源的先前加载,如果找到一个加载,则恢复该加载作业。如果未找到之前的加载作业,则加载程序将停止。

      加载程序将避免重新加载之前作业中已成功加载的文件。它仅尝试处理失败的文件。如果您从 Neptune 集群中删除了之前加载的数据,则此模式下不加载该数据。如果之前的加载作业成功加载了来自同一源的所有文件,则不会重新加载任何文件,并且加载程序返回成功。

    • NEW – 在 NEW 模式下,将创建新的加载请求而不管任何之前的加载。您可以使用此模式在从 Neptune 集群删除之前加载的数据之后从源重新加载数据,或加载同一个源处可用的新数据。

    • AUTO – 在 AUTO 模式下,加载程序查找来自此同一个源的先前加载作业,如果找到一个加载作业,则恢复该作业,如同在 RESUME 模式中一样。

      如果加载程序没有找到来自同一源的先前加载作业,则会从源加载所有数据,就像在 NEW 模式中一样。

  • failOnError – 用于在出错时切换为完全停止的标记。

    允许的值"TRUE""FALSE"

    默认值"TRUE"

    如果此参数设置为 "FALSE",则加载程序尝试加载指定位置中的所有数据并跳过任何出错的条目。

    将此参数设置为 "TRUE" 时,加载程序会在遇到错误时立即停止。截至该点加载的数据仍然存在。

  • parallelism – 这是一个可选参数,可以设置用于减少批量加载过程使用的线程数。

    允许的值

    • LOW – 所使用的线程数是内核数除以 8。

    • MEDIUM – 所使用的线程数是内核数除以 2。

    • HIGH – 所使用的线程数等于内核数。

    • OVERSUBSCRIBE – 所使用的线程数是内核数乘以 2。如果使用此值,则批量加载程序将占用所有可用资源。

    默认值HIGH

  • parserConfiguration – 具有额外解析程序配置值的可选对象。每个子参数也是可选的:

    名称 示例值 描述
    namedGraphUri http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph 未指定任何图形时所有 RDF 格式的默认图形(适用于非 quads 格式和无图形的 NQUAD 条目)。默认值为 http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph
    baseUri http://aws.amazon.com/neptune/default RDF/XML 和 Turtle 格式的基本 URI。默认为 http://aws.amazon.com/neptune/default

    有关更多信息,请参阅 SPARQL 默认图形和命名图形

  • updateSingleCardinalityProperties – 这是一个可选参数,用于控制批量加载程序如何处理单基数顶点或边缘属性的新值。

    允许的值"TRUE""FALSE"

    默认值"FALSE"

    默认情况下,或者当 updateSingleCardinalityProperties 被显式设置为 "FALSE" 时,加载程序将新值视为错误,因为它违反了单个基数。

    另一方面,当 updateSingleCardinalityProperties 设置为 "TRUE" 时,批量加载程序会用新值替换现有值。如果在要加载的源文件中提供了多个边缘或单基数顶点属性值,则批量加载结束时的最终值可以是这些新值中的任何一个值。加载程序仅保证现有值已被其中一个新值替换。

  • queueRequest – 这是一个可选的标志参数,用于指示是否可以对加载请求进行排队。

    您不必等到一个加载作业完成就可以发出下一个作业,因为 Neptune 可以一次对多达 64 个作业进行排队,前提是它们的 queueRequest 参数都设置为 "TRUE"

    如果省略 queueRequest 参数或将其设置为 "FALSE",则如果另一个加载作业已在运行,该加载请求将失败。

    允许的值"TRUE""FALSE"

    默认值"FALSE"

  • dependencies – 这是一个可选参数,可以使排队的加载请求取决于队列中的一个或多个先前作业的成功完成。

    Neptune 可以一次对多达 64 个加载请求进行排队,前提是它们的 queueRequest 参数设置为 "TRUE"dependencies 参数允许您使此类排队请求的执行取决于成功完成队列中的一个或多个指定的先前请求。

    例如,如果加载 Job-AJob-B 彼此独立,但加载 Job-C 在开始之前要求先完成 Job-AJob-B,请按以下方式进行操作:

    1. 不分顺序接连提交 load-job-Aload-job-B,并保存它们的加载 ID。

    2. 提交 load-job-C,并在其 dependencies 字段中填入前两个作业的加载 ID:

    "dependencies" : ["job_A_load_id", "job_B_load_id"]

    由于 dependencies 参数,批量加载程序在 Job-AJob-B 成功完成前将不会启动 Job-C。如果其中任何一个作业失败,则不会执行作业 C,并将其状态设置为 LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED

    您可以通过这种方式设置多个依赖关系级别,这样,一个作业的失败将导致所有直接或间接依赖于该作业的请求被取消。

  • accessKey[弃用] 对 S3 存储桶和数据文件具有访问权限的 IAM 角色的访问密钥 ID。

    建议改用 iamRoleArn 参数。有关创建对 Amazon S3 具有访问权限的角色,然后将其 Neptune 集群关联的信息,请参阅先决条件:IAM 角色和 Amazon S3 访问权限

    有关更多信息,请参阅访问密钥(访问密钥 ID 和秘密访问密钥)

  • secretKey[已弃用] 建议改用 iamRoleArn 参数。有关创建对 Amazon S3 具有访问权限的角色,然后将其 Neptune 集群关联的信息,请参阅先决条件:IAM 角色和 Amazon S3 访问权限

    有关更多信息,请参阅访问密钥(访问密钥 ID 和秘密访问密钥)

Neptune 加载程序响应语法

{ "status" : "200 OK", "payload" : { "loadId" : "guid_as_string" } }

200 OK (200 确定)

成功启动的加载任务将返回 200 代码。

Neptune 加载程序错误

当错误出现后,响应的 BODY 中将返回 JSON 对象。message 对象包含对错误的描述。

错误类别

  • Error 400 – 语法错误将返回 HTTP 400 错误请求错误。此消息描述错误。

  • Error 500 – 无法处理的有效请求返回 HTTP 500 内部服务器错误。此消息描述错误。

以下是来自加载程序的可能的错误消息,其中包含对错误的描述。

加载程序错误消息

  • Couldn't find the AWS credential for iam_role_arn  (HTTP 400)

    未找到凭证。针对 IAM 控制台或 AWS CLI 输出验证提供的凭证。

  • S3 bucket not found for source  (HTTP 400)

    S3 存储桶不存在。请检查存储桶的名称。

  • The source source-uri does not exist/not reachable  (HTTP 400)

    在 S3 存储桶中未找到匹配的文件。

  • Unable to connect to S3 endpoint. Provided source = source-uri and region = aws-region  (HTTP 400)

    无法连接到 Amazon S3。区域必须与集群区域匹配。确保具有 VPC 端点。有关创建 VPC 端点的信息,请参阅 创建 Amazon S3 VPC 终端节点

  • Bucket is not in provided Region (aws-region)  (HTTP 400)

    存储桶必须与 Neptune 数据库实例位于同一 AWS 区域。

  • Unable to perform S3 list operation  (HTTP 400)

    提供的 IAM 用户或角色对存储桶或文件夹无 List 权限。检查存储桶上的此策略或访问控制列表 (ACL)。

  • Start new load operation not permitted on a read replica instance  (HTTP 405)

    加载是写入操作。在读取/写入集群终端节点上重试加载。

  • Failed to start load because of unknown error from S3  (HTTP 500)

    Amazon S3 返回未知错误。联系 AWS Support

  • Invalid S3 access key  (HTTP 400)

    访问密钥无效。请检查提供的凭证。

  • Invalid S3 secret key  (HTTP 400)

    秘密密钥无效。请检查提供的凭证。

  • Max concurrent load limit breached  (HTTP 400)

    如果提交的加载请求没有附带 "queueRequest" : "TRUE",并且当前正在运行加载作业,则请求将失败并显示此错误。

  • Failed to start new load for the source "source name". Max load task queue size limit breached. Limit is 64  (HTTP 400)

    Neptune 支持一次对多达 64 个加载作业进行排队。如果额外的加载请求提交到已经包含 64 个作业的队列,请求将失败并显示此消息。

Neptune 加载程序示例

例 请求

下面是使用 curl 命令经由 HTTP POST 发送的请求。它加载 Neptune CSV 格式的文件。有关更多信息,请参阅 Gremlin 加载数据格式

curl -X POST \ -H 'Content-Type: application/json' \ https://your-neptune-endpoint:port/loader -d ' { "source" : "s3://bucket-name/object-key-name", "format" : "csv", "iamRoleArn" : "ARN for the IAM role you are using", "region" : "region", "failOnError" : ""FALSE"", "parallelism" : "MEDIUM", "updateSingleCardinalityProperties" : ""FALSE"", "queueRequest" : ""FALSE"" }'

例 响应

{ "status" : "200 OK", "payload" : { "loadId" : "ef478d76-d9da-4d94-8ff1-08d9d4863aa5" } }