Neptune 加载程序命令 - Amazon Neptune
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

Neptune 加载程序命令

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

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

重要

MIME 类型必须为 application/json

S3 存储桶必须位于同一位置Amazon区域作为集群。

注意

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

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

Neptune 当前不支持加载使用SSE-C模式。

您不必等待一个加载作业完成就可以开始另一个加载作业。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参数接受标识单个文件、多个文件、一个文件夹或多个文件夹的 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

    这些区域有:object-key-nameURI 的元素等效于前缀Amazon S3 中的参数ListObjectsAPI 调用。它标识指定 Amazon S3 存储桶中名称以该前缀开头的所有对象。这可以是单个文件或文件夹,也可以是多个文件和/或文件夹。

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

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

    允许的值csv对于 Gremlin 数据,opencypher对于 OpenPher CSV 数据,或者ntriplesnquadsrdfxml,或者turtle对于 RDF 数据。

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

  • region— 该region参数必须与Amazon集群和 S3 存储桶的区域。

    以下区域提供了 Amazon Neptune:

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

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

    • 美国西部(加利福尼亚北部):us-west-1

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

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

    • 南美洲(圣保罗):sa-east-1

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

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

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

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

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

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

    • 亚太地区(香港):ap-east-1

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

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

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

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

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

    • 中国(北京):cn-north-1

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

    • AmazonGovCloud(美国西部):us-gov-west-1

    • AmazonGovCloud(美国东部):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— 所使用的线程数是可用的 vCPUs 数除以 8。

    • MEDIUM— 所使用的线程数是可用的 vCPUs 数除以 2。

    • HIGH— 所使用的线程数等于可用 vCPUs 的数量。

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

      但是,这并不意味着OVERSUBSCRIBE设置会导致 100% 的 CPU 使用率。由于负载操作受 I/O 限制,所以预期的最高 CPU 利用率在 60% 至 70% 的范围内。

    默认值HIGH

    这些区域有:parallelism加载 OpenPher 数据时,设置有时会导致线程之间的死锁。出现这种情况时,Neptune 将返回LOAD_DATA_DEADLOCK错误消息。你通常可以通过设置来修复问题parallelism更低的设置,然后重试 load 命令。

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

    名称 示例值 描述
    命名 Graphuri http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph The default graph for all RDF formats when no graph is specified (for non-quads formats and NQUAD entries with no graph). The default is http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph
    baseuri http://aws.amazon.com/neptune/default The base URI for RDF/XML and Turtle formats. The default is http://aws.amazon.com/neptune/default.
    AllowEmptyString true

    在加载 CSV 数据时,Gremlin 用户需要能够将空字符串值 (“”) 作为节点和边缘属性传递。如果allowEmptyStrings设置为false(默认值),这样的空字符串被视为空值,不加载。

    如果allowEmptyStrings设置为true,加载器将空字符串视为有效的属性值并相应地加载它们。

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

  • updateSingleCardinalityProperties— 这是一个可选参数,用于控制批量加载程序如何处理单基数顶点或边缘属性的新值。加载 OpenPher 数据不支持这(请参阅加载 Openpher 数据)。

    允许的值"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

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

  • userProvidedEdgeIds— 只有在加载包含关系 ID 的 OpenPher 数据时,才需要使用此参数。它必须包含并将其设置为True当加载数据中明确提供 OpenPher 关系 ID 时(推荐)。

    何时userProvidedEdgeIds存在并设置为True,一个:ID列必须存在于加载中的每个关系文件中。

    何时userProvidedEdgeIds缺席或设置为False,加载中的关系文件必须不能包含:IDcolumn. 相反,Neptune 加载器会自动为每个关系生成一个 ID。

    明确提供关系 ID 非常有用,以便加载器可以在修复 CSV 数据中的错误后恢复加载,而无需重新加载已加载的任何关系。如果尚未明确分配关系 ID,则加载器无法恢复失败的加载,如果任何关系文件必须更正,而必须重新加载所有关系。

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

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

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

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

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

加载 OpenPher 数据的特殊注意事项

  • 当以 CSV 格式加载 OpenPher 数据时,格式参数必须设置为opencypher.

  • 这些区域有:updateSingleCardinalityPropertiesOpenPher 加载不支持参数,因为所有 opency Pher 属性都具有单个基数。OpenPher 加载格式不支持数组,如果 ID 值不止一次出现,则将其视为重复错误或插入错误(见下文)。

  • Neptune 加载器处理它在 OpenPher 数据中遇到的重复项,如下所示:

    • 如果加载器遇到具有相同节点或关系 ID 的多行,则只加载其中一行,哪一行不确定性。

    • 如果加载器遇到具有现有节点或关系 ID 的加载数据,则永远不会更新数据库中现有节点或关系的属性值。相反,当加载器遇到包含现有节点或关系 ID 的行时,它只会忽略该行。

  • 尽管你不必为关系分配 ID,但通常是个好主意(请参阅userProvidedEdgeIds上面的参数)。如果没有明确的关系 ID,加载器必须在关系文件中出现错误时重新加载所有关系,而不是从失败的位置恢复加载。

    此外,如果加载数据不包含显式关系 ID,则加载器无法检测重复的关系。

以下是 OpenPher 加载命令的示例:

curl -X POST https://your-neptune-endpoint:port/loader \ -H 'Content-Type: application/json' \ -d ' { "source" : "s3://bucket-name/object-key-name", "format" : "opencypher", "userProvidedEdgeIds": "TRUE", "iamRoleArn" : "arn:aws:iam::account-id:role/role-name", "region" : "region", "failOnError" : "FALSE", "parallelism" : "MEDIUM", }'

加载器的响应与正常情况相同。例如:

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

Neptune 加载程序响应语法

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

200 OK (200 确定)

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

Neptune 加载程序错误

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

错误类别

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

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

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

加载程序错误消息

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

    未找到凭证。针对 IAM 控制台验证提供的凭证或Amazon 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 500)

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

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

    存储桶必须位于同一位置Amazon区域为 Neptune 数据库实例。

  • 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 返回未知错误。联系 Amazon Web Services 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 加载程序

例 Request

下面是使用 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" }'

例 Response

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