Neptune 載入器命令

將資料從 Amazon S3 儲存貯體載入至 Neptune 資料庫執行個體。

若要載入資料，您必須將要HTTPPOST求傳送至https://your-neptune-endpoint:port/loader端點。loader請求的參數可以在POST主體中發送，也可以作為URL編碼參數發送。

重要

類MIME型必須是application/json。

S3 儲存貯體必須與叢集位於相同的 AWS 區域。

注意

您可以從 Amazon S3 載入加密的資料 (如果它是使用 Amazon S3 SSE-S3 模式加密的)。在這種情況下，Neptune 可以模擬您的憑證，並代表您發出 s3:getObject 呼叫。

只要您的IAM角色包含必要的存取權限，您也可以從使用該SSE-KMS模式加密的 Amazon S3 載入加密的資料 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— 一個 Amazon S3URI.

URI此SOURCE參數接受可識別單一檔案、多個檔案、資料夾或多個資料夾的 Amazon S3。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 大量載入器擷取資料。
允許的值
- csv對於小精靈CSV數據格式。
- opencypher用於資openCypher CSV料格式。
- ntriples對於 N-三元RDF數據格式。
- nquads用於 N-四邊形RDF資料格式。
- rdfxml表示 RDF\ XML RDF 資料格式。
- turtle用於「龜」RDF 資料格式。
iamRoleArn— Neptune 資料庫執行個體假定用於存取 S3 儲存貯體之IAM角色的 Amazon 資源名稱 (ARN)。如需建立可存取 Amazon S3 的角色，然後將其與 Neptune 叢集建立關聯的相關資訊，請參閱先決條件：IAM角色和 Amazon S3 存取。

從引擎版本 1.2.1.0.R3 開始，如果 Neptune 資料庫執行個體和 Amazon S3 儲存貯體位於不同的帳戶中，您也可以鏈結多個IAM角色。 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-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-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和烏龜格式的基礎URI。預設值為 http://aws.amazon.com/neptune/default。

名稱	範例值	描述
`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和烏龜格式的基礎URI。預設值為 `http://aws.amazon.com/neptune/default`。
`allowEmptyStrings`	`true`	Gemlin 使用者需要能夠在載入CSV資料時傳遞空字串值 (「」) 作為節點和邊緣屬性。如果 `allowEmptyStrings` 設定為 `false` (預設值)，則這類空字串會被視為 null 而不會將其載入。如果 `allowEmptyStrings` 設定為 `true`，載入器會將空字串視為有效的屬性值，並相應地載入它們。

allowEmptyStrings

true

Gemlin 使用者需要能夠在載入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. 使用兩任務其 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— 只有在載入包含關係的 openCypher 資料時，才需要此參數IDs。當在負載資料中明確提供 openCypher 關係TrueIDs時，它必須包含並設定為 (建議使用)。

如果 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 和私密存取金鑰)。

載入 openCypher 資料的特殊考量

以CSV格式載入 openCypher 資料時，必須將 format 參數設定為opencypher。
openCypher 負載不支援此updateSingleCardinalityProperties參數，因為所有 openCypher 性質都具有單一基數。 openCypher 載入格式不支援陣列，如果 ID 值出現一次以上，則會將其視為重複或插入錯誤 (請參閱下文)。
Neptune 加載程序處理它在openCypher數據中遇到的重複項，如下所示：
- 如果載入器遇到多個具有相同節點 ID 的資料列，則會使用下列規則合併它們：
  - 資料列行中的所有標籤現在會新增至節點。
  - 對於每個屬性，只會載入其中一個屬性值。選取要載入哪一個是不具確定性的。
- 如果載入器遇到多個具有相同關係 ID 的資料列，則只會載入其中一個資料列。選取要載入哪一個是不具確定性的。
- 如果載入器遇到具有現有節點或關係 ID 的載入資料，則它永遠不會更新資料庫中現有節點或關係的屬性值。不過，它確實會載入現有節點或關係中不存在的節點標籤和屬性。
雖然您不必分配IDs給關係，但它通常是一個好主意（請參閱上面的userProvidedEdgeIds參數）。如果沒有明確的關係IDs，載入器必須在關聯檔案中發生錯誤時重新載入所有關係，而不是從失敗處繼續載入。

此外，如果載入資料不包含明確的關聯性IDs，則載入器無法偵測重複的關係。

下面是一個 openCypher load 命令的一個例子：



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 程式碼。

Neptune 載入器錯誤

發生錯誤時，會在回應中BODY傳回JSON物件。message 物件包含此錯誤的描述。

錯誤類別

Error 400— 語法錯誤會HTTP400傳回錯誤的要求錯誤。描述錯誤的訊息。
Error 500— 無法處理的有效要求會傳回HTTP500內部伺服器錯誤。描述錯誤的訊息。

以下是來自載入器的可能錯誤訊息及錯誤的描述。

載入器錯誤訊息

Couldn't find the AWS credential for iam_role_arnHTTP

找不到登入資料。對照IAM控制台或 AWS CLI 輸出驗證提供的認證。請確定您已iamRoleArn將中指定的IAM角色新增至叢集。
S3 bucket not found for sourceHTTP

S3 儲存貯體不存在。檢查儲存貯體的名稱。
The source source-uri does not exist/not reachableHTTP

在 S3 儲存貯體找不到相符的檔案。
Unable to connect to S3 endpoint. Provided source = source-uri and region = aws-region(HTTP500)

無法連線至 Amazon S3。區域必須符合叢集區域。確定您有VPC端點。如需有關建立VPC端點的資訊，請參閱創建一個 Amazon S3 VPC 端點。
Bucket is not in provided Region (aws-region)HTTP

儲存貯體必須與 Neptune 資料庫執行個體位於相同的 AWS 區域。
Unable to perform S3 list operationHTTP

提供的IAM使用者或角色沒有值區或資料夾的List權限。檢查值區上的政策或存取控制清單 (ACL)。
Start new load operation not permitted on a read replica instanceHTTP

載入是一種寫入操作。在讀取/寫入叢集端點上重試載入。
Failed to start load because of unknown error from S3(HTTP500)

Amazon S3 傳回未知的錯誤。請聯絡 AWS Support。
Invalid S3 access key(HTTP四百)

存取金鑰無效。檢查提供的登入資料。
Invalid S3 secret key(HTTP四百)

私密金鑰無效。檢查提供的登入資料。
Max concurrent load limit breached(HTTP四百)

如不使用 "queueRequest" : "TRUE" 提交載入請求，且某載入任務正在執行中，則此請求將失敗，並顯示此錯誤。
Failed to start new load for the source "source name". Max load task queue size limit breached. Limit is 64(HTTP四百)

Neptune 最多支援一次將 64 個載入器工作排入佇列。若在佇列已包含 64 個任務時，再繼續提交其他載入請求到該佇列，則請求會失敗並顯示此訊息。

Neptune 載入器範例

範例請求

以下是通過HTTPPOST使用curl命令發送的請求。它加載 Neptune CSV 格式的文件。如需詳細資訊，請參閱Gremlin 載入資料格式。


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"
    }'

範例回應


{
    "status" : "200 OK",
    "payload" : {
        "loadId" : "ef478d76-d9da-4d94-8ff1-08d9d4863aa5"
    }
}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

載入器參考

取得狀態 API