本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# RDF 資料的原生匯出
<a name="neptune-native-export"></a>

Neptune 匯出 API 可讓您將資料從 Neptune 資料庫匯出至 Amazon S3。您可以匯出 N-Triples 或 N-Quads 格式的 RDF 資料。

## 原生匯出的運作方式
<a name="neptune-native-export-how-it-works"></a>

原生匯出會在 Neptune 叢集的寫入器執行個體上執行，並使用分段上傳將匯出的資料寫入 Amazon S3。由於匯出使用寫入器執行個體的運算資源，我們強烈建議對複製的叢集執行匯出，以避免影響生產工作負載。如需詳細資訊，請參閱[建議](#neptune-native-export-recommendations)。

### 匯出輸送量
<a name="neptune-native-export-throughput"></a>

匯出輸送量會以大約線性的方式擴展，執行個體大小上限為 `r7i.16xlarge`。作為保守規劃估計， 預期**每個 vCPU 每秒大約 50，000 個陳述**式。

使用此公式估計匯出持續時間：

```
export_seconds = total_statements / (vCPUs × 50,000)
```

實際輸送量取決於資料集特性，包括述詞基數、陳述式複雜性和叢集大小。

## 先決條件
<a name="neptune-native-export-prerequisites"></a>

使用匯出 API 之前，您必須：
+ 擁有執行 1.4.6.0 版或更新版本 (1.4.8.0 版或更新版本以取得`exportFilter`支援） 的 Neptune 資料庫叢集
+ [建立具有存取 S3 儲存貯體許可的 IAM 角色](#neptune-native-export-iam-s3)
+ [將 IAM 角色與 Neptune 叢集建立關聯](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-IAM-add-role-cluster.html)
+ [在 Neptune 叢集的 VPC 中設定 S3 VPC 端點](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-vpc.html)

## 建議
<a name="neptune-native-export-recommendations"></a>

[我們強烈建議在沒有任何讀取/寫入工作負載的情況下，在複製的叢集上執行匯出操作，以避免影響生產效能。](https://docs.aws.amazon.com/neptune/latest/userguide/manage-console-cloning.html)

為了獲得最佳price-to-performance比，建議使用 **16xlarge** 執行個體進行匯出操作。此執行個體類型提供：
+ 有足夠的記憶體來處理大型資料集，而不會降低效能
+ 用於並行匯出處理的最佳 CPU 資源
+ 匯出工作負載的最佳成本效益

## IAM 許可
<a name="neptune-native-export-iam"></a>

匯出功能包含兩個不同的 IAM 角色：
+ **來電者的 IAM 角色** – 將請求傳送至匯出 API 端點的 IAM 主體 （使用者或角色）。此角色需要 Neptune 資料存取許可。
+ **S3 存取 IAM 角色** – Neptune 擔任的角色，可將匯出的資料寫入 Amazon S3。您可以在匯出請求的 `iamRoleArn` 參數中傳遞此角色的 ARN，而且它必須與 Neptune 叢集相關聯。

### 來電者許可 (Neptune 資料存取動作）
<a name="neptune-native-export-iam-data-access"></a>

呼叫匯出 API 的 IAM 主體在其 IAM 政策中必須具有下列 Neptune 資料存取動作：

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "AllowNeptuneExportActions",
      "Effect": "Allow",
      "Action": [
        "neptune-db:StartExportJob",
        "neptune-db:GetExportJobStatus",
        "neptune-db:ListExportJobs",
        "neptune-db:CancelExportJob"
      ],
      "Resource": "arn:aws:neptune-db:us-east-1:123456789012:{{cluster-resource-id}}/*"
    }
  ]
}
```

如需詳細資訊，請參閱[使用 IAM 資料存取政策陳述式](iam-dp-actions.md)。

### S3 存取角色許可
<a name="neptune-native-export-iam-s3"></a>

在`iamRoleArn`請求參數中傳遞的 IAM 角色必須與 Neptune 叢集相關聯，且必須授予 Neptune 寫入目標 S3 儲存貯體的許可。如需建立 IAM 角色並將其與叢集建立關聯的步驟，請參閱[建立 IAM 角色以允許 Neptune 存取 Amazon S3](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-IAM-CreateRole.html)。

**注意**  
匯出 API 需要 S3 的*寫入*許可，與只需要讀取存取權的大量載入器不同。使用以下許可政策，而不是該頁面上所述的`AmazonS3ReadOnlyAccess`受管政策。

將下列許可政策連接至 S3 存取角色：

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "AllowS3WriteForNeptuneExport",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject",
        "s3:AbortMultipartUpload",
        "s3:GetBucketPublicAccessBlock"
      ],
      "Resource": [
        "arn:aws:s3:::amzn-s3-demo-bucket",
        "arn:aws:s3:::amzn-s3-demo-bucket/*"
      ]
    }
  ]
}
```

### 選用 KMS 許可
<a name="neptune-native-export-iam-kms"></a>

如果您在匯出請求`kmsKeyIdentifier`中指定 ，請將下列許可新增至 S3 存取角色：

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Sid": "AllowKMSForNeptuneExport",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt",
        "kms:Encrypt",
        "kms:GenerateDataKey"
      ],
      "Resource": "arn:aws:kms:us-east-1:123456789012:key/{{key-id}}"
    }
  ]
}
```

## 匯出端點
<a name="neptune-native-export-endpoint"></a>

若要匯出資料，請將 HTTP 請求傳送至`https://your-neptune-endpoint:port/export`端點。

## 匯出請求語法
<a name="neptune-native-export-request"></a>

```
POST https://your-neptune-endpoint:port/export
```

### 請求標頭
<a name="neptune-native-export-request-headers"></a>
+ `Content-Type: application/json`

### 請求內文
<a name="neptune-native-export-request-body"></a>

```
{
  "destination": "string",
  "format": "string",
  "iamRoleArn": "string",
  "region": "string",
  "compression": "string",
  "kmsKeyIdentifier": "string",
  "exportFilter": {
    "namedGraphUris": ["string"]
  }
}
```

### 請求參數
<a name="neptune-native-export-request-params"></a>

**目的地** （字串）  
必要. 將存放匯出資料的 S3 URI。格式必須為 `s3://bucket-name/optional-prefix/`。

**格式** （字串）  
必要. 匯出資料的格式。有效值：  
+ `ntriples` – 以 N-Triples 格式匯出資料
+ `nquads` – 以 N-Quads 格式匯出資料

**iamRoleArn** （字串）  
必要. Neptune 擔任以存取 S3 儲存貯體之 IAM 角色的 Amazon Resource Name (ARN)。

**region** （字串）  
必要. S3 儲存貯體 AWS 區域 的 。必須與 Neptune 叢集的區域相同。

**壓縮** （字串）  
選用。匯出檔案的壓縮格式。有效值：  
+ `gz` - 以 .gz 格式壓縮檔案

**kmsKeyIdentifier** （字串）  
選用。用於加密匯出資料的 AWS KMS 金鑰 ARN。

**exportFilter** （物件）  
選用。篩選以選擇性地匯出 RDF 資料的子集。適用於引擎 1.4.8.0 版及更新版本。    
**namedGraphUris** （字串陣列）  
要匯出的具名圖形 URIs（上限為 100)。只會匯出指定圖形中的資料。如果指定的圖形是空的，則匯出會以空的結果成功。無效的 URIs會失敗並顯示 `InvalidParameterException`。

### 回應語法
<a name="neptune-native-export-response"></a>

```
{
  "status": "string",
  "payload": {
    "exportId": "string"
  }
}
```

**狀態** （字串）  
請求的 HTTP 狀態。

**exportId** （字串）  
匯出任務的唯一識別符。

## 匯出狀態端點
<a name="neptune-native-export-status"></a>

若要檢查匯出任務的狀態，您可以使用匯出 ID 將 HTTP GET 請求傳送至匯出端點。

```
GET https://your-neptune-endpoint:port/export?exportId=export-id
```

### 請求參數
<a name="neptune-native-export-status-params"></a>

**exportId** （字串）  
必要. 匯出任務的唯一識別符。

### 回應語法
<a name="neptune-native-export-status-response"></a>

```
{
  "status": "string",
  "payload": {
    "exportId": "string",
    "destination": "string",
    "status": "string",
    "statusReason": "string",
    "format": "string",
    "iamRoleArn": "string",
    "kmsKeyIdentifier": "string",
    "exportFilter": {
      "namedGraphUris": ["string"]
    },
    "exportTaskDetails": {
      "timeElapsedSeconds": number,
      "startTime": number,
      "numRecordsWritten": number,
      "progressPercentage": number
    }
  }
}
```

**exportId** （字串）  
匯出任務的唯一識別符。

**目的地** （字串）  
匯出資料的 S3 URI。

**狀態** （字串）  
匯出任務的目前狀態。有效值：  
+ `EXPORT_NOT_STARTED` – 匯出已排入佇列，但未啟動
+ `EXPORT_IN_PROGRESS` – 匯出目前正在執行
+ `EXPORT_COMPLETED` – 匯出成功完成
+ `EXPORT_CANCELLING` – 正在取消匯出
+ `EXPORT_CANCELLED_BY_USER` – 使用者已取消匯出
+ `EXPORT_S3_ERROR` – 由於 S3 存取錯誤導致匯出失敗
+ `EXPORT_FAILED` – 匯出因其他錯誤而失敗

**statusReason** （字串）  
有關匯出狀態的其他資訊。

**格式** （字串）  
匯出資料的格式。

**iamRoleArn** （字串）  
用於 S3 存取之 IAM 角色的 ARN。

**kmsKeyIdentifier** （字串）  
用於加密的 KMS 金鑰 ARN，如果指定的話。

**exportFilter** （物件）  
如果在請求中指定匯出篩選條件，則套用該匯出篩選條件。  
+ **namedGraphUris** （字串陣列） – 用於篩選匯出的具名圖形 URIs。

**exportTaskDetails** （物件）  
匯出任務進度的詳細資訊：  
+ **timeElapsedSeconds** (number) – 匯出開始後經過的時間
+ **startTime** (number) – 匯出開始時的 Epoch 時間
+ **numRecordsWritten** （數字） – 寫入 S3 的記錄數目
+ **progressPercentage** (number) – 已完成匯出的百分比

## 列出匯出端點
<a name="neptune-native-export-list"></a>

若要列出所有匯出任務，請將 HTTP GET 請求傳送至匯出端點。

```
GET https://your-neptune-endpoint:port/export
```

### 回應語法
<a name="neptune-native-export-list-response"></a>

```
{
  "status": "string",
  "payload": [
    "string"
  ]
}
```

**承載** （陣列）  
所有匯出任務IDs 陣列。

## 取消匯出端點
<a name="neptune-native-export-cancel"></a>

若要取消匯出任務，您可以使用匯出 ID 將 HTTP DELETE 請求傳送至匯出端點。

```
DELETE https://your-neptune-endpoint:port/export?exportId=export-id
```

### 請求參數
<a name="neptune-native-export-cancel-params"></a>

**exportId** （字串）  
必要. 要取消之匯出任務的唯一識別符。

### 回應語法
<a name="neptune-native-export-cancel-response"></a>

```
{
  "status": "string",
  "payload": {
    "message": "string"
  }
}
```

## 匯出輸出格式
<a name="neptune-native-export-output"></a>

### S3 目錄結構
<a name="neptune-native-export-output-structure"></a>

匯出的資料會在 S3 儲存貯體中組織，如下所示：

```
s3://your-bucket/export-id/
├── data/
│   ├── part-00000.nt
│   ├── part-00001.nt
│   └── ...
└── export_status.json
```

**資料/**目錄  
包含指定格式的匯出圖形資料檔案。

**export\_status.json** 檔案  
包含有關匯出操作的中繼資料。

## 錯誤回應
<a name="neptune-native-export-errors"></a>

### 常見錯誤代碼
<a name="neptune-native-export-errors-codes"></a>

**BadRequestException**  
請求包含無效的參數或匯出已在進行中。

**AccessDeniedException**  
IAM 角色缺少 S3 或 KMS 存取的必要許可。

### 錯誤回應範例
<a name="neptune-native-export-errors-example"></a>

```
{
  "code": "BadRequestException",
  "requestId": "request-id", 
  "message": "Export already in progress with ID 'existing-id'. Please wait or cancel it first.",
  "detailedMessage": "Detailed error description"
}
```

## 範例
<a name="neptune-native-export-examples"></a>

### 開始匯出
<a name="neptune-native-export-examples-start"></a>

```
curl -X POST https://your-cluster-endpoint:8182/export \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "s3://my-bucket/exports/",
    "format": "ntriples", 
    "iamRoleArn": "arn:aws:iam::123456789012:role/neptune-export-role",
    "region": "us-west-2"
  }'
```

### 啟動篩選的匯出 （具名圖形）
<a name="neptune-native-export-examples-filtered"></a>

```
curl -X POST https://your-cluster-endpoint:8182/export \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "s3://my-bucket/exports/",
    "format": "nquads",
    "iamRoleArn": "arn:aws:iam::123456789012:role/neptune-export-role",
    "region": "us-west-2",
    "exportFilter": {
      "namedGraphUris": [
        "http://example.com/graph1",
        "http://example.com/graph2"
      ]
    }
  }'
```

### 檢查匯出狀態
<a name="neptune-native-export-examples-status"></a>

```
curl -X GET "https://your-cluster-endpoint:8182/export?exportId=<id>"
```

### 取消匯出
<a name="neptune-native-export-examples-cancel"></a>

```
curl -X DELETE "https://your-cluster-endpoint:8182/export?exportId=<id>"
```

## 限制
<a name="neptune-native-export-limitations"></a>

原生匯出具有下列限制：
+ **執行個體支援** – Neptune Serverless 執行個體或僅供讀取複本不支援原生匯出。匯出一律會在佈建叢集的寫入器執行個體上執行。
+ **每個叢集一個匯出** – 一次只能有一個匯出在叢集上作用中。如果您在另一個匯出進行時提交新的匯出請求，請求會失敗。
+ **無自動恢復** – 如果引擎在匯出期間重新啟動，匯出會失敗，而且必須從頭開始重新啟動。引擎重新啟動時不會保留匯出進度。
+ **引擎事件後的狀態可用性** – 如果引擎當機，您無法透過狀態 API 擷取匯出狀態。
+ **寫入期間的一致性** – 如果您的叢集在匯出期間為寫入流量提供服務，匯出的資料可能會反映圖形的部分檢視或不一致的檢視。若要保證一致的匯出，請針對複製的叢集執行匯出。