Neptune 加载程序命令 - Amazon Neptune
请求语法请求参数响应语法

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

Neptune 加载程序命令

将 Amazon S3 桶中的数据加载到 Neptune 数据库实例中。

要加载数据，必须向https://your-neptune-endpoint:port/loader端点发送HTTPPOST请求。loader请求的参数可以在POST正文中发送，也可以作为URL编码参数发送。

重要

MIME类型必须是application/json。

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

注意

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

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

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

您不必等到一个加载任务完成后再开始另一个加载任务。Neptune 可以一次对多达 64 个任务请求进行排队，前提是它们的 queueRequest 参数全部设置为 "TRUE"。作业的队列顺序将是 first-in-first-out (FIFO)。另一方面，如果您不希望对某个加载任务排队，则可以将其 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— 亚马逊 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-name元素等同URI于 Amazon S3 ListObjectsAPI调用中的前缀参数。它可以识别指定的 Amazon S3 桶中名称以该前缀开头的所有对象。可以是单个文件或文件夹，也可以是多个文件和/或文件夹。

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

    例如，如果您在名为的 Amazon S3 存储桶中有以下文件夹结构和文件bucket-name：

    s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade
s3://bucket-name/bcd

    如果将 source 参数指定为s3://bucket-name/a，则将加载前三个文件。

    s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade

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

    允许值

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

    从引擎版本 1.2.1.0.R3 开始，IAM如果 Neptune 数据库实例和 Amazon S3 存储桶位于不同的账户中，您还可以链接多个角色。 AWS 在本例中，iamRoleArn包含以逗号分隔的角色列表ARNs，如中所述。在 Amazon Neptune 中连锁IAM角色例如：

    curl -X POST https://localhost:8182/loader \
  -H 'Content-Type: application/json' \
  -d '{
        "source" : "s3://(the target bucket name)/(the target date file name)",
        "iamRoleArn" : "arn:aws:iam::(Account A ID):role/(RoleA),arn:aws:iam::(Account B ID):role/(RoleB),arn:aws:iam::(Account C ID):role/(RoleC)",
        "format" : "csv",
        "region" : "us-east-1"
      }'

  • region— 该region参数必须与集群的 AWS 区域和 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-south-2

    • 欧洲地区（爱尔兰）：eu-west-1

    • 欧洲地区（伦敦）：eu-west-2

    • 欧洲地区（巴黎）：eu-west-3

    • 欧洲地区（法兰克福）：eu-central-1

    • 中东（巴林）：me-south-1

    • 中东 (UAE): me-central-1

    • 以色列（特拉维夫）：il-central-1

    • 非洲（开普敦）：af-south-1

    • 亚太地区（香港）：ap-east-1

    • 亚太地区（东京）：ap-northeast-1

    • 亚太地区（首尔）：ap-northeast-2

    • 亚太地区（大阪）：ap-northeast-3

    • 亚太地区（新加坡）：ap-southeast-1

    • 亚太地区（悉尼）：ap-southeast-2

    • 亚太地区（雅加达）：ap-southeast-3

    • 亚太地区（孟买）：ap-south-1

    • 中国（北京）：cn-north-1

    • 中国（宁夏）：cn-northwest-1

    • AWS GovCloud （美国西部）：us-gov-west-1

    • AWS GovCloud （美国东部）：us-gov-east-1

  • mode – 加载任务模式。

    允许的值：RESUME、NEW、AUTO

    默认值：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

    加载 openCypher 数据时，该parallelism设置有时会导致线程之间出现死锁。发生这种情况时，Neptune 会返回 LOAD_DATA_DEADLOCK 错误。通常，您可以通过将 parallelism 设为较低的设置并重试加载命令来解决此问题。

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

    名称 示例值 描述
    namedGraphUri http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph 未指定图形时所有RDF格式的默认图表（适用于非四边形格式和没有图形的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。
    allowEmptyStrings true

    Gremlin 用户在加载CSV数据时需要能够将空字符串值 (“”) 作为节点和边缘属性传递。如果 allowEmptyStrings 设置为 false（默认值），则此类空字符串将视为 null 且不会加载。

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

    有关更多信息，请参阅 SPARQL默认图表和命名图表。

  • updateSingleCardinalityProperties – 这是一个可选参数，用于控制批量加载程序如何处理单基数顶点或边缘属性的新值。加载 openCypher 数据时不支持这样做（请参阅正在加载 openCypher 数据）。

    允许的值："TRUE"、"FALSE"。

    默认值："FALSE"。

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

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

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

    您不必等到一个加载任务完成就可以发出下一个任务，因为 Neptune 可以一次对多达 64 个任务进行排队，前提是它们的 queueRequest 参数都设置为 "TRUE"。作业的队列顺序将是 first-in-first-out (FIFO)。

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

    允许的值："TRUE"、"FALSE"。

    默认值："FALSE"。

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

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

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

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

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

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

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

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

  • userProvidedEdgeIds— 只有在加载包含关系 openCypher 的数据时才需要此参数IDs。当加载数据中明确提供 openCypher 关系True时IDs，必须将其包含并设置为（推荐）。

    如果 userProvidedEdgeIds 不存在或设置为 True，则加载过程中的每个关系文件中都必须存在 :ID 列。

    如果 userProvidedEdgeIds 存在且设置为 False，则加载中的关系文件不得包含 :ID 列。相反，Neptune 加载程序会自动为每个关系生成一个 ID。

    IDs显式提供关系很有用，这样加载器就可以在修复CSV数据错误后恢复加载，而不必重新加载任何已经加载的关系。如果IDs尚未明确分配关系，则如果必须更正任何关系文件，加载程序将无法恢复失败的加载，而是必须重新加载所有关系。

  • 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 代码。