本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# RDF 数据的原生导出
<a name="neptune-native-export"></a>

海王星导出 API 使您能够将数据从海王星数据库导出到亚马逊 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 之前，您必须：
+ 让 Neptune 数据库集群运行 1.4.6.0 或更高版本（支持 1.4.8.0 或更高版本）`exportFilter`
+ [创建具有访问您的 S3 存储桶权限的 IAM 角色 ](#neptune-native-export-iam-s3)
+ [将 IAM 角色与您的 Neptune 集群关联 ](https://docs.amazonaws.cn/neptune/latest/userguide/bulk-load-tutorial-IAM-add-role-cluster.html)
+ [在 Neptune 集群的 VPC 中配置 S3 VPC 终端节点 ](https://docs.amazonaws.cn/neptune/latest/userguide/bulk-load-tutorial-vpc.html)

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

[我们强烈建议在没有任何 read/write 工作负载的克隆集群上运行导出操作，以避免对生产性能产生影响。](https://docs.amazonaws.cn/neptune/latest/userguide/manage-console-cloning.html)

为了获得最佳的性价比，我们建议使用 ** 16xlarg ** e 实例进行导出操作。此实例类型提供：
+ 足够的内存来处理大型数据集而不会降低性能
+ 用于并行导出处理的最佳 CPU 资源
+ 导出工作负载的最佳成本效益

## IAM 权限
<a name="neptune-native-export-iam"></a>

导出功能涉及两个独立的 IAM 角色：
+ **调用者的 IAM 角色 ** — 向导出 API 终端节点发送请求的 IAM 委托人（用户或角色）。此角色需要 Neptune 数据访问权限。
+ **S3 访问 IAM 角色 ** — Neptune 在将导出的数据写入亚马逊 S3 时所扮演的角色。您在导出请求的`iamRoleArn`参数中传递此角色的 ARN，它必须与您的 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.amazonaws.cn/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>

要导出数据，您需要向`https://your-neptune-endpoint:port/export`终端节点发送 HTTP 请求。

## 导出请求语法
<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 格式导出数据

**iam RoleArn**（字符串）  
必需。海王星为访问 S3 存储桶而承担的 IAM 角色的亚马逊资源名称 (ARN)。

**区域**（字符串）  
必需。S3 存储桶的。 Amazon Web Services 区域 必须与您的 Neptune 集群位于同一区域。

**压缩**（字符串）  
可选。导出文件的压缩格式。有效值：  
+ `gz`-以 .gz 格式压缩文件

**kms KeyIdentifier**（字符串）  
可选。用于加密导出 Amazon KMS 数据的密钥的 ARN。

**导出过滤器**（对象）  
可选。用于有选择地导出 RDF 数据子集的过滤器。在引擎版本 1.4.8.0 及更高版本中可用。    
**命名 GraphUris**（字符串数组）  
要导出的命名图形 URI（最多 100 个）。仅导出指定图表中的数据。如果指定的图表为空，则导出成功，结果为空。无效的 URI 失败。`InvalidParameterException`

### 响应语法
<a name="neptune-native-export-response"></a>

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

**状态**（字符串）  
请求的 HTTP 状态。

**导出 ID（字符串**）  
导出任务的唯一标识符。

## 导出状态端点
<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>

**导出 ID（字符串**）  
必需。导出任务的唯一标识符。

### 响应语法
<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
    }
  }
}
```

**导出 ID（字符串**）  
导出任务的唯一标识符。

**目的地**（字符串）  
导出数据的 S3 URI。

**状态**（字符串）  
导出任务的当前状态。有效值：  
+ `EXPORT_NOT_STARTED`— 导出已排队但尚未开始
+ `EXPORT_IN_PROGRESS`— 导出当前正在运行
+ `EXPORT_COMPLETED`— 导出成功完成
+ `EXPORT_CANCELLING`— 导出已取消
+ `EXPORT_CANCELLED_BY_USER`— 用户取消了导出
+ `EXPORT_S3_ERROR`— 由于 S3 访问错误，导出失败
+ `EXPORT_FAILED`— 由于其他错误，导出失败

**状态原因**（字符串）  
有关导出状态的其他信息。

**格式**（字符串）  
导出的数据的格式。

**iam RoleArn**（字符串）  
用于 S3 访问的 IAM 角色的 ARN。

**kms KeyIdentifier**（字符串）  
用于加密的 KMS 密钥的 ARN（如果已指定）。

**导出过滤器**（对象）  
应用的导出过滤器（如果在请求中指定了过滤器）。  
+ **named GraphUris**（字符串数组）-用于过滤导出的命名图形 URI。

**导出 TaskDetails**（对象）  
有关导出任务进度的详细信息：  
+ **时间 ElapsedSeconds**（数字）-自导出开始以来经过的时间
+ **startTime**（数字）— 导出开始时的纪元时间
+ **num RecordsWritten**（数字）— 写入 S3 的记录数
+ **progressPercenty**（数字）— 导出完成的百分比

## 列出导出端点
<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"
  ]
}
```

**有效载荷**（阵列）  
所有导出任务的导出 ID 数组。

## 取消导出端点
<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>

**导出 ID（字符串**）  
必需。要取消的导出任务的唯一标识符。

### 响应语法
<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 无服务器实例或只读副本不支持本机导出。导出始终在已配置集群的写入器实例上运行。
+ **每个集群一次导出 **-一次只能在集群上激活一个导出。如果您在另一次导出过程中提交了新的导出请求，则该请求将失败。
+ **不自动恢复 **-如果引擎在导出期间重新启动，则导出将失败，必须从头开始重新启动。引擎重启后导出进度不会保留。
+ **引擎事件后的状态可用性 **-如果引擎崩溃，则无法通过状态 API 检索导出状态。
+ **写入期间的一致性 **-如果您的集群在导出期间为写入流量提供服务，则导出的数据可能会反映图表的部分或不一致的视图。为保证一致的导出，请对克隆的集群运行导出。