本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Neptune 載入器命令 將資料從 Amazon S3 儲存貯體載入至 Neptune 資料庫執行個體。 若要載入資料，您必須將 HTTP `POST` 請求傳送至 `https://your-neptune-endpoint:port/loader` 端點。您可以用 `POST` 本文或以 URL 編碼參數來傳送 `loader` 請求的參數。 **重要** MIME 類型必須是 `application/json`。 Amazon S3 儲存貯體必須與叢集位於相同的 AWS 區域。 **注意** 您可以從 Amazon S3 載入加密的資料 (如果它是使用 Amazon S3 `SSE-S3` 模式加密的)。在這種情況下，Neptune 可以模擬您的憑證，並代表您發出 `s3:getObject` 呼叫。 您也可以從 Amazon S3 載入使用 `SSE-KMS` 模式加密的加密資料，只要您的 IAM 角色包含存取 AWS KMS的必要許可。如果沒有適當的 AWS KMS 許可，大量載入操作會失敗並傳回`LOAD_FAILED`回應。 Neptune 目前不支援載入使用 `SSE-C` 模式加密的 Amazon S3 資料。 您不必等待一個載入工作完成，然後再啟動另一個工作。Neptune 最多可以一次將 64 個工作排入佇列，前提是其 `queueRequest` 參數全都設為 `"TRUE"`。工作的佇列順序將為先進先出 (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 呼叫中的 [prefix](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html#API_ListObjects_RequestParameters) 參數。它會識別所指定 Amazon S3 儲存貯體中其名稱以該字首開頭的所有物件。這可以是單一檔案或資料夾，也可以是多個檔案和/或資料夾。 一個或多個指定的資料夾可以包含多個頂點檔案和多個邊緣檔案。 例如，如果您在名為 的 Amazon S3 儲存貯體中具有下列資料夾結構和檔案`bucket-name`： ``` 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 Resource Name (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 儲存貯體位於不同的 AWS 帳戶中，您也可以鏈結多個 IAM 角色。在此情況下，`iamRoleArn` 會包含逗號分隔的角色 ARN 清單，如 [在 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` – 使用的執行緒數目是可用 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`** – 包含額外剖析器組態值的選用物件。也可選用每個子參數： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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"`。工作的佇列順序將為先進先出 (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. 使用兩任務其 `dependencies` 欄位中的載入 ID 提交 `load-job-C`： ``` "dependencies" : ["job_A_load_id", "job_B_load_id"] ``` 由於 `dependencies` 參數的關係，大量載入器在 `Job-A` 和 `Job-B` 順利完成之前，將不會啟動 `Job-C`。如果其中任何一個失敗，則不執行 Job-C，且其狀態將設為 `LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED`。 您可以使用這種方式設定多個相依性層級，如此一來，一項任務若失敗，將導致直間接仰賴該任務的所有請求遭取消。 + **`userProvidedEdgeIds`** – 只有在載入包含關係 ID 的 OpenCypher 資料時，才需要這個參數。在載入資料中明確提供 OpenCypher 關係 ID 時，必須包含它並設定為 `True` (建議使用)。 如果 `userProvidedEdgeIds` 不存在或設定為 `True`，則載入中的每個關係檔案中都必須存在一個 `:ID` 欄。 當 `userProvidedEdgeIds` 存在且設定為 `False` 時，載入中的關係檔案**不得**包含 `:ID` 欄。相反地，Neptune 載入器會自動為每個關係產生一個 ID。 明確提供關係 ID 很有用，如此一來，載入器就可以在 CSV 資料中的錯誤完成修正之後繼續載入，而不必重新載入任何已載入的關係。如果尚未明確指派關係 ID，則載入器無法繼續失敗的載入 (如果任何關係檔案必須更正的話)，反而必須重新載入所有關係。 + `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`。 + 不支援 `updateSingleCardinalityProperties` 參數用於 openCypher 載入，因為所有 openCypher 屬性都有單一基數。OpenCypher 載入格式不支援陣列，而且如果 ID 值出現多次，則系統會將其視為重複或插入錯誤 (請參閱下文)。 + Neptune 載入器會處理它在 OpenCypher 資料中遇到的重複項目，如下所示： + 如果載入器遇到多個具有相同節點 ID 的資料列，則會使用下列規則合併它們： + 資料列行中的所有標籤現在會新增至節點。 + 對於每個屬性，只會載入其中一個屬性值。選取要載入哪一個是不具確定性的。 + 如果載入器遇到多個具有相同關係 ID 的資料列，則只會載入其中一個資料列。選取要載入哪一個是不具確定性的。 + 如果載入器遇到具有現有節點或關係 ID 的載入資料，則它永遠不會更新資料庫中現有節點或關係的屬性值。不過，它確實會載入現有節點或關係中不存在的節點標籤和屬性。 + 雖然您不必將 ID 指派給關係，但是這樣做通常是個好主意 (請參閱上面的 `userProvidedEdgeIds` 參數)。若沒有明確的關係 ID，載入器必須在關係檔案中發生錯誤時重新載入所有關係，而不是從失敗處繼續載入。 此外，如果載入資料未包含明確的關係 ID，則載入器無法偵測重複的關係。 以下是 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` 程式碼。