本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Neptune 加载程序参考 本节介绍了 Neptune 数据库实例的 HTTP 终端节点提供的`Loader` APIs 适用于亚马逊 Neptune 的。 **注意** 有关加载程序在出现错误时返回的错误和馈送消息的列表，请参阅[Neptune 加载程序错误和源消息](loader-message.md)。 **Contents** + [Neptune 加载程序命令](load-api-reference-load.md) + [Neptune 加载程序请求语法](load-api-reference-load.md#load-api-reference-load-syntax) + [Neptune 加载程序请求参数](load-api-reference-load.md#load-api-reference-load-parameters) + [加载 openCypher 数据的特殊注意事项](load-api-reference-load.md#load-api-reference-load-parameters-opencypher) + [Neptune 加载程序响应语法](load-api-reference-load.md#load-api-reference-load-return) + [Neptune 加载程序错误](load-api-reference-load-errors.md) + [Neptune 加载程序示例](load-api-reference-load-examples.md) + [Neptune 加载器 API Get-Status](load-api-reference-status.md) + [Neptune Loader 请求 Get-Status](load-api-reference-status-requests.md) + [加载器 Get-Status 请求语法](load-api-reference-status-requests.md#load-api-reference-status-request-syntax) + [Neptune 加载器请求参数 Get-Status](load-api-reference-status-requests.md#load-api-reference-status-parameters) + [Neptune 加载器响应 Get-Status](load-api-reference-status-response.md) + [Neptune 加载器 Get-Status 响应 JSON 布局](load-api-reference-status-response.md#load-api-reference-status-response-layout) + [Neptune 加载 Get-Status `overallStatus`器和响应对象 `failedFeeds`](load-api-reference-status-response.md#load-api-reference-status-response-objects) + [Neptune 加载器响应对象 Get-Status `errors`](load-api-reference-status-response.md#load-api-reference-status-errors) + [Neptune 加载器响应对象 Get-Status `errorLogs`](load-api-reference-status-response.md#load-api-reference-error-logs) + [Neptune 装载机示例 Get-Status](load-api-reference-status-examples.md) + [加载状态请求示例](load-api-reference-status-examples.md#load-api-reference-status-examples-status-request) + [loadId 请求示例](load-api-reference-status-examples.md#load-api-reference-status-examples-loadId-request) + [详细状态请求示例](load-api-reference-status-examples.md#load-api-reference-status-examples-details-request) + [Neptune Loader 示例 Get-Status `errorLogs`](load-api-reference-error-logs-examples.md) + [错误发生时的详细状态响应示例](load-api-reference-error-logs-examples.md#load-api-reference-status-examples-details-request-errors) + [`Data prefetch task interrupted` 错误示例](load-api-reference-error-logs-examples.md#load-api-reference-status-examples-task-interrupted) + [Neptune 加载程序取消任务](load-api-reference-cancel.md) + [取消任务请求语法](load-api-reference-cancel.md#load-api-reference-cancel-syntax) + [取消任务请求参数](load-api-reference-cancel.md#load-api-reference-cancel-parameters) + [取消任务响应语法](load-api-reference-cancel.md#load-api-reference-cancel-parameters-response) + [取消任务错误](load-api-reference-cancel.md#load-api-reference-cancel-parameters-errors) + [取消任务错误消息](load-api-reference-cancel.md#load-api-reference-cancel-parameters-errors-messages) + [取消任务示例](load-api-reference-cancel.md#load-api-reference-cancel-examples) # 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` 代码。 # 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 输出验证提供的证书。确保您已将在 `iamRoleArn` 中指定的 IAM 角色添加到集群。 + `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 端点](bulk-load-data.md#bulk-load-prereqs-s3)。 + `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) 加载是写入操作。在 read/write 集群终端节点上重试加载。 + `Failed to start load because of unknown error from S3`  (HTTP 500) Amazon S3 返回了未知错误。联系 [AWS 支持](https://aws.amazon.com/premiumsupport/)。 + `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 加载程序示例 此示例演示如何使用 Neptune 加载程序使用 Gremlin CSV 格式将数据加载到 Neptune 图形数据库中。该请求作为 HTTP POST 请求发送到 Neptune 加载程序端点，请求正文包含指定数据来源、格式、IAM 角色和其他配置选项所需的参数。响应包括加载 ID，可用于跟踪数据加载过程的进度。 **Example 请求** 下面是使用 `curl` 命令经由 HTTP POST 发送的请求。它加载 Neptune CSV 格式的文件。有关更多信息，请参阅 [Gremlin 加载数据格式](bulk-load-tutorial-format-gremlin.md)。 ``` 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" }' ``` **Example 响应** ``` { "status" : "200 OK", "payload" : { "loadId" : "ef478d76-d9da-4d94-8ff1-08d9d4863aa5" } } ``` # Neptune 加载器 API Get-Status 获取 `loader` 任务的状态。 要获取加载状态，必须将 HTTP `GET` 请求发送到 `https://your-neptune-endpoint:port/loader` 终端节点。要获取特定加载请求的状态，必须包含 `loadId` 作为 URL 参数，也可将 `loadId` 附加到 URL 路径。 Neptune 仅跟踪最近的 1024 个批量加载任务，并且仅存储每个任务的最后 10000 个错误详细信息。 有关加载程序在出现错误时返回的错误和馈送消息的列表，请参阅[Neptune 加载程序错误和源消息](loader-message.md)。 **Contents** + [Neptune Loader 请求 Get-Status](load-api-reference-status-requests.md) + [加载器 Get-Status 请求语法](load-api-reference-status-requests.md#load-api-reference-status-request-syntax) + [Neptune 加载器请求参数 Get-Status](load-api-reference-status-requests.md#load-api-reference-status-parameters) + [Neptune 加载器响应 Get-Status](load-api-reference-status-response.md) + [Neptune 加载器 Get-Status 响应 JSON 布局](load-api-reference-status-response.md#load-api-reference-status-response-layout) + [Neptune 加载 Get-Status `overallStatus`器和响应对象 `failedFeeds`](load-api-reference-status-response.md#load-api-reference-status-response-objects) + [Neptune 加载器响应对象 Get-Status `errors`](load-api-reference-status-response.md#load-api-reference-status-errors) + [Neptune 加载器响应对象 Get-Status `errorLogs`](load-api-reference-status-response.md#load-api-reference-error-logs) + [Neptune 装载机示例 Get-Status](load-api-reference-status-examples.md) + [加载状态请求示例](load-api-reference-status-examples.md#load-api-reference-status-examples-status-request) + [loadId 请求示例](load-api-reference-status-examples.md#load-api-reference-status-examples-loadId-request) + [详细状态请求示例](load-api-reference-status-examples.md#load-api-reference-status-examples-details-request) + [Neptune Loader 示例 Get-Status `errorLogs`](load-api-reference-error-logs-examples.md) + [错误发生时的详细状态响应示例](load-api-reference-error-logs-examples.md#load-api-reference-status-examples-details-request-errors) + [`Data prefetch task interrupted` 错误示例](load-api-reference-error-logs-examples.md#load-api-reference-status-examples-task-interrupted) # Neptune Loader 请求 Get-Status ## 加载器 Get-Status 请求语法 ``` GET https://your-neptune-endpoint:port/loader?loadId=loadId ``` ``` GET https://your-neptune-endpoint:port/loader/loadId ``` ``` GET https://your-neptune-endpoint:port/loader ``` ## Neptune 加载器请求参数 Get-Status + **`loadId`** – 加载任务的 ID。如果未指定`loadId`， IDs 则返回负载列表。 + **`details`** – 包括整体状态之外的详细信息。 *允许的值*：`TRUE`、`FALSE`。 *默认值：*`FALSE`。 + **`errors`** – 包含错误的列表。 *允许的值*：`TRUE`、`FALSE`。 *默认值：*`FALSE`。 将对错误的列表进行分页。`page` 和 `errorsPerPage` 参数允许浏览所有错误。 + **`page`** – 错误页码。仅当 `errors` 参数设置为 `TRUE` 时有效。 *允许的值*：正整数。 *默认值*：1。 + **`errorsPerPage`** – 每页的错误数量。仅当 `errors` 参数设置为 `TRUE` 时有效。 *允许的值*：正整数。 *默认值*：10。 + **`limit`** – 要列出的加载 ID 的数量。仅当 IDs 通过发送未`loadId`指定请求来`GET`请求负荷列表时才有效。 *允许的值*：从 1 到 100 的正整数。 *默认值*：100。 + **`includeQueuedLoads`**— 一个可选参数，可用于在请求加载 IDs 列表时排除排队加载请求的负载 IDs。 默认情况下，所有带有状态 IDs 的加载任务的加载`LOAD_IN_QUEUE`都包含在这样的列表中。它们出现在加载 IDs 其他作业之前，按它们加入队列的时间从最近到最早排序。 *允许的值*：`TRUE`、`FALSE`。 *默认值：*`TRUE`。 # Neptune 加载器响应 Get-Status 以下来自 Neptune Get-Status API 的示例响应描述了响应的整体结构，解释了各种字段及其数据类型，以及错误处理和错误日志的详细信息。 ## Neptune 加载器 Get-Status 响应 JSON 布局 加载程序状态响应的总体布局如下： ``` { "status" : "200 OK", "payload" : { "feedCount" : [ { "LOAD_FAILED" : number } ], "overallStatus" : { "fullUri" : "s3://bucket/key", "runNumber" : number, "retryNumber" : number, "status" : "string", "totalTimeSpent" : number, "startTime" : number, "totalRecords" : number, "totalDuplicates" : number, "parsingErrors" : number, "datatypeMismatchErrors" : number, "insertErrors" : number, }, "failedFeeds" : [ { "fullUri" : "s3://bucket/key", "runNumber" : number, "retryNumber" : number, "status" : "string", "totalTimeSpent" : number, "startTime" : number, "totalRecords" : number, "totalDuplicates" : number, "parsingErrors" : number, "datatypeMismatchErrors" : number, "insertErrors" : number, } ], "errors" : { "startIndex" : number, "endIndex" : number, "loadId" : "string, "errorLogs" : [ ] } } } ``` ## Neptune 加载 Get-Status `overallStatus`器和响应对象 `failedFeeds` 为每个失败馈送返回的可能响应（包括错误描述）与 `Get-Status` 响应中的 `overallStatus` 对象相同。 以下字段显示在所有负载的 `overallStatus` 对象中，以及每个失败馈送的 `failedFeeds` 对象中： + **`fullUri` ** – 要加载的一个或多个文件的 URI。 *类型*：*字符串* *格式*：`s3://bucket/key`。 + **`runNumber`** – 此加载或馈送的运行编号。此编号将在加载重新启动时增加。 *类型：**无符号整数* + **`retryNumber`** – 此加载或馈送的重试编号。此编号将在加载程序自动重试馈送或加载时递增。 *类型：**无符号整数* + **`status`** – 返回的加载状态或馈送状态。`LOAD_COMPLETED` 指示加载成功，无问题。有关其它加载状态消息的列表，请参阅[Neptune 加载程序错误和源消息](loader-message.md)。 *类型：**字符串*。 + **`totalTimeSpent`** – 解析并插入以进行加载或馈送的数据所耗费的时间（秒）。这不包括提取源文件列表所耗费时间。 *类型：**无符号整数* + **`totalRecords`** – 已加载或尝试加载的记录总数。 *类型：**无符号整数* 请注意，从 CSV 文件加载时，记录计数不是指加载的行数，而是指这些行中的单个记录数。例如，以一个小的 CSV 文件为例： ``` ~id,~label,name,team 'P-1','Player','Stokes','England' ``` Neptune 会认为这个文件包含 3 条记录，即： ``` P-1 label Player P-1 name Stokes P-1 team England ``` + **`totalDuplicates`** – 遇到的重复记录的数量。 *类型：**无符号整数* 与 `totalRecords` 计数一样，此值包含 CSV 文件中单个重复记录的数量，而不是重复行的数量。以这个小的 CSV 文件为例： ``` ~id,~label,name,team P-2,Player,Kohli,India P-2,Player,Kohli,India ``` 加载此文件后返回的状态如下所示，报告总共 6 条记录，其中 3 条是重复的： ``` { "status": "200 OK", "payload": { "feedCount": [ { "LOAD_COMPLETED": 1 } ], "overallStatus": { "fullUri": "(the URI of the CSV file)", "runNumber": 1, "retryNumber": 0, "status": "LOAD_COMPLETED", "totalTimeSpent": 3, "startTime": 1662131463, "totalRecords": 6, "totalDuplicates": 3, "parsingErrors": 0, "datatypeMismatchErrors": 0, "insertErrors": 0 } } } ``` 对于 openCypher 加载，在以下情况下会计算重复记录： + 加载程序检测到节点文件中的某行具有的 ID 没有 ID 空间，而该 ID 与另一个没有 ID 空间的 ID 值相同，无论是在另一行中还是属于现有节点。 + 加载程序检测到节点文件中的某行具有的 ID 有 ID 空间，而该 ID 与另一个有 ID 空间的 ID 值相同，无论是在另一行中还是属于现有节点。 请参阅[加载 openCypher 数据的特殊注意事项](load-api-reference-load.md#load-api-reference-load-parameters-opencypher)。 + **`parsingErrors`** – 遇到的解析错误的数量。 *类型：**无符号整数* + **`datatypeMismatchErrors`** – 数据类型与给定的数据不匹配的记录的数量。 *类型：**无符号整数* + **`insertErrors`** – 由于错误而无法插入的记录的数量。 *类型：**无符号整数* ## Neptune 加载器响应对象 Get-Status `errors` 错误分为以下几类： + **`Error 400`** - 无效的 `loadId` 返回 HTTP `400` 错误请求错误。此消息描述错误。 + **`Error 500`** – 无法处理的有效请求返回 HTTP `500` 内部服务器错误。此消息描述错误。 有关加载程序在出现错误时返回的错误和馈送消息的列表，请参阅[Neptune 加载程序错误和源消息](loader-message.md)。 当发生错误时，会在响应的 `BODY` 中返回一个 JSON `errors` 对象，其中包含以下字段： + **`startIndex`** – 包含的第一个错误的索引。 *类型：**无符号整数* + **`endIndex`** – 包含的最后一个错误的索引。 *类型：**无符号整数* + **`loadId`** – 加载的 ID。可通过将 `errors` 参数设置为 `TRUE` 来使用此 ID 打印错误。 *类型：**字符串*。 + **`errorLogs`** – 错误列表。 *类型：**列表* ## Neptune 加载器响应对象 Get-Status `errorLogs` 加载程序获取状态响应中 `errors` 下的 `errorLogs` 对象包含一个使用以下字段描述每个错误的对象： + **`errorCode`** – 识别错误的性质。 它可能采用下列值之一： + `PARSING_ERROR` + `S3_ACCESS_DENIED_ERROR` + `FROM_OR_TO_VERTEX_ARE_MISSING` + `ID_ASSIGNED_TO_MULTIPLE_EDGES` + `SINGLE_CARDINALITY_VIOLATION` + `FILE_MODIFICATION_OR_DELETION_ERROR` + `OUT_OF_MEMORY_ERROR` + `INTERNAL_ERROR`（当批量加载程序无法确定错误的类型时返回）。 + **`errorMessage`** – 描述错误的消息。 这可以是与错误代码关联的通用消息，也可以是包含详细信息（例如有关缺失 from/to 顶点或解析错误的信息）的特定消息。 + **`fileName`** – 馈送的名称。 + **`recordNum`** – 如果出现解析错误，则这是记录文件中无法解析的记录号。如果记录号不适用于错误，或者无法确定，则将其设置为零。 例如，如果批量加载程序在 RDF `nquads` 文件中遇到诸如以下内容的错误行，则会生成解析错误： ``` |http://base#predicate> . ``` 如您所见，上面一行中的第二个 `http` 应该在前面加上 `<` 而不是 `|`。状态响应中 `errorLogs` 下生成的错误对象如下所示： ``` { "errorCode" : "PARSING_ERROR", "errorMessage" : "Expected '<', found: |", "fileName" : "s3://bucket/key", "recordNum" : 12345 }, ``` # Neptune 装载机示例 Get-Status 以下示例展示了 Neptune 加载程序的 GET-Status API 的用法，它可让您检索有关数据加载到 Amazon Neptune 图形数据库中的状态的信息。这些示例涵盖了三种主要场景：检索特定负荷的状态、列出可用负荷 IDs以及请求特定负荷的详细状态信息。 ## 加载状态请求示例 下面是使用 `curl` 命令经由 HTTP `GET` 发送的请求。 ``` curl -X GET 'https://your-neptune-endpoint:port/loader/loadId (a UUID)' ``` **Example 响应** ``` { "status" : "200 OK", "payload" : { "feedCount" : [ { "LOAD_FAILED" : 1 } ], "overallStatus" : { "datatypeMismatchErrors" : 0, "fullUri" : "s3://bucket/key", "insertErrors" : 0, "parsingErrors" : 5, "retryNumber" : 0, "runNumber" : 1, "status" : "LOAD_FAILED", "totalDuplicates" : 0, "totalRecords" : 5, "totalTimeSpent" : 3.0 } } } ``` ## loadId 请求示例 下面是使用 `curl` 命令经由 HTTP `GET` 发送的请求。 ``` curl -X GET 'https://your-neptune-endpoint:port/loader?limit=3' ``` **Example 响应** ``` { "status" : "200 OK", "payload" : { "loadIds" : [ "a2c0ce44-a44b-4517-8cd4-1dc144a8e5b5", "09683a01-6f37-4774-bb1b-5620d87f1931", "58085eb8-ceb4-4029-a3dc-3840969826b9" ] } } ``` ## 详细状态请求示例 下面是使用 `curl` 命令经由 HTTP `GET` 发送的请求。 ``` curl -X GET 'https://your-neptune-endpoint:port/loader/loadId (a UUID)?details=true' ``` **Example 响应** ``` { "status" : "200 OK", "payload" : { "failedFeeds" : [ { "datatypeMismatchErrors" : 0, "fullUri" : "s3://bucket/key", "insertErrors" : 0, "parsingErrors" : 5, "retryNumber" : 0, "runNumber" : 1, "status" : "LOAD_FAILED", "totalDuplicates" : 0, "totalRecords" : 5, "totalTimeSpent" : 3.0 } ], "feedCount" : [ { "LOAD_FAILED" : 1 } ], "overallStatus" : { "datatypeMismatchErrors" : 0, "fullUri" : "s3://bucket/key", "insertErrors" : 0, "parsingErrors" : 5, "retryNumber" : 0, "runNumber" : 1, "status" : "LOAD_FAILED", "totalDuplicates" : 0, "totalRecords" : 5, "totalTimeSpent" : 3.0 } } } ``` # Neptune Loader 示例 Get-Status `errorLogs` 以下示例展示了在数据加载过程中出现错误时，Neptune 加载程序发出的详细状态响应。这些示例说明了响应的结构，包括有关失败的馈送、总体状态和详细错误日志的信息。 ## 错误发生时的详细状态响应示例 这是使用 `curl` 通过 HTTP `GET` 发送的请求： ``` curl -X GET 'https://your-neptune-endpoint:port/loader/0a237328-afd5-4574-a0bc-c29ce5f54802?details=true&errors=true&page=1&errorsPerPage=3' ``` **Example 属于出现错误时的详细响应** 这是您可能从上面的查询中得到的响应的示例，其中 `errorLogs` 对象列出了遇到的加载错误： ``` { "status" : "200 OK", "payload" : { "failedFeeds" : [ { "datatypeMismatchErrors" : 0, "fullUri" : "s3://bucket/key", "insertErrors" : 0, "parsingErrors" : 5, "retryNumber" : 0, "runNumber" : 1, "status" : "LOAD_FAILED", "totalDuplicates" : 0, "totalRecords" : 5, "totalTimeSpent" : 3.0 } ], "feedCount" : [ { "LOAD_FAILED" : 1 } ], "overallStatus" : { "datatypeMismatchErrors" : 0, "fullUri" : "s3://bucket/key", "insertErrors" : 0, "parsingErrors" : 5, "retryNumber" : 0, "runNumber" : 1, "status" : "LOAD_FAILED", "totalDuplicates" : 0, "totalRecords" : 5, "totalTimeSpent" : 3.0 }, "errors" : { "endIndex" : 3, "errorLogs" : [ { "errorCode" : "PARSING_ERROR", "errorMessage" : "Expected '<', found: |", "fileName" : "s3://bucket/key", "recordNum" : 1 }, { "errorCode" : "PARSING_ERROR", "errorMessage" : "Expected '<', found: |", "fileName" : "s3://bucket/key", "recordNum" : 2 }, { "errorCode" : "PARSING_ERROR", "errorMessage" : "Expected '<', found: |", "fileName" : "s3://bucket/key", "recordNum" : 3 } ], "loadId" : "0a237328-afd5-4574-a0bc-c29ce5f54802", "startIndex" : 1 } } } ``` ## `Data prefetch task interrupted` 错误示例 在某些情况下，当您收到 `LOAD_FAILED` 状态，然后请求详细信息时，返回的错误可能是 `PARSING_ERROR` 以及 `Data prefetch task interrupted` 消息，如下所示： ``` "errorLogs" : [ { "errorCode" : "PARSING_ERROR", "errorMessage" : "Data prefetch task interrupted: Data prefetch task for 11467 failed", "fileName" : "s3://amzn-s3-demo-bucket/some-source-file", "recordNum" : 0 } ] ``` 在数据加载过程中发生临时中断时会出现此错误，这种中断一般不是由您的请求或数据导致的。这通常可以通过再次运行批量上传请求加以解决。如果您使用的是默认设置，即 `"mode":"AUTO"` 和 `"failOnError":"TRUE"`，则在发生中断时，加载程序会跳过已经成功加载的文件，并继续加载尚未加载的文件。 # Neptune 加载程序取消任务 取消加载任务。 要取消任务，必须将 HTTP `DELETE` 请求发送到 `https://your-neptune-endpoint:port/loader` 终端节点。`loadId` 可以追加到 `/loader` URL 路径，或作为变量包含在 URL 中。 ## 取消任务请求语法 ``` DELETE https://your-neptune-endpoint:port/loader?loadId=loadId ``` ``` DELETE https://your-neptune-endpoint:port/loader/loadId ``` ## 取消任务请求参数 **loadId** 加载任务的 ID。 ## 取消任务响应语法 ``` no response body ``` **200 OK (200 确定)** 成功删除的加载任务将返回 `200` 代码。 ## 取消任务错误 当错误出现后，响应的 `BODY` 中将返回 JSON 对象。`message` 对象包含对错误的描述。 **错误类别** + **`Error 400`** - 无效的 `loadId` 返回 HTTP `400` 错误请求错误。此消息描述错误。 + **`Error 500`** – 无法处理的有效请求返回 HTTP `500` 内部服务器错误。此消息描述错误。 ## 取消任务错误消息 以下是来自取消 API 的可能的错误消息，其中包含对错误的描述。 + `The load with id = load_id does not exist or not active` (HTTP 404) – 找不到加载。检查 `id` 参数的值。 + `Load cancellation is not permitted on a read replica instance.` (HTTP 405) – 加载是写入操作。在 read/write 集群终端节点上重试加载。 ## 取消任务示例 **Example 请求** 下面是使用 `curl` 命令经由 HTTP `DELETE` 发送的请求。 ``` curl -X DELETE 'https://your-neptune-endpoint:port/loader/0a237328-afd5-4574-a0bc-c29ce5f54802' ```