本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Neptune 資料平面大量載入器 API 大量載入器 **大量載入動作：** + [StartLoaderJob (動作)](#StartLoaderJob) + [GetLoaderJobStatus (動作)](#GetLoaderJobStatus) + [ListLoaderJobs (動作)](#ListLoaderJobs) + [CancelLoaderJob (動作)](#CancelLoaderJob) **大量載入結構：** + [LoaderIdResult (結構)](#LoaderIdResult) ## StartLoaderJob (動作) StartLoaderJob         此 API 的 AWS CLI 名稱為：`start-loader-job`。 啟動 Neptune 大量載入器工作，將資料從 Amazon S3 儲存貯體載入至 Neptune 資料庫執行個體。請參閱[使用 Amazon Neptune 大量載入器擷取資料](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load.html)。 在已啟用 IAM 身分驗證的 Neptune 叢集中調用此操作時，發出請求的 IAM 使用者或角色必須附加一個政策，在該叢集中允許 [neptune-db:StartLoaderJob](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#startloaderjob) IAM 動作。 **請求** + **dependencies** (在 CLI 中：`--dependencies`) – 字串，類型為：`string` (UTF-8 編碼的字串)。 這是選用參數，可在佇列中一或多個先前工作順利完成時，發出排入佇列的載入請求。 Neptune 最多可以一次將 64 個載入請求排入佇列，前提是其 `queueRequest` 參數設為 `"TRUE"`。`dependencies` 參數可讓您在一或多個佇列中指定的先前請求順利完成時，執行這類佇列請求。 例如，如果載入 `Job-A` 和 `Job-B` 彼此獨立，但載入 `Job-C` 須先完成 `Job-A` 和 `Job-B` 才能開始，請依照指示執行： 1. 以任何順序一個接著一個提交 `load-job-A` 和 `load-job-B`，並儲存其載入 ID。 1. 使用兩任務其 `dependencies` 欄位中的載入 ID 提交 `load-job-C`： **Example** ``` "dependencies" : ["(job_A_load_id)", "(job_B_load_id)"] ``` 由於 `dependencies` 參數的關係，大量載入器在 `Job-A` 和 `Job-B` 順利完成之前，將不會啟動 `Job-C`。如果其中任何一個失敗，則不執行 Job-C，且其狀態將設為 `LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED`。 您可以使用這種方式設定多個相依性層級，如此一來，一項任務若失敗，將導致直間接仰賴該任務的所有請求遭取消。 + **failOnError** (在 CLI 中:`--fail-on-error`) – 布林值，類型為：`boolean` (布林值 (true 或 false))。 **`failOnError`** – 一種旗標，用來切換錯誤時完全停止。 *允許的值*：`"TRUE"`、`"FALSE"`。 *預設值*：`"TRUE"`。 此參數設為 `"FALSE"` 時，載入器會嘗試載入指定位置中的所有資料，並略過任何有錯誤的項目。 此參數設為 `"TRUE"` 時，載入器會在遇到錯誤時立即停止。到該時間點載入的資料仍然存在。 + **format** (在 CLI 中：`--format`) – *必要：*一種格式，類型為：`string` (UTF-8 編碼的字串)。 資料的格式。如需有關 Neptune `Loader` 命令的資料格式詳細資訊，請參閱[載入資料格式](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-format.html)。 **允許的值** + **`csv`** 表示 [Gremlin CSV 資料格式](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-format-gremlin.html)。 + **`opencypher`** 表示 [openCypher CSV 資料格式](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-format-opencypher.html)。 + **`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** (在 CLI 中：`--iam-role-arn`) – *必要：*字串，類型為：`string` (UTF-8 編碼的字串)。 Neptune 資料庫執行個體為了存取 S3 儲存貯體 而擔任之 IAM 角色的 Amazon Resource Name (ARN)。這裡提供的 IAM 角色 ARN 應附加至資料庫叢集 (請參閱[將 IAM 角色新增至 Amazon Neptune 叢集](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-IAM-add-role-cluster.html)。 + **mode** (在 CLI 中：`--mode`) – 一種模式，類型為：`string` (UTF-8 編碼的字串)。 載入任務模式。 *允許的值*：`RESUME`、`NEW`、`AUTO`。 *預設值*：`AUTO`。 **** + `RESUME` – 在 RESUME 模式下，載入器會從此來源尋找先前的載入，若找到某載入工作，則會繼續該工作。如果找不到先前的載入任務，載入器便會停止。 載入程式可避免重新載入已順利載入先前任務的檔案。它只會嘗試處理失敗的檔案。如果從 Neptune 叢集捨棄先前載入的資料，則不會在此模式下重新載入該資料。如果先前的載入工作已從相同來源順利載入所有檔案，則不會重新載入任何工作，且載入器會傳回成功。 + `NEW` – 在 NEW 模式下，建立新的載入請求，無論先前有任何的載入。您可以使用此模式，在捨棄 Neptune 叢集先前載入的資料之後，從來源重新載入所有資料，或者載入同一來源的可用新資料。 + `AUTO` – 在 AUTO 模式下，載入器會從相同來源尋找先前的載入任務，若找到一項載入任務，則會繼續該任務，如同 `RESUME` 模式一般。 若載入器未能從相同來源找到先前的載入任務，則會從該來源載入所有資料，如同 `NEW` 模式那樣。 + **parallelism** (在 CLI 中：`--parallelism`) – 一種平行處理，類型為：`string` (UTF-8 編碼的字串)。 您可以設定選用 `parallelism` 參數，以減少大量載入程序所使用的執行緒數目。 *允許的值*： + `LOW` – 使用的執行緒數目是可用 vCPU 除以 8 後的數字。 + `MEDIUM` – 使用的執行緒數目是可用 vCPU 除以 2 後的數字。 + `HIGH` – 使用的執行緒數目與可用 vCPU 的數目相同。 + `OVERSUBSCRIBE` – 使用的執行緒數目是可用 vCPU 乘以 2 後的數字。如果使用此值，大量載入器會佔用所有可用的資源。 不過，這並不表示 `OVERSUBSCRIBE` 設定會產生 100% CPU 使用率。由於載入操作受 I/O 限制，因此預期的最高 CPU 使用率在 60％ 到 70％ 的範圍內。 *預設值*：`HIGH` 載入 OpenCypher 資料時，`parallelism` 設定有時可能會導致執行緒之間發生死結。發生這種情況時，Neptune 會傳回 `LOAD_DATA_DEADLOCK` 錯誤。通常，您可以透過將 `parallelism` 設定為較低的設定，並重試載入命令來修正此問題。 + **parserConfiguration** (在 CLI 中：`--parser-configuration`) – 它是金鑰值對的對應陣列，其中：     每個金鑰都是字串，類型為：`string` (UTF-8 編碼的字串)。     每個值都是字串，類型為：`string` (UTF-8 編碼的字串)。 **`parserConfiguration`** – 包含額外剖析器組態值的選用物件。也可選用每個子參數： **** + **`namedGraphUri`** – 未指定圖形時，所有 RDF 格式的預設圖形 (適用於非 quads 格式及無圖形的 NQUAD 項目)。 預設值為 `https://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph`。 + **`baseUri`** – RDF/XML 和 Turtle 格式的基本 URI。 預設值為 `https://aws.amazon.com/neptune/default`。 + **`allowEmptyStrings`** – 載入 CSV 資料時，Gemlin 使用者必須能夠傳遞空字串值 ("") 做為節點和邊緣屬性。如果 `allowEmptyStrings` 設定為 `false` (預設值)，則這類空字串會被視為 null 而不會將其載入。 如果 `allowEmptyStrings` 設定為 `true`，載入器會將空字串視為有效的屬性值，並相應地載入它們。 + **queueRequest** (在 CLI 中:`--queue-request`) – 布林值，類型為：`boolean` (布林值 (true 或 false))。 此為選用旗標參數，其會指示載入請求能否排入佇列。 您不必等到載入工作完成才能發出另一個載入工作，因為 Neptune 最多可以一次將 64 個工作排入佇列，前提是其 `queueRequest` 參數都設為 `"TRUE"`。工作的佇列順序將為先進先出 (FIFO)。 如果 `queueRequest` 參數遭省略或設為 `"FALSE"`，且已有其他執行中的載入任務，則此載入請求將失敗。 *允許的值*：`"TRUE"`、`"FALSE"`。 *預設值*：`"FALSE"`。 + **s3BucketRegion** (在 CLI 中：`--s-3-bucket-region`) – *必要：*S3BucketRegion，類型為：`string` (UTF-8 編碼的字串)。 S3 儲存貯體的 Amazon 區域。這必須與資料庫叢集的 Amazon 區域相符。 + **source** (在 CLI 中：`--source`) – *必要：*字串，類型為：`string` (UTF-8 編碼的字串)。 `source` 參數接受可識別單一檔案、多個檔案、一個資料夾或多個資料夾的 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` 元素相當於 [S3 ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) API 呼叫中的 [prefix](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html#API_ListObjects_RequestParameters) 參數。它會識別所指定 S3 儲存貯體中其名稱以該字首開頭的所有物件。這可以是單一檔案或資料夾，也可以是多個檔案和/或資料夾。 一個或多個指定的資料夾可以包含多個頂點檔案和多個邊緣檔案。 + **updateSingleCardinalityProperties** (在 CLI 中:`--update-single-cardinality-properties`) – 布林值，類型為：`boolean` (布林值 (true 或 false))。 `updateSingleCardinalityProperties` 是選用參數，可控制大量載入器如何處理單一基數頂點或邊緣屬性的新值。不支援將此用於載入 openCypher 資料。 *允許的值*：`"TRUE"`、`"FALSE"`。 *預設值*：`"FALSE"`。 根據預設，或當 `updateSingleCardinalityProperties` 明確設定為 `"FALSE"` 時，載入器會將新值視為錯誤，因為它違反單一基數。 另一方面，當 `updateSingleCardinalityProperties` 設為 `"TRUE"` 時，大量載入器會以新的值取代現有的值。如果在要載入的來源檔案中提供多個邊緣或單一基數頂點屬性值，則大量載入結尾的最終值可以是這些新值的其中之一。載入器只會保證現有的值已由其中一個新值取代。 + **userProvidedEdgeIds** (在 CLI 中:`--user-provided-edge-ids`) – 布林值，類型為：`boolean` (布林值 (true 或 false))。 只有在載入包含關係 ID 的 OpenCypher 資料時，才需要這個參數。在載入資料中明確提供 OpenCypher 關係 ID 時，必須包含它並設定為 `True` (建議使用)。 如果 `userProvidedEdgeIds` 不存在或設定為 `True`，則載入中的每個關係檔案中都必須存在一個 `:ID` 欄。 當 `userProvidedEdgeIds` 存在且設定為 `False` 時，載入中的關係檔案**不得**包含 `:ID` 欄。相反地，Neptune 載入器會自動為每個關係產生一個 ID。 明確提供關係 ID 很有用，如此一來，載入器就可以在 CSV 資料中的錯誤完成修正之後繼續載入，而不必重新載入任何已載入的關係。如果尚未明確指派關係 ID，則載入器無法繼續失敗的載入 (如果任何關係檔案必須更正的話)，反而必須重新載入所有關係。 **回應** + **payload** – *必要：*它是金鑰值對的對應陣列，其中：     每個金鑰都是字串，類型為：`string` (UTF-8 編碼的字串)。     每個值都是字串，類型為：`string` (UTF-8 編碼的字串)。 包含 `loadId` 名稱值對，其會提供載入操作的識別符。 + **status** – *必要：*字串，類型為：`string` (UTF-8 編碼的字串)。 指示載入工作狀態的傳回碼。 **錯誤** + [BadRequestException](data-api-dp-errors.md#BadRequestException) + [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException) + [BulkLoadIdNotFoundException](data-api-dp-errors.md#BulkLoadIdNotFoundException) + [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException) + [LoadUrlAccessDeniedException](data-api-dp-errors.md#LoadUrlAccessDeniedException) + [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException) + [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException) + [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException) + [InternalFailureException](data-api-dp-errors.md#InternalFailureException) + [S3Exception](data-api-dp-errors.md#S3Exception) + [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException) + [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException) + [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException) + [MissingParameterException](data-api-dp-errors.md#MissingParameterException) ## GetLoaderJobStatus (動作) GetLoaderJobStatus         此 API 的 AWS CLI 名稱為：`get-loader-job-status`。 取得有關所特定載入工作的狀態資訊。Neptune 會追蹤最近 1,024 個大量載入工作，並會儲存每個工作的最後 10,000 個錯誤詳細資訊。 如需詳細資訊，請參閱 [Neptune 載入器 Get-Status API](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-status.htm)。 在已啟用 IAM 身分驗證的 Neptune 叢集中調用此操作時，發出請求的 IAM 使用者或角色必須附加一個政策，在該叢集中允許 [neptune-db:GetLoaderJobStatus](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#getloaderjobstatus) IAM 動作。 **請求** + **details** (在 CLI 中:`--details`) – 布林值，類型為：`boolean` (布林值 (true 或 false))。 指示是否要包含整體狀態之外的詳細資訊的旗標 (`TRUE` 或 `FALSE`；預設值為 `FALSE`)。 + **errors** (在 CLI 中:`--errors`) – 布林值，類型為：`boolean` (布林值 (true 或 false))。 指示是否要包含發生的錯誤清單的旗標 ( `TRUE` 或`FALSE`；預設值為 `FALSE`)。 錯誤清單會分頁。`page` 和 `errorsPerPage` 參數可讓您翻閱所有錯誤頁面。 + **errorsPerPage** (在 CLI 中：`--errors-per-page`) – PositiveInteger，類型為：`integer` (帶有正負號的 32 位元整數)，至少 1 ?st?。 每一頁傳回的錯誤數目 (正整數；預設值為 `10`)。僅在 `errors` 參數設定為 `TRUE` 時才有效。 + **loadId** (在 CLI 中：`--load-id`) – *必要：*字串，類型為：`string` (UTF-8 編碼的字串)。 要取得其狀態之載入工作的載入 ID。 + **page** (在 CLI 中：`--page`) – PositiveInteger，類型為：`integer` (帶有正負號的 32 位元整數)，至少 1 ?st?。 錯誤頁號碼 (正整數；預設值為 `1`)。僅在 `errors` 參數設定為 `TRUE` 時才有效。 **回應** + **payload** – *必要：*文件，類型為：`document` (與通訊協定無關的開放內容，由類似 JSON 的資料模型表示)。 有關載入工作的狀態資訊，其配置可以如下所示： **Example** ``` { "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" : [ ] } } } ``` + **status** – *必要：*字串，類型為：`string` (UTF-8 編碼的字串)。 請求的 HTTP 回應代碼。 **錯誤** + [BadRequestException](data-api-dp-errors.md#BadRequestException) + [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException) + [BulkLoadIdNotFoundException](data-api-dp-errors.md#BulkLoadIdNotFoundException) + [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException) + [LoadUrlAccessDeniedException](data-api-dp-errors.md#LoadUrlAccessDeniedException) + [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException) + [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException) + [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException) + [InternalFailureException](data-api-dp-errors.md#InternalFailureException) + [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException) + [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException) + [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException) + [MissingParameterException](data-api-dp-errors.md#MissingParameterException) ## ListLoaderJobs (動作) ListLoaderJobs         此 API 的 AWS CLI 名稱為：`list-loader-jobs`。 為所有作用中的載入器操作擷取 `loadIds` 的清單。 在已啟用 IAM 身分驗證的 Neptune 叢集中調用此操作時，發出請求的 IAM 使用者或角色必須附加一個政策，在該叢集中允許 [neptune-db:ListLoaderJobs](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#listloaderjobs) IAM 動作。 **請求** + **includeQueuedLoads** (在 CLI 中:`--include-queued-loads`) – 布林值，類型為：`boolean` (布林值 (true 或 false))。 選用參數，在將此參數設定為 `FALSE`，請求載入 ID 清單時，此參數可以用來排除佇列中載入請求的載入 ID。預設值為 `TRUE`。 + **limit** (在 CLI 中：`--limit`) – ListLoaderJobsInputLimitInteger，類型為：`integer` (帶有正負號的 32 位元整數)，不小於 1 或大於 100 ?st?s。 要列出的載入 ID 數目。必須是大於零且不超過 `100` (預設值) 的正整數。 **回應** + **payload** – *必要：*[LoaderIdResult](#LoaderIdResult) 物件。 要求的 工作 ID 清單。 + **status** – *必要：*字串，類型為：`string` (UTF-8 編碼的字串)。 傳回工作清單請求的狀態。 **錯誤** + [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException) + [BadRequestException](data-api-dp-errors.md#BadRequestException) + [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException) + [BulkLoadIdNotFoundException](data-api-dp-errors.md#BulkLoadIdNotFoundException) + [InternalFailureException](data-api-dp-errors.md#InternalFailureException) + [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException) + [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException) + [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException) + [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException) + [LoadUrlAccessDeniedException](data-api-dp-errors.md#LoadUrlAccessDeniedException) + [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException) + [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException) ## CancelLoaderJob (動作) CancelLoaderJob         此 API 的 AWS CLI 名稱為：`cancel-loader-job`。 取消指定的載入工作。這是一個 HTTP `DELETE` 請求。如需詳細資訊，請參閱 [Neptune 載入器 Get-Status API](https://docs.aws.amazon.com/neptune/latest/userguide/load-api-reference-status.htm)。 在已啟用 IAM 身分驗證的 Neptune 叢集中調用此操作時，發出請求的 IAM 使用者或角色必須附加一個政策，在該叢集中允許 [neptune-db:CancelLoaderJob](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#cancelloaderjob) IAM 動作。 **請求** + **loadId** (在 CLI 中：`--load-id`) – *必要：*字串，類型為：`string` (UTF-8 編碼的字串)。 要刪除之載入工作的 ID。 **回應** + **status** – 字串，類型為：`string` (UTF-8 編碼的字串)。 取消狀態。 **錯誤** + [BadRequestException](data-api-dp-errors.md#BadRequestException) + [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException) + [BulkLoadIdNotFoundException](data-api-dp-errors.md#BulkLoadIdNotFoundException) + [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException) + [LoadUrlAccessDeniedException](data-api-dp-errors.md#LoadUrlAccessDeniedException) + [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException) + [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException) + [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException) + [InternalFailureException](data-api-dp-errors.md#InternalFailureException) + [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException) + [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException) + [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException) + [MissingParameterException](data-api-dp-errors.md#MissingParameterException) ## *大量載入結構：* \$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1\$1 ## LoaderIdResult (結構) LoaderIdResult 包含載入 ID 的清單。 **欄位** + **loadIds** - 這是字串，類型為：`string` (UTF-8 編碼的字串)。 載入 ID 的清單。