本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Neptune 加载程序命令 将 Amazon S3 桶中的数据加载到 Neptune 数据库实例中。 要加载数据，必须将 HTTP `POST` 请求发送到 `https://your-neptune-endpoint:port/loader` 终端节点。`loader` 请求的参数可在 `POST` 正文中或作为 URL 编码的参数发送。 **重要** MIME 类型必须为 `application/json`。 Amazon 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"`。任务的队列顺序将是 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"] } ``` **edgeOnlyLoad 语法** 对于 `edgeOnlyLoad`，语法将是： ``` { "source" : "string", "format" : "string", "iamRoleArn" : "string", "mode": "NEW|RESUME|AUTO", "region" : "us-east-1", "failOnError" : "string", "parallelism" : "string", "edgeOnlyLoad" : "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` URI 的`object-key-name`元素等同于 Amazon S3 [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html)API 调用中的[前缀](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html#API_ListObjects_RequestParameters)参数。它可以识别指定的 Amazon S3 桶中名称以该前缀开头的所有对象。可以是单个文件或文件夹，也可以是多个文件文件 and/or 夹。 指定的一个或多个文件夹可以包含多个顶点文件和多个边缘文件。 例如，如果您在名为 `bucket-name` 的 Amazon S3 存储桶中具有以下文件夹结构和文件： ``` s3://bucket-name/a/bc s3://bucket-name/ab/c s3://bucket-name/ade s3://bucket-name/bcd ``` 如果将源参数指定为 `s3://bucket-name/a`，则系统将加载前三个文件。 ``` s3://bucket-name/a/bc s3://bucket-name/ab/c s3://bucket-name/ade ``` + **`format`** – 数据的格式。有关 Neptune `Loader` 命令的数据格式的更多信息，请参阅[使用 Amazon Neptune 批量加载程序摄取数据](bulk-load.md)。 **允许值** + **`csv`** 适用于 [Gremlin CSV 数据格式](bulk-load-tutorial-format-gremlin.md)。 + **`opencypher`** 适用于 [openCypher CSV 数据格式](bulk-load-tutorial-format-opencypher.md)。 + **`ntriples`** 适用于 [N-Triples RDF 数据格式](https://www.w3.org/TR/n-triples/)。 + **`nquads`** 适用于 [N-Quads RDF 数据格式](https://www.w3.org/TR/n-quads/)。 + **`rdfxml`** 适用于 [RDF\$1XML RDF 数据](https://www.w3.org/TR/rdf-syntax-grammar/)格式。 + **`turtle`** 适用于 [Turtle RDF 数据格式](https://www.w3.org/TR/turtle/)。 + **`iamRoleArn`** – Neptune 数据库实例为访问 S3 桶而代入的 IAM 角色的 Amazon 资源名称 (ARN)。有关创建对 Amazon S3 具有访问权限的角色，然后将其与 Neptune 集群关联的信息，请参阅[先决条件：IAM 角色和 Amazon S3 访问权限](bulk-load-tutorial-IAM.md)。 从[引擎版本 1.2.1.0.R3](engine-releases-1.2.1.0.R3.md) 开始，如果 Neptune 数据库实例和 Amazon S3 存储桶位于不同的账户中，您还可以链接多个 IAM 角色。 AWS 在本例中，`iamRoleArn`包含以逗号分隔的角色列表 ARNs，如中所述。[在 Amazon Neptune 中串联 IAM 角色](bulk-load-tutorial-chain-roles.md)例如： ``` 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` + 加拿大西部（卡尔加里）：`ca-west-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` + 中东（阿联酋）：`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-southeast-4` + 亚太地区（马来西亚）：`ap-southeast-5` + 亚太地区（孟买）：`ap-south-1` + 亚太地区（海得拉巴）：`ap-south-2` + 中国（北京）：`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` 模式中一样。 + **`edgeOnlyLoad`** – 用于控制批量加载期间文件处理顺序的标志。 *允许的值*：`"TRUE"`、`"FALSE"`。 *默认值：*`"FALSE"`。 当此参数设置为“FALSE”时，加载程序会自动先加载顶点文件，然后再加载边缘文件。它通过首先扫描所有文件以确定其内容（顶点或边缘）来执行这一操作。当此参数设置为“TRUE”时，加载程序会跳过初始扫描阶段，立即按照文件出现的顺序加载所有文件。有关更多信息，请参阅[批量加载优化](https://docs.aws.amazon.com//neptune/latest/userguide/bulk-load-optimize.html)。 + **`failOnError`** – 用于在出错时切换为完全停止的标志。 *允许的值*：`"TRUE"`、`"FALSE"`。 *默认值：*`"TRUE"`。 如果此参数设置为 `"FALSE"`，则加载程序尝试加载指定位置中的所有数据并跳过任何出错的条目。 将此参数设置为 `"TRUE"` 时，加载程序会在遇到错误时立即停止。截至该点加载的数据仍然存在。 + **`parallelism`** – 这是一个可选参数，可以设置用于减少批量加载过程使用的线程数。 *允许的值*： + `LOW`— 使用的线程数等于可用线程数 v CPUs 除以 8。 + `MEDIUM`— 使用的线程数等于可用线程数 v CPUs 除以 2。 + `HIGH`— 使用的线程数与可用线程数 v 相同CPUs。 + `OVERSUBSCRIBE`— 使用的线程数是可用线程数 v CPUs 乘以 2。如果使用此值，则批量加载程序将占用所有可用资源。 但是，这并不意味着 `OVERSUBSCRIBE` 设置会导致 100% 的 CPU 利用率。由于负载操作是 I/O 受限的，因此预期的最高 CPU 利用率在 60% 到 70% 之间。 *默认值*：`HIGH` 在加载 openCypher 数据时，`parallelism` 设置有时会导致线程之间出现死锁。发生这种情况时，Neptune 会返回 `LOAD_DATA_DEADLOCK` 错误。通常，您可以通过将 `parallelism` 设为较低的设置并重试加载命令来解决此问题。 + **`parserConfiguration`** – 具有额外解析程序配置值的可选对象。每个子参数也是可选的： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/load-api-reference-load.html) 有关更多信息，请参阅 [SPARQL 默认图形和命名图形](feature-sparql-compliance.md#sparql-default-graph)。 + **`updateSingleCardinalityProperties`** – 这是一个可选参数，用于控制批量加载程序如何处理单基数顶点或边缘属性的新值。加载 openCypher 数据时不支持这样做（请参阅[加载 openCypher 数据](#load-api-reference-load-parameters-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。 1. 提交 `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 访问权限](bulk-load-tutorial-IAM.md)。 有关更多信息，请参阅[访问密钥（访问密钥 ID 和秘密访问密钥）](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)。 + `secretKey` – **[已弃用]** 建议改用 `iamRoleArn` 参数。有关创建对 Amazon S3 具有访问权限的角色，然后将其与 Neptune 集群关联的信息，请参阅[先决条件：IAM 角色和 Amazon S3 访问权限](bulk-load-tutorial-IAM.md)。 有关更多信息，请参阅[访问密钥（访问密钥 ID 和秘密访问密钥）](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)。 ### 加载 openCypher 数据的特殊注意事项 + 以 CSV 格式加载 openCypher 数据时，必须将格式参数设置为 `opencypher`。 + openCypher 加载不支持 `updateSingleCardinalityProperties` 参数，因为所有 openCypher 属性都具有单一基数。openCypher 加载格式不支持数组，如果一个 ID 值出现多次，则将其视为重复值或插入错误（见下文）。 + Neptune 加载程序按如下方式处理它在 openCypher 数据中遇到的重复项： + 如果加载程序遇到多个具有相同节点 ID 的行，则使用以下规则将它们合并： + 行中的所有标签都将添加到节点中。 + 对于每个属性，只加载其中一个属性值。选择要加载哪个属性值是不确定的。 + 如果加载程序遇到多个具有相同关系 ID 的行，则只加载其中一行。选择要加载哪一行是不确定的。 + 如果加载程序遇到具有现有节点或关系 ID 的加载数据，则它从不会更新数据库中现有节点或关系的属性值。但是，它的确会加载现有节点或关系中不存在的节点标签和属性。 + 尽管您不必 IDs 为关系赋值，但这通常是个好主意（参见上面的`userProvidedEdgeIds`参数）。如果没有明确的关系 IDs，加载器必须重新加载所有关系，以防关系文件出现错误，而不是从失败的地方恢复加载。 此外，如果加载数据不包含显式关系 IDs，则加载器无法检测重复关系。 以下是 openCypher 加载命令的示例： ``` 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` 代码。