本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Neptune 載入器 Get-Status API 取得 `loader` 工作的狀態。若要取得載入狀態，您必須將 HTTP `GET` 請求傳送至 `https://your-neptune-endpoint:port/loader` 端點。若要取得特定載入請求的狀態，您必須包含 `loadId` 做為 URL 參數，或將 `loadId` 連接到 URL 路徑。 Neptune 只會追蹤最近 1,024 個大量載入任務，並且只會存放每個任務的最後 10,000 個錯誤詳細資訊。如需載入器在發生錯誤時傳回的錯誤和饋送訊息清單，請參閱 [Neptune 載入器的錯誤和饋送訊息](loader-message.md)。 **Contents** + [Neptune 載入器 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) + [載入 ID 的請求範例](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 載入器 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 載入器 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`，會傳回載入 ID 的清單。 + **`details`** – 除了整體狀態之外也包含詳細資訊。 *允許的值*：`TRUE`、`FALSE`。 *預設值*：`FALSE`。 + **`errors`** – 包括錯誤清單。 *允許的值*：`TRUE`、`FALSE`。 *預設值*：`FALSE`。錯誤清單會分頁。`page` 和 `errorsPerPage` 參數可讓您翻閱所有錯誤頁面。 + **`page`** – 錯誤頁面號碼。僅適用於 `errors` 參數設為 `TRUE` 時。 *允許的值*：正整數。 *預設值*：1。 + **`errorsPerPage`** – 每個頁面的錯誤數。僅適用於 `errors` 參數設為 `TRUE` 時。 *允許的值*：正整數。 *預設值*：10。 + **`limit`** – 要列出的載入 ID 數目。僅適用於藉由傳送 `GET` 請求且未指定 `loadId` 以請求載入 ID 清單時。 *允許值*：1 到 100 的正整數。 *預設值*：100。 + **`includeQueuedLoads`** – 請求載入 ID 清單時，選用參數可用來排除佇列中載入請求的載入 ID。依預設，所有狀態為 `LOAD_IN_QUEUE` 的載入任務的載入 ID 都包含在這類清單中。它們會出現在其他任務的載入 ID 之前，依加入佇列的時間，從最近到最早進行排序。 *允許的值*：`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`** – 此載入或饋送的執行數量。它會在載入重新啟動時遞增。 *類型：**unsigned long*。 + **`retryNumber`** – 此載入或饋送的重試次數。它會在載入器自動重試饋送或載入時遞增。 *類型：**unsigned long*。 + **`status`** – 載入或饋送傳回的狀態。`LOAD_COMPLETED` 表示成功載入，沒有發生問題。如需其他 load-status 訊息的清單，請參閱 [Neptune 載入器的錯誤和饋送訊息](loader-message.md)。 *類型：**字串*。 + **`totalTimeSpent`** – 載入或饋送時用於剖析及插入資料的時間 (以秒為單位)。這不包含擷取原始檔案清單所花費的時間。 *類型：**unsigned long*。 + **`totalRecords`** – 已載入或嘗試載入的記錄總數。 *類型：**unsigned long*。請注意，從 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`** – 遇到的重複記錄數目。 *類型：**unsigned long*。與 `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 值相同，不是在另一個資料列中，就是屬於現有節點。請參閱 [載入 openCypher 資料的特殊考量](load-api-reference-load.md#load-api-reference-load-parameters-opencypher)。 + **`parsingErrors`** – 遇到的剖析錯誤數目。 *類型：**unsigned long*。 + **`datatypeMismatchErrors`** – 資料類型與給定資料不符的記錄數目。 *類型：**unsigned long*。 + **`insertErrors`** – 由於錯誤而無法插入的記錄數目。 *類型：**unsigned long*。 ## Neptune 載入器 Get-Status `errors` 回應物件錯誤分為以下類別： + **`Error 400`** – 無效的 `loadId` 會傳回 HTTP `400` 錯誤的請求錯誤。描述錯誤的訊息。 + **`Error 500`** – 無法處理的有效請求會傳回 HTTP `500` 內部伺服器錯誤。描述錯誤的訊息。如需載入器在發生錯誤時傳回的錯誤和饋送訊息清單，請參閱 [Neptune 載入器的錯誤和饋送訊息](loader-message.md)。發生錯誤時，回應的 `BODY` 中會傳回 JSON `errors` 物件，具有下列欄位： + **`startIndex`** – 第一個包含的錯誤的索引。 *類型：**unsigned long*。 + **`endIndex`** – 最後一個包含的錯誤的索引。 *類型：**unsigned long*。 + **`loadId`** – 載入的 ID。您可以使用此 ID 並將 `errors` 參數設為 `TRUE` 以列印載入的錯誤。 *類型：**字串*。 + **`errorLogs`** – 錯誤清單。 *類型：**清單*。 ## Neptune 載入器 Get-Status `errorLogs` 回應物件載入器 Get-Status 回應中 `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`** – 描述錯誤的訊息。這可以是與錯誤代碼相關聯的一般訊息，或包含詳細資訊的特定訊息，例如關於遺失來源/目標頂點或關於剖析錯誤。 + **`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 } } } ``` ## 載入 ID 的請求範例以下是使用 `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 載入器 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"`，這時載入器會略過其已成功載入的檔案，並恢復其在中斷發生時尚未載入的檔案載入。