本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 从 Neptune 数据库集群中导出数据 从 Neptune 数据库集群导出数据有几种好方法： + 对于少量数据，只需使用一个或多个查询的结果即可。 + 对于 RDF 数据，[图形存储协议 (GSP)](sparql-graph-store-protocol.md) 可以简化导出过程。例如： ``` curl --request GET \ 'https://your-neptune-endpoint:port/sparql/gsp/?graph=http://www.example.com/named/graph' ``` + 还有一个强大而灵活的开源工具，用于导出 Neptune 数据，即 [https://github.com/aws/neptune-export](https://github.com/aws/neptune-export)。以下各节介绍了此工具的特征以及如何使用它。 **Topics** + [ # 使用 `neptune-export` ](neptune-export.md) + [ # 使用 Neptune-Export 服务导出 Neptune 数据 ](export-service.md) + [ # 使用 `neptune-export` 命令行工具从 Neptune 导出数据 ](export-utility.md) + [ # 由 Neptune-Export 和 `neptune-export` 导出的文件 ](exported-files.md) + [ # 用于控制 Neptune 导出过程的参数 ](export-parameters.md) + [ # 对 Neptune 导出过程进行故障排除 ](export-troubleshooting.md) + [ # 将 Gremlin 查询结果导出到 Amazon S3 ](exporting-gremlin.md) # 使用 `neptune-export` 您可以通过两种不同的方式使用开源 [https://github.com/aws/neptune-export](https://github.com/aws/neptune-export) 工具： + **作为 [Neptune-Export 服务](export-service.md)**。  使用 Neptune-Export 服务从 Neptune 导出数据时，您可以通过 REST API 触发和监控导出任务。 + **作为 [`neptune-export` Java 命令行实用程序](export-utility.md)**。  要使用此命令行工具导出 Neptune 数据，您必须在可以访问 Neptune 数据库集群的环境中运行它。 Neptune-Export 服务和 `neptune-export` 命令行工具都将数据发布到 Amazon Simple Storage Service (Amazon S3)，数据是使用 Amazon S3 服务器端加密 (`SSE-S3`) 来加密的。 **注意** 最佳做法是在所有 Amazon S3 桶上[启用访问日志记录](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enable-server-access-logging.html)，这样您就可以审计对这些桶的所有访问。 如果您尝试从 Neptune 数据库集群导出数据，而该集群的数据在导出过程中发生变化，则无法保证导出数据的一致性。也就是说，如果您的集群在导出任务进行期间正在为写入流量提供服务，则导出的数据可能存在不一致之处。无论您是从集群中的主实例还是从一个或多个只读副本进行导出，都是如此。 为确保导出的数据一致，最好从[数据库集群的克隆](manage-console-cloning.md)中导出。这既为导出工具提供了数据的静态版本，又可确保导出任务不会减慢原始数据库集群中的查询速度。 为了简化此操作，您可以在触发导出任务时表明要克隆源数据库集群。如果这样做，则导出过程会自动创建克隆，将其用于导出，然后在导出完成后将其删除。 # 使用 Neptune-Export 服务导出 Neptune 数据 您可以使用以下步骤，通过 Neptune-Export 服务将数据从 Neptune 数据库集群导出到 Amazon S3： ## 安装 Neptune-Export 服务 使用 AWS CloudFormation 模板创建堆栈： **安装 Neptune-Export 服务** 1. 通过选择下表中的**启动堆栈**按钮之一，在 CloudFormation 控制台中启动 CloudFormation 堆栈： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/export-service.html) 1. 在 **Select Template** 页面上，选择 **Next**。 1. 在模板的**指定详细信息**页面上，设置以下参数： + ** `VPC`** –设置 Neptune-Export 服务的最简单方法是将其安装在与 Neptune 数据库相同的 Amazon VPC 中。如果您想将其安装在单独的 VPC 中，则可以使用 [VPC 对等连接](https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html)在 Neptune 数据库集群的 VPC 和 Neptune-Export 服务 VPC 之间建立连接。 + ** `Subnet1`** –Neptune-Export 服务必须安装在您 VPC 的子网中，该子网允许从该子网到互联网的出站 IPv4 HTTPS 流量。这样，Neptune-Export 服务就可以调用 [AWS Batch API](https://aws.amazon.com/premiumsupport/knowledge-center/batch-job-stuck-runnable-status/) 来创建和运行导出任务。 如果您使用 Neptune 文档中[创建 Neptune 集群](get-started-create-cluster.md)页面上的 CloudFormation 模板创建了 Neptune 集群，则可以使用该堆栈中的 `PrivateSubnet1` 和 `PrivateSubnet2` 输出来填充此参数和下一个参数。 + ** `Subnet2`** –VPC 中的第二个子网，允许从该子网到互联网的出站 IPv4 HTTPS 流量。 + **`EnableIAM`** – 将其设置为 `true` 以使用 AWS Identity and Access Management (IAM) 保护 Neptune-Endpoint API。我们建议您这样做。 如果您启用 IAM 身份验证，则必须对针对端点的所有 HTTPS 请求进行 `Sigv4` 签名。您可以使用诸如 [awscurl](https://github.com/okigan/awscurl) 之类的工具来代表您签署请求。 + **`VPCOnly`** – 将它设置为 `true` 将使导出端点成为“仅 VPC”，因此，您只能从安装了 Neptune-Export 服务的 VPC 内对其进行访问。这将 Neptune-Export API 限制为只能在该 VPC 内使用。 建议您将 `VPCOnly` 设置为 `true`。 + **`NumOfFilesULimit `** – 在 `ulimits` 容器属性中为 `nofile` 指定一个介于 10000 到 1 百万之间的值。默认值为 10000，除非您的图形包含大量唯一标签，否则我们建议保留默认值。 + **`PrivateDnsEnabled `**（布尔值）– 指示是否将私有托管区与指定的 VPC 关联。默认值为 `true`。 在启用此标志的情况下创建 VPC 端点时，所有 API Gateway 流量都将通过 VPC 端点路由，并且公有 API Gateway 端点调用将被禁用。如果将 `PrivateDnsEnabled` 设置为 `false`，则启用公有 API Gateway 端点，但无法通过私有 DNS 端点连接 Neptune 导出服务。然后，您可以使用 VPC 端点的公有 DNS 端点来调用导出服务，详见[此处](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-api-test-invoke-url.html#apigateway-private-api-public-dns)。 + **`NeptuneExportVersion`** – 指定要使用的 Neptune Export 实用程序的版本。支持 `v1.1.11` 或以上的所有版本。版本 `v2.latest` 可用于自动接收次要更新。可用版本的完整列表以及补丁说明可以在开源 [GitHub 版本](https://github.com/aws/neptune-export/releases)中找到。 1. 选择**下一步**。 1. 在**选项**页面上，选择**下一步**。 1. 在**审核**页面上，选中第一个复选框以确认 CloudFormation 将创建 IAM 资源。选中第二个复选框以确认新堆栈的 `CAPABILITY_AUTO_EXPAND`。 **注意** `CAPABILITY_AUTO_EXPAND` 明确确认在创建堆栈时将扩展宏，而无需事先审核。用户通常通过处理的模板创建更改集，以便在实际创建堆栈之前对宏所做的更改进行审核。有关更多信息，请参阅 CloudFormation [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) API。 然后选择**创建**。 ## 启用从 Neptune-Export 访问 Neptune Neptune-Export 安装完成后，更新您的 [Neptune VPC 安全组](get-started-vpc.md#security-vpc-security-group)以允许从 Neptune-Export 进行访问。创建 Neptune-Export CloudFormation 堆栈后，**输出**选项卡将包含一个 `NeptuneExportSecurityGroup` ID。更新 Neptune VPC 安全组以允许从该 Neptune 导出任务进行访问。 ## 启用从基于 VPC 的 EC2 实例访问 Neptune-Export 端点 如果您将 Neptune-Export 端点设置为仅 VPC，则只能从安装了 Neptune-Export 服务的 VPC 内对其进行访问。要允许从 VPC 中的 Amazon EC2 实例进行连接（您可以从该实例进行 Neptune-Export API 调用），请将 CloudFormation 堆栈创建的 `NeptuneExportSecurityGroup` 附加到该 Amazon EC2 示例。 # 使用 Neptune-Export API 运行 Neptune-Export 任务 CloudFormation 堆栈的**输出**选项卡还包括 `NeptuneExportApiUri`。每当您向 Neptune-Export 端点发送请求时，请使用此 URI。 **运行导出任务** + 请确保运行导出的用户或角色已被授予 `execute-api:Invoke` 权限。 + 如果您在安装 Neptune-Export 时在 CloudFormation 堆栈中将 `EnableIAM` 参数设置为 `true`，则需要对针对 Neptune-Export API 的所有请求进行 `Sigv4` 签名。我们建议使用 [awscurl](https://github.com/okigan/awscurl) 向 API 发出请求。此处的所有示例都假设已启用 IAM 身份验证。 + 如果您在安装 Neptune-Export 时在 CloudFormation 堆栈中将 `VPCOnly` 参数设置为 `true`，则必须从 VPC 内调用 Neptune-Export API，通常是从位于 VPC 中的 Amazon EC2 实例调用。 要开始导出数据，请使用 `command` 和 `outputS3Path` 请求参数以及 `endpoint` 导出参数向 `NeptuneExportApiUri` 端点发送请求。 以下是从 Neptune 导出属性图数据并将其发布到 Amazon S3 的请求示例： ``` curl \ (your NeptuneExportApiUri) \ -X POST \ -H 'Content-Type: application/json' \ -d '{ "command": "export-pg", "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint": "(your Neptune endpoint DNS name)" } }' ``` 同样，以下是将 RDF 数据从 Neptune 导出到 Amazon S3 的请求示例： ``` curl \ (your NeptuneExportApiUri) \ -X POST \ -H 'Content-Type: application/json' \ -d '{ "command": "export-rdf", "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint": "(your Neptune endpoint DNS name)" } }' ``` 如果您省略 `command` 请求参数，则默认情况下，Neptune-Export 会尝试从 Neptune 导出属性图数据。 如果前面的命令成功运行，则输出将如下所示： ``` { "jobName": "neptune-export-abc12345-1589808577790", "jobId": "c86258f7-a9c9-4f8c-8f4c-bbfe76d51c8f" } ``` ## 监控您刚刚启动的导出任务 要监控正在运行的任务，请将其 jobID 附加到您的 `NeptuneExportApiUri` 之后，如下所示： ``` curl \ (your NeptuneExportApiUri)/(the job ID) ``` 如果服务尚未启动导出任务，则响应将如下所示： ``` { "jobId": "c86258f7-a9c9-4f8c-8f4c-bbfe76d51c8f", "status": "pending" } ``` 当您在导出任务开始后重复该命令时，响应将如下所示： ``` { "jobId": "c86258f7-a9c9-4f8c-8f4c-bbfe76d51c8f", "status": "running", "logs": "https://us-east-1.console.aws.amazon.com/cloudwatch/home?..." } ``` 如果您使用状态调用提供的 URI 在 CloudWatch Logs 中打开日志，则可以详细监控导出的进度： ![\[CloudWatch Logs 显示内容的屏幕截图。\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/images/export-job-monitor.png) ## 取消正在运行的导出任务 **使用 AWS 管理控制台 取消正在运行的导出任务** 1. 打开AWS Batch控制台，地址：[https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/)。 1. 选择 **Jobs (作业)**。 1. 根据要取消的正在运行的任务的 `jobID`，找到该任务。 1. 选择**取消任务**。 **使用 Neptune 导出 API 取消正在运行的导出任务**： 向附有 `jobID` 的 `NeptuneExportApiUri` 发送 `HTTP DELETE` 请求，如下所示： ``` curl -X DELETE \ (your NeptuneExportApiUri)/(the job ID) ``` # 使用 `neptune-export` 命令行工具从 Neptune 导出数据 您可以使用以下步骤，通过 `neptune-export` 命令行实用程序将数据从 Neptune 数据库集群导出到 Amazon S3： ## 使用 `neptune-export` 命令行实用程序的先决条件 **开始之前** + **拥有 JDK 的版本 8** – 您需要安装 [Java SE 开发工具包 (JDK) ](https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html)的版本 8。 + **下载 neptune-export 实用程序** – 下载并安装 [neptune-export.jar](https://s3.amazonaws.com/aws-neptune-customer-samples/neptune-export/bin/neptune-export.jar) 文件。 + **确保 `neptune-export` 可以访问您的 Neptune VPC** – 从可以访问您的 Neptune 数据库集群所在的 VPC 的位置运行 neptune-export。 例如，您可以在 Neptune VPC 内的 Amazon EC2 实例上、在与 Neptune VPC 对等的独立 VPC 中或在单独的堡垒主机上运行它。 + **确保 VPC 安全组授予对 `neptune-export` 的访问权限** – 检查连接到 Neptune VPC 的 VPC 安全组是否允许从与 `neptune-export` 环境关联的 IP 地址或安全组访问您的数据库集群。 + **设置必要的 IAM 权限** — 如果您的数据库启用了 AWS Identity and Access Management (IAM) 数据库身份验证，请确保`neptune-export`运行所依据的角色与允许连接 Neptune 的 IAM 策略相关联。有关 Neptune 策略的一般信息，请参阅[使用 IAM 策略](security-iam-access-manage.md)。 如果您想在查询请求中使用 `clusterId` 导出参数，则 `neptune-export` 运行所使用的角色需要以下 IAM 权限： + `rds:DescribeDBClusters` + `rds:DescribeDBInstances` + `rds:ListTagsForResource` 如果要从克隆的集群中导出，则 `neptune-export` 运行所使用的角色需要以下 IAM 权限： + `rds:AddTagsToResource` + `rds:DescribeDBClusters` + `rds:DescribeDBInstances` + `rds:ListTagsForResource` + `rds:DescribeDBClusterParameters` + `rds:DescribeDBParameters` + `rds:ModifyDBParameterGroup` + `rds:ModifyDBClusterParameterGroup` + `rds:RestoreDBClusterToPointInTime` + `rds:DeleteDBInstance` + `rds:DeleteDBClusterParameterGroup` + `rds:DeleteDBParameterGroup` + `rds:DeleteDBCluster` + `rds:CreateDBInstance` + `rds:CreateDBClusterParameterGroup` + `rds:CreateDBParameterGroup` 要将导出的数据发布到 Amazon S3，`neptune-export` 运行所使用的角色需要对 Amazon S3 位置具有以下 IAM 权限： + `s3:PutObject` + `s3:PutObjectTagging` + `s3:GetObject` + **设置 `SERVICE_REGION` 环境变量** - 设置 `SERVICE_REGION` 环境变量以标识数据库集群所在的区域（有关区域标识符的列表，请参阅[连接到 Neptune](iam-auth-connecting-gremlin-java.md)）。 ## 运行 `neptune-export` 实用程序以启动导出操作 使用以下命令从命令行运行 neptune-export 并启动导出操作： ``` java -jar neptune-export.jar nesvc \ --root-path (path to a local directory) \ --json (the JSON file that defines the export) ``` 该命令有两个参数： **开始导出时 neptune-export 的参数** + **`--root-path`** – 导出文件发布到 Amazon S3 之前写入的本地目录的路径。 + **`--json`** – 用于定义导出的 JSON 对象。 ## 使用命令行实用程序的 `neptune-export` 命令示例 要直接从源数据库集群导出属性图数据，请执行以下操作： ``` java -jar neptune-export.jar nesvc \ --root-path /home/ec2-user/neptune-export \ --json '{ "command": "export-pg", "outputS3Path" : "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint" : "(your neptune DB cluster endpoint)" } }' ``` 要直接从源数据库集群导出 RDF 数据，请执行以下操作： ``` java -jar neptune-export.jar nesvc \ --root-path /home/ec2-user/neptune-export \ --json '{ "command": "export-rdf", "outputS3Path" : "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint" : "(your neptune DB cluster endpoint)" } }' ``` 如果忽略 `command` 请求参数，则默认情况下，`neptune-export` 实用程序会从 Neptune 导出属性图数据。 要从数据库集群的克隆中导出，请执行以下操作： ``` java -jar neptune-export.jar nesvc \ --root-path /home/ec2-user/neptune-export \ --json '{ "command": "export-pg", "outputS3Path" : "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint" : "(your neptune DB cluster endpoint)", "cloneCluster" : true } }' ``` 要使用 IAM 身份验证从数据库集群导出，请执行以下操作： ``` java -jar neptune-export.jar nesvc \ --root-path /home/ec2-user/neptune-export \ --json '{ "command": "export-pg", "outputS3Path" : "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint" : "(your neptune DB cluster endpoint)" "useIamAuth" : true } }' ``` # 由 Neptune-Export 和 `neptune-export` 导出的文件 导出完成后，导出文件将发布到您指定的 Amazon S3 位置。将使用 Amazon S3 服务器端加密 (`SSE-S3`) 对发布到 Amazon S3 的所有文件进行加密。发布到 Amazon S3 的文件夹和文件会有所不同，具体取决于您是导出属性图还是 RDF 数据。如果您打开在其中发布文件的 Amazon S3 位置，则会看到以下内容： **导出文件在 Amazon S3 中的位置** + **`nodes/`** – 此文件夹包含逗号分隔值 (CSV) 或 JSON 格式的节点数据文件。 在 Neptune 中，节点可以有一个或多个标签。具有不同单个标签（或多个标签的不同组合）的节点会写入不同的文件，这意味着没有单个文件包含具有不同标签组合的节点的数据。如果一个节点有多个标签，则这些标签在分配给文件之前会按字母顺序排序。 + **`edges/`** – 此文件夹包含逗号分隔值 (CSV) 或 JSON 格式的边缘数据文件。 与节点文件一样，边缘数据会根据标签的组合写入不同的文件。为了进行模型训练，根据边缘的标签加上边缘的起始和结束节点的标签的组合，将边缘数据分配给不同的文件。 + **`statements/`** – 此文件夹包含 Turtle、N-Quads、N-Triples 或 JSON 格式的 **RDF** 数据文件。 + **`config.json`** – 此文件包含导出过程推断出的图形*架构*。 + **`lastEventId.json`** – 此文件包含数据库的 Neptune 流上最后一个事件的 `commitNum` 和 `opNum`。如果将 `includeLastEventId` 导出参数设置为 `true`，并且从中导出数据的数据库已启用 [Neptune 流](streams-using.md)，则导出过程仅包括此文件。 # 用于控制 Neptune 导出过程的参数 无论您使用的是 Neptune-Export 服务还是 `neptune-export` 命令行实用程序，用于控制导出的参数基本相同。它们包含传递给 Neptune-Export 端点或命令行上的 `neptune-export` 的 JSON 对象。 传递到导出过程的对象最多有五个顶级字段： ``` -d '{ "command" : "(either export-pg or export-rdf)", "outputS3Path" : "s3:/(your Amazon S3 bucket)/(path to the folder for exported data)", "jobSize" : "(for Neptune-Export service only)", "params" : { (a JSON object that contains export-process parameters) }, "additionalParams": { (a JSON object that contains parameters for training configuration) } }' ``` **Contents** + [ ## `command` 参数 ](#export-parameters-command) + [ ## `outputS3Path` 参数 ](#export-parameters-outputS3Path) + [ ## `jobSize` 参数 ](#export-parameters-jobSize) + [ ## `params` 对象 ](#export-parameters-params) + [ ## `additionalParams` 对象 ](#export-parameters-additionalParams) + [ # 导出 `params` 顶级 JSON 对象中的参数字段 ](export-params-fields.md) + [ ## 导出参数 `params` 对象中可能的字段列表 ](export-params-fields.md#export-params-fields-list) + [ ### 所有导出类型通用的字段列表 ](export-params-fields.md#export-params-common-fields-list) + [ ### 属性图导出的字段列表 ](export-params-fields.md#export-params-property-graph-fields-list) + [ ### RDF 导出的字段列表 ](export-params-fields.md#export-params-RDF-fields-list) + [ ## 所有导出类型通用的字段 ](export-params-fields.md#export-params-common-fields) + [ ### `params` 中的 `cloneCluster` 字段 ](export-params-fields.md#export-params-cloneCluster) + [ ### `params` 中的 `cloneClusterInstanceType` 字段 ](export-params-fields.md#export-params-cloneClusterInstanceType) + [ ### `params` 中的 `cloneClusterReplicaCount` 字段 ](export-params-fields.md#export-params-cloneClusterReplicaCount) + [ ### `params` 中的 `cloneClusterEnableAuditLogs` 字段 ](export-params-fields.md#export-params-cloneClusterEnableAuditLogs) + [ ### `params` 中的 `clusterId` 字段 ](export-params-fields.md#export-params-clusterId) + [ ### `params` 中的 `endpoint` 字段 ](export-params-fields.md#export-params-endpoint) + [ ### `params` 中的 `endpoints` 字段 ](export-params-fields.md#export-params-endpoints) + [ ### `params` 中的 `profile` 字段 ](export-params-fields.md#export-params-profile) + [ ### `params` 中的 `useIamAuth` 字段 ](export-params-fields.md#export-params-useIamAuth) + [ ### `params` 中的 `includeLastEventId` 字段 ](export-params-fields.md#export-params-includeLastEventId) + [ ## 用于属性图导出的字段 ](export-params-fields.md#export-params-property-graph-fields) + [ ### `params` 中的 `concurrency` 字段 ](export-params-fields.md#export-params-concurrency) + [ ### `params` 中的 `edgeLabels` 字段 ](export-params-fields.md#export-params-edgeLabels) + [ ### `params` 中的 `filter` 字段 ](export-params-fields.md#export-params-filter) + [ ### `params` 中的 `filterConfigFile` 字段 ](export-params-fields.md#export-params-filterConfigFile) + [ ### `params` 中用于属性图数据的 `format` 字段 ](export-params-fields.md#export-params-format-pg) + [ ### `params` 中的 `gremlinFilter` 字段 ](export-params-fields.md#export-params-gremlinFilter) + [ ### `params` 中的 `gremlinNodeFilter` 字段 ](export-params-fields.md#export-params-gremlinNodeFilter) + [ ### `params` 中的 `gremlinEdgeFilter` 字段 ](export-params-fields.md#export-params-gremlinEdgeFilter) + [ ### `params` 中的 `nodeLabels` 字段 ](export-params-fields.md#export-params-nodeLabels) + [ ### `params` 中的 `scope` 字段 ](export-params-fields.md#export-params-scope) + [ ## RDF 导出的字段 ](export-params-fields.md#export-params-rdf-fields) + [ ### `params` 中用于 RDF 数据的 `format` 字段 ](export-params-fields.md#export-params-format-rdf) + [ ### `params` 中的 `rdfExportScope` 字段 ](export-params-fields.md#export-params-rdfExportScope) + [ ### `params` 中的 `sparql` 字段 ](export-params-fields.md#export-params-sparql) + [ ### `params` 中的 `namedGraph` 字段 ](export-params-fields.md#namedgraph-params-sparql) + [ # 筛选导出内容的示例 ](export-filtering-examples.md) + [ ## 筛选属性图数据的导出 ](export-filtering-examples.md#export-property-graph-filtering-examples) + [ ### 使用 `scope` 仅导出边缘的示例 ](export-filtering-examples.md#export-property-graph-filtering-scope-example) + [ ### 使用 `nodeLabels` 和 `edgeLabels` 仅导出带有特定标签的节点和边缘的示例 ](export-filtering-examples.md#export-property-graph-filtering-labels-example) + [ ### 使用 `filter` 仅导出指定节点、边缘和属性的示例 ](export-filtering-examples.md#export-property-graph-filtering-filter-example) + [ ### 使用 `gremlinFilter` 的示例。 ](export-filtering-examples.md#export-property-graph-filtering-gremlinFilter-example) + [ ### 使用 `gremlinNodeFilter` 的示例。 ](export-filtering-examples.md#export-property-graph-filtering-gremlinNodeFilter-example) + [ ### 使用 `gremlinEdgeFilter` 的示例。 ](export-filtering-examples.md#export-property-graph-filtering-gremlinEdgeFilter-example) + [ ### 组合 `filter`、`gremlinNodeFilter`、`nodeLabels`、`edgeLabels` 和 `scope` ](export-filtering-examples.md#export-property-graph-filtering-combo-example) + [ ## 筛选 RDF 数据的导出 ](export-filtering-examples.md#export-RDF-filtering-examples) + [ ### 使用 `rdfExportScope` 和 `sparql` 导出特定边缘 ](export-filtering-examples.md#export-RDF-filtering-rdfExportScope-sparql-example) + [ ### 使用 `namedGraph` 导出单个命名图 ](export-filtering-examples.md#export-RDF-filtering-rdfExportScope-sparql-namedGraph-example) ## `command` 参数 `command` 顶级参数决定是导出属性图数据还是导出 RDF 数据。如果忽略 `command` 参数，则导出过程默认为导出属性图数据。 + **`export-pg`** – 导出属性图数据。 + **`export-rdf`** – 导出 RDF 数据。 ## `outputS3Path` 参数 `outputS3Path` 顶级参数是必需的，并且必须包含可将导出文件发布到的 Amazon S3 位置的 URI： ``` "outputS3Path" : "s3://(your Amazon S3 bucket)/(path to output folder)" ``` 该值必须以 `s3://` 开头，后跟有效的桶名称以及（可选）桶内的文件夹路径。 ## `jobSize` 参数 `jobSize` 顶级参数仅用于 Neptune-Export 服务，不用于 `neptune-export` 命令行实用程序，并且是可选的。它允许您表征正在启动的导出任务的大小，这有助于确定专用于该任务的计算资源量及其最大并发级别。 ``` "jobSize" : "(one of four size descriptors)" ``` 四个有效的大小描述符是： + `small` – 最大并发度：8。适用于最大 10GB 的存储卷。 + `medium` – 最大并发度：32。适用于最大 100GB 的存储卷。 + `large` – 最大并发度：64。适用于超过 100GB 但小于 1TB 的存储卷。 + `xlarge` – 最大并发度：96。适用于超过 1TB 的存储卷。 默认情况下，在 Neptune-Export 服务上启动的导出作为 `small` 任务运行。 导出的性能不仅取决于 `jobSize` 设置，还取决于您要从中进行导出的数据库实例的数量、每个实例的大小以及任务的有效并发级别。 对于属性图导出，您可以使用 [cloneClusterReplica计数](export-params-fields.md#export-params-cloneClusterReplicaCount) 参数配置数据库实例的数量，也可以使用 [并发](export-params-fields.md#export-params-concurrency) 参数配置任务的有效并发级别。 ## `params` 对象 `params` 顶级参数是一个 JSON 对象，其中包含用于控制导出过程本身的参数，如[导出 `params` 顶级 JSON 对象中的参数字段](export-params-fields.md)中所述。`params` 对象中的某些字段特定于属性图导出，有些字段特定于 RDF。 ## `additionalParams` 对象 `additionalParams` 顶级参数是一个 JSON 对象，其中包含可用于控制在导出数据后应用于数据的操作的参数。目前，`additionalParams` 仅用于导出 [Neptune ML](machine-learning-additionalParams.md) 的训练数据。 # 导出 `params` 顶级 JSON 对象中的参数字段 Neptune 导出 `params` JSON 对象允许您控制导出，包括导出数据的类型和格式。 ## 导出参数 `params` 对象中可能的字段列表 下面列出了所有可能出现在 `params` 对象中的顶级字段。任何一个对象中都只显示这些字段的一个子集。 ### 所有导出类型通用的字段列表 + [`cloneCluster`](#export-params-cloneCluster) + [`cloneClusterInstanceType`](#export-params-cloneClusterInstanceType) + [`cloneClusterReplicaCount`](#export-params-cloneClusterReplicaCount) + [`cloneClusterEnableAuditLogs`](#export-params-cloneClusterEnableAuditLogs) + [`clusterId`](#export-params-clusterId) + [`endpoint`](#export-params-endpoint) + [`endpoints`](#export-params-endpoints) + [`profile`](#export-params-profile) + [`useIamAuth`](#export-params-useIamAuth) + [`includeLastEventId`](#export-params-includeLastEventId) ### 属性图导出的字段列表 + [`concurrency`](#export-params-concurrency) + [`edgeLabels`](#export-params-edgeLabels) + [`filter`](#export-params-filter) + [`filterConfigFile`](#export-params-filterConfigFile) + [`gremlinFilter`](#export-params-gremlinFilter) + [`gremlinNodeFilter`](#export-params-gremlinFilter) + [`gremlinEdgeFilter`](#export-params-gremlinFilter) + [`format`](#export-params-format-pg) + [`nodeLabels`](#export-params-nodeLabels) + [`scope`](#export-params-scope) ### RDF 导出的字段列表 + [`format`](#export-params-format-rdf) + [`rdfExportScope`](#export-params-rdfExportScope) + [`sparql`](#export-params-sparql) + [`namedGraph`](#namedgraph-params-sparql) ## 所有导出类型通用的字段 ### `params` 中的 `cloneCluster` 字段 *（可选）*。默认值：`false`。 如果 `cloneCluster` 参数设置为 `true`，则导出过程将使用数据库集群的快速克隆： ``` "cloneCluster" : true ``` 默认情况下，导出过程会从您使用 `endpoint`、`endpoints` 或 `clusterId` 参数指定的数据库集群中导出数据。但是，如果在导出过程中正在使用数据库集群，并且数据正在更改，则导出过程无法保证正在导出的数据的一致性。 为确保导出的数据一致，请改为使用 `cloneCluster` 参数从数据库集群的静态克隆中导出。 克隆的数据库集群与源数据库集群在同一 VPC 中创建，并继承源数据库集群的安全组、子网组和 IAM 数据库身份验证设置。导出完成后，Neptune 会删除克隆的数据库集群。 默认情况下，克隆的数据库集群由与源数据库集群中的主实例具有相同实例类型的单个实例组成。您可以通过使用 `cloneClusterInstanceType` 指定不同的实例类型，更改用于克隆的数据库集群的实例类型。 **注意** 如果您不使用 `cloneCluster` 选项，而是直接从主数据库集群导出，则可能需要增加从中导出数据的实例的超时时间。对于大型数据集，应将超时设置为几个小时。 ### `params` 中的 `cloneClusterInstanceType` 字段 *（可选）*。 如果 `cloneCluster` 参数存在且设置为 `true`，则可以使用 `cloneClusterInstanceType` 参数指定用于克隆的数据库集群的实例类型： 默认情况下，克隆的数据库集群由与源数据库集群中的主实例具有相同实例类型的单个实例组成。 ``` "cloneClusterInstanceType" : "(for example, r5.12xlarge)" ``` ### `params` 中的 `cloneClusterReplicaCount` 字段 *（可选）*。 如果 `cloneCluster` 参数存在且设置为 `true`，则可以使用 `cloneClusterReplicaCount` 参数来指定在克隆的数据库集群中创建的只读副本实例的数量： ``` "cloneClusterReplicaCount" : (for example, 3) ``` 默认情况下，克隆的数据库集群由单个主实例组成。`cloneClusterReplicaCount` 参数允许您指定应额外创建多少只读副本实例。 ### `params` 中的 `cloneClusterEnableAuditLogs` 字段 *（可选）*。默认值：false。 如果 `cloneCluster` 参数存在且设置为 true，则可以使用 `cloneClusterEnableAuditLogs` 参数在克隆的集群中启用或禁用审计日志。 默认情况下，审计日志处于禁用状态。 ``` "cloneClusterEnableAuditLogs" : true ``` ### `params` 中的 `clusterId` 字段 *（可选）*。 `clusterId` 参数指定要使用的数据库集群的 ID： ``` "clusterId" : "(the ID of your DB cluster)" ``` 如果您使用 `clusterId` 参数，则导出过程将使用该数据库集群中的所有可用实例来提取数据。 **注意** `endpoint`、`endpoints` 和 `clusterId` 参数是互斥的。使用且仅使用其中一个。 ### `params` 中的 `endpoint` 字段 *（可选）*。 使用 `endpoint` 指定数据库集群中 Neptune 实例的端点，导出过程可以查询该端点以提取数据（请参阅[终端节点连接](feature-overview-endpoints.md)）。这只是 DNS 名称，不包括协议或端口： ``` "endpoint" : "(a DNS endpoint of your DB cluster)" ``` 使用集群或实例端点，但不要使用主读取器端点。 **注意** `endpoint`、`endpoints` 和 `clusterId` 参数是互斥的。使用且仅使用其中一个。 ### `params` 中的 `endpoints` 字段 *（可选）*。 使用 `endpoints` 指定数据库集群中端点的 JSON 数组，导出过程可以查询这些端点以提取数据（请参阅[终端节点连接](feature-overview-endpoints.md)）。这些只是 DNS 名称，不包括协议或端口： ``` "endpoints": [ "(one endpoint in your DB cluster)", "(another endpoint in your DB cluster)", "(a third endpoint in your DB cluster)" ] ``` 如果您的集群中有多个实例（一个主实例和一个或多个只读副本），则可以使用 `endpoints` 参数在这些端点列表间分配查询，从而提高导出性能。 **注意** `endpoint`、`endpoints` 和 `clusterId` 参数是互斥的。使用且仅使用其中一个。 ### `params` 中的 `profile` 字段 *（需要此字段以便为 Neptune ML 导出训练数据，除非 `additionalParams` 字段中存在 `neptune_ml` 字段）*。 `profile` 参数为特定工作负载提供一组预配置的参数。目前，导出过程仅支持 `neptune_ml` 配置文件 如果要为 Neptune ML 导出训练数据，请向 `params` 对象添加以下参数： ``` "profile" : "neptune_ml" ``` ### `params` 中的 `useIamAuth` 字段 *（可选）*。默认值：`false`。 如果您要从中导出数据的数据库[启用了 IAM 身份验证](iam-auth-enable.md)，则必须包括 `useIamAuth` 参数（设置为 `true`）： ``` "useIamAuth" : true ``` ### `params` 中的 `includeLastEventId` 字段 如果将 `includeLastEventId` 设置为 true，并且要从中导出数据的数据库启用了 [Neptune Streams](streams-using.md)，则导出过程会将 `lastEventId.json` 文件写入您指定的导出位置。此文件包含流中最后一个事件的 `commitNum` 和 `opNum`。 ``` "includeLastEventId" : true ``` 导出过程创建的克隆数据库会继承其父数据库的流设置。如果父级启用了流，则克隆同样会启用流。克隆上流的内容将反映创建克隆时父流的内容（包括相同的事件 IDs）。 ## 用于属性图导出的字段 ### `params` 中的 `concurrency` 字段 *（可选）*。默认值：`4`。 `concurrency` 参数指定导出过程应使用的并行查询数量： ``` "concurrency" : (for example, 24) ``` 一个好的指导方针是，在要从中导出数据的所有实例CPUs上，将并发级别设置为 v 数的两倍。例如，一个 r5.xlarge 实例有 4 v。CPUs 如果您要从包含 3 个 r5.xlarge 实例的集群中导出，则可以将并发级别设置为 24（= 3 x 2 x 4）。 如果您使用的是 Neptune-Export 服务，则并发级别受到 [jobSize](export-parameters.md#export-parameters-jobSize) 设置的限制。例如，小型任务支持的并发级别为 8。如果您尝试使用 `concurrency` 参数为小型任务指定并发级别 24，则有效级别将保持为 8。 如果您从克隆的集群中导出，则导出过程会根据克隆实例的大小和任务大小计算适当的并发级别。 ### `params` 中的 `edgeLabels` 字段 *（可选）*。 使用 `edgeLabels` 仅导出那些带有您指定的标签的边缘： ``` "edgeLabels" : ["(a label)", "(another label"] ``` JSON 数组中的每个标签都必须是单个简单的标签。 `scope` 参数优先于 `edgeLabels` 参数，因此，如果 `scope` 值不包括边缘，则 `edgeLabels` 参数无效。 ### `params` 中的 `filter` 字段 *（可选）*。 `filter`用于指定只应导出带有特定标签的节点 and/or 边，并用于筛选为每个节点或边缘导出的属性。 `filter` 对象的一般结构，无论是内联对象还是筛选条件配置文件中的对象，如下所示： ``` "filter" : { "nodes": [ (array of node label and properties objects) ], "edges": [ (array of edge definition an properties objects) ] } ``` + **`nodes`** – 包含节点和节点属性的 JSON 数组，格式如下： ``` "nodes : [ { "label": "(node label)", "properties": [ "(a property name)", "(another property name)", ( ... ) ] } ] ``` + `label` – 节点的一个或多个属性图标签。 取一个值，或者如果节点有多个标签，则取一个值数组。 + `properties` – 包含要导出的节点属性的名称的数组。 + **`edges`** – 包含边缘定义的 JSON 数组，格式如下： ``` "edges" : [ { "label": "(edge label)", "properties": [ "(a property name)", "(another property name)", ( ... ) ] } ] ``` + `label` – 边缘的属性图标签。取单个值。 + `properties` – 包含要导出的边缘属性的名称的数组。 ### `params` 中的 `filterConfigFile` 字段 *（可选）*。 使用 `filterConfigFile` 指定包含筛选条件配置的 JSON 文件，其格式与 `filter` 参数采用的格式相同： ``` "filterConfigFile" : "s3://(your Amazon S3 bucket)/neptune-export/(the name of the JSON file)" ``` 有关 `filterConfigFile` 文件的格式，请参阅[筛选](#export-params-filter)。 ### `params` 中用于属性图数据的 `format` 字段 *（可选）*。*默认值*：`csv`（逗号分隔值） `format` 参数指定导出的属性图数据的输出格式： ``` "format" : (one of: csv, csvNoHeaders, json, neptuneStreamsJson) ``` + **`csv`** – 逗号分隔值 (CSV) 格式的输出，列标题根据 [Gremlin 加载数据格式](bulk-load-tutorial-format-gremlin.md)进行格式化。 + **`csvNoHeaders`** – CSV 格式的数据，没有列标题。 + **`json`** – JSON 格式的数据。 + **`neptuneStreamsJson`** – 使用 [GREMLIN\$1JSON 更改序列化格式](streams-change-formats.md)的 JSON 格式的数据。 ### `params` 中的 `gremlinFilter` 字段 *（可选）*。 `gremlinFilter` 参数允许您提供用于筛选节点和边缘的 Gremlin 代码段，例如 `has()` 步骤： ``` "gremlinFilter" : (a Gremlin snippet) ``` 字段名称和字符串值应用转义的双引号括起来。对于日期和时间，您可以使用 [datetime](best-practices-gremlin-datetime.md) 方法。 以下示例仅导出具有 date-created 属性且属性值晚于 2021-10-10 的节点和边缘： ``` "gremlinFilter" : "has(\"created\", gt(datetime(\"2021-10-10\")))" ``` ### `params` 中的 `gremlinNodeFilter` 字段 *（可选）*。 `gremlinNodeFilter` 参数允许您提供用于筛选节点的 Gremlin 代码段，例如 `has()` 步骤： ``` "gremlinNodeFilter" : (a Gremlin snippet) ``` 字段名称和字符串值应用转义的双引号括起来。对于日期和时间，您可以使用 [datetime](best-practices-gremlin-datetime.md) 方法。 以下示例仅导出具有 `deleted` 布尔属性且属性值为 `true` 的节点： ``` "gremlinNodeFilter" : "has(\"deleted\", true)" ``` ### `params` 中的 `gremlinEdgeFilter` 字段 *（可选）*。 `gremlinEdgeFilter` 参数允许您提供用于筛选边缘的 Gremlin 代码段，例如 `has()` 步骤： ``` "gremlinEdgeFilter" : (a Gremlin snippet) ``` 字段名称和字符串值应用转义的双引号括起来。对于日期和时间，您可以使用 [datetime](best-practices-gremlin-datetime.md) 方法。 以下示例仅导出具有 `strength` 数值属性且属性值为 5 的边缘： ``` "gremlinEdgeFilter" : "has(\"strength\", 5)" ``` ### `params` 中的 `nodeLabels` 字段 *（可选）*。 使用 `nodeLabels` 仅导出那些带有您指定的标签的节点： ``` "nodeLabels" : ["(a label)", "(another label"] ``` JSON 数组中的每个标签都必须是单个简单的标签。 `scope` 参数优先于 `nodeLabels` 参数，因此，如果 `scope` 值不包括节点，则 `nodeLabels` 参数无效。 ### `params` 中的 `scope` 字段 *（可选）*。默认值：`all`。 `scope` 参数指定是仅导出节点，仅导出边缘，还是同时导出节点和边缘： ``` "scope" : (one of: nodes, edges, or all) ``` + `nodes` – 仅导出节点及其属性。 + `edges` – 仅导出边缘及其属性。 + `all` – 同时导出节点和边缘及其属性（默认）。 ## RDF 导出的字段 ### `params` 中用于 RDF 数据的 `format` 字段 *（可选）*。*默认值*：`turtle` `format` 参数指定导出的 RDF 数据的输出格式： ``` "format" : (one of: turtle, nquads, ntriples, neptuneStreamsJson) ``` + **`turtle`** – Turtle 格式的输出。 + **`nquads`** – N-Quads 格式的数据，没有列标题。 + **`ntriples`** – N-Triples 格式的数据。 + **`neptuneStreamsJson`** – 使用 [SPARQL NQUADS 更改序列化格式](streams-change-formats.md)的 JSON 格式的数据。 ### `params` 中的 `rdfExportScope` 字段 *（可选）*。默认值：`graph`。 `rdfExportScope` 参数指定 RDF 导出的范围： ``` "rdfExportScope" : (one of: graph, edges, or query) ``` + `graph` – 导出所有 RDF 数据。 + `edges` – 仅导出表示边缘的三元组。 + `query` – 导出由使用 `sparql` 字段提供的 SPARQL 查询取回的数据。 ### `params` 中的 `sparql` 字段 *（可选）*。 `sparql` 参数允许您指定 SPARQL 查询来取回要导出的数据： ``` "sparql" : (a SPARQL query) ``` 如果您使用 `sparql` 字段提供查询，还必须将 `rdfExportScope` 字段设置为 `query`。 ### `params` 中的 `namedGraph` 字段 *（可选）*。 使用 `namedGraph` 参数，您可以指定 IRI 以限制导出为单个命名图： ``` "namedGraph" : (Named graph IRI) ``` `namedGraph` 参数只能用于设置为 `graph` 的 `rdfExportScope` 字段。 # 筛选导出内容的示例 以下示例说明了筛选导出的数据的方法。 ## 筛选属性图数据的导出 ### 使用 `scope` 仅导出边缘的示例 ``` { "command": "export-pg", "params": { "endpoint": "(your Neptune endpoint DNS name)", "scope": "edges" }, "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export" } ``` ### 使用 `nodeLabels` 和 `edgeLabels` 仅导出带有特定标签的节点和边缘的示例 以下示例中的 `nodeLabels` 参数指定只应导出带有 `Person` 标签或 `Post` 标签的节点。`edgeLabels` 参数指定只应导出带有 `likes` 标签的边缘： ``` { "command": "export-pg", "params": { "endpoint": "(your Neptune endpoint DNS name)", "nodeLabels": ["Person", "Post"], "edgeLabels": ["likes"] }, "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export" } ``` ### 使用 `filter` 仅导出指定节点、边缘和属性的示例 此示例中的 `filter` 对象导出带有 `type`、`code` 和 `desc` 属性的 `country` 节点，还导出带有 `dist` 属性的 `route` 边缘。 ``` { "command": "export-pg", "params": { "endpoint": "(your Neptune endpoint DNS name)", "filter": { "nodes": [ { "label": "country", "properties": [ "type", "code", "desc" ] } ], "edges": [ { "label": "route", "properties": [ "dist" ] } ] } }, "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export" } ``` ### 使用 `gremlinFilter` 的示例。 此示例使用 `gremlinFilter` 以仅导出 2021-10-10 之后创建的节点和边缘（即其 `created` 属性值大于 2021-10-10）： ``` { "command": "export-pg", "params": { "endpoint": "(your Neptune endpoint DNS name)", "gremlinFilter" : "has(\"created\", gt(datetime(\"2021-10-10\")))" }, "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export" } ``` ### 使用 `gremlinNodeFilter` 的示例。 此示例使用 `gremlinNodeFilter` 以仅导出已删除的节点（其布尔 `deleted` 属性的值为 `true` 的节点）： ``` { "command": "export-pg", "params": { "endpoint": "(your Neptune endpoint DNS name)", "gremlinNodeFilter" : "has(\"deleted\", true)" }, "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export" } ``` ### 使用 `gremlinEdgeFilter` 的示例。 此示例使用 `gremlinEdgeFilter ` 以仅导出具有 `strength` 数值属性且属性值为 5 的边缘： ``` { "command": "export-pg", "params": { "endpoint": "(your Neptune endpoint DNS name)", "gremlinEdgeFilter" : "has(\"strength\", 5)" }, "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export" } ``` ### 组合 `filter`、`gremlinNodeFilter`、`nodeLabels`、`edgeLabels` 和 `scope` 此示例中的 `filter` 对象导出： + 带有其 `type`、`code` 和 `desc` 属性的 `country` 节点 + 带有其 `code`、`icao` 和 `runways` 属性的 `airport` 节点 + 带有其 `dist` 属性的 `route` 边缘 `gremlinNodeFilter` 参数筛选节点，以便仅导出具有 `code` 属性且属性值以 A 开头的节点。 `nodeLabels` 和 `edgeLabels` 参数进一步限制了输出，因此只输出 `airport` 节点和 `route` 边缘。 最后，`scope` 参数消除了输出中的边缘，从而在输出中只留下指定的 `airport` 节点。 ``` { "command": "export-pg", "params": { "endpoint": "(your Neptune endpoint DNS name)", "filter": { "nodes": [ { "label": "airport", "properties": [ "code", "icao", "runways" ] }, { "label": "country", "properties": [ "type", "code", "desc" ] } ], "edges": [ { "label": "route", "properties": [ "dist" ] } ] }, "gremlinNodeFilter": "has(\"code\", startingWith(\"A\"))", "nodeLabels": [ "airport" ], "edgeLabels": [ "route" ], "scope": "nodes" }, "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export" } ``` ## 筛选 RDF 数据的导出 ### 使用 `rdfExportScope` 和 `sparql` 导出特定边缘 此示例导出谓词为 < http://kelvinlawrence 的三元组。 net/air-routes/objectProperty/route> 且其对象不是字面意思： ``` { "command": "export-rdf", "params": { "endpoint": "(your Neptune endpoint DNS name)", "rdfExportScope": "query", "sparql": "CONSTRUCT { ?s ?o } WHERE { ?s ?p ?o . FILTER(!isLiteral(?o)) }" }, "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export" } ``` ### 使用 `namedGraph` 导出单个命名图 此示例导出属于命名图的三元组 < http://aws.amazon。 com/neptune/vocab/v01/DefaultNamedGraph>: ``` { "command": "export-rdf", "params": { "endpoint": "(your Neptune endpoint DNS name)", "rdfExportScope": "graph", "namedGraph": "http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph" }, "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export" } ``` # 对 Neptune 导出过程进行故障排除 Amazon Neptune 导出流程使用 [AWS Batch](https://docs.aws.amazon.com/batch/latest/userguide/) 来预调配导出 Neptune 数据所需的计算和存储资源。运行导出操作时，您可以使用 `logs` 字段中的链接访问导出任务的 CloudWatch 日志。 但是，执行导出的 AWS Batch 任务的 CloudWatch 日志仅在 AWS Batch 任务运行时才可用。如果 Neptune 导出报告导出处于待处理状态，则不会有日志链接可供您访问 CloudWatch 日志。如果导出任务保持 `pending` 状态的时间超过几分钟，则预调配底层 AWS Batch 资源可能会出现问题。 当导出任务离开待处理状态时，您可以按如下方式检查其状态： **检查 AWS Batch 任务的状态** 1. 打开AWS Batch控制台，地址：[https://console.aws.amazon.com/batch/](https://console.aws.amazon.com/batch/)。 1. 选择 neptune-export 任务队列。 1. 查找名称与您开始导出时由 Neptune 导出返回的 `jobName` 相匹配的任务。 ![\[检查状态时 AWS Batch 控制台的屏幕截图\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/images/batch-console-checking-export.png) 如果任务保持卡在 `RUNNABLE` 状态，则可能是因为网络或安全问题使容器实例无法加入底层的 Amazon Elastic Container Service (Amazon ECS) 集群。请参阅[本支持文章](https://aws.amazon.com/premiumsupport/knowledge-center/batch-job-stuck-runnable-status/)中有关验证计算环境的网络和安全设置的部分。 您可以检查的另一件事是自动扩缩是否存在问题： **查看 AWS Batch 计算环境的 Amazon EC2 自动扩缩组** 1. 通过以下网址打开 Amazon EC2 控制台：[https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)。 1. 为 neptune-export 计算环境选择**自动扩缩**组。 1. 打开**活动**选项卡，并查看活动历史记录中是否存在未成功的事件。 ![\[检查自动扩缩问题时 Amazon EC2 控制台的屏幕截图\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/images/ec2-console-checking-auto-scaling.png) ## Neptune 导出常见错误 ### `org.eclipse.rdf4j.query.QueryEvaluationException: Tag mismatch!` 如果 `export-rdf` 任务经常失败并引发 `Tag mismatch!` `QueryEvaluationException`，则 Neptune 实例的大小对于 Neptune 导出使用的大型、长时间运行的查询来说太小了。 您可以通过纵向扩展到更大的 Neptune 实例或将任务配置为从大型克隆集群中导出来避免出现此错误，如下所示： ``` '{ "command": "export-rdf", "outputS3Path": "s3://(your Amazon S3 bucket)/neptune-export", "params": { "endpoint": "(your Neptune endpoint DNS name)", "cloneCluster": True, "cloneClusterInstanceType" : "r5.24xlarge" } }' ``` # 将 Gremlin 查询结果导出到 Amazon S3 从引擎版本 1.4.3.0 开始，Amazon Neptune 支持将 Gremlin 查询结果直接导出到 Amazon S3。该功能支持您将大型查询结果导出到 Amazon S3 存储桶，而不是作为查询响应返回，从而更高效地处理海量查询结果。 要将查询结果导出到 Amazon S3，请在 Gremlin 查询的最后一步使用 `call()` 步骤，并将服务名称设置为 `neptune.query.exportToS3`。可在 `call()` 步骤之后添加[使用字节码的 Tinkerpop 驱动程序](https://tinkerpop.apache.org/docs/current/reference/#terminal-steps)中的终端步骤。导出参数必须以字符串值的形式提供。 **注意** 包含 `call()` 步骤且该步骤使用 `neptune.query.exportToS3` 的查询，若未作为最终步骤使用，则会失败。使用字节码的 Gremlin 客户端可以使用终端步骤。有关更多信息，请参阅 Amazon Neptune 文档中的 [Gremlin 最佳实践](https://docs.aws.amazon.com//neptune/latest/userguide/best-practices-gremlin-java-bytecode.html)。 ``` g.V() ... .call('neptune.query.exportToS3', [ 'destination': 's3://your-bucket/path/result.json', 'format': 'GraphSONv3', 'kmskeyArn': 'optional-kms-key-arn' ]) ``` **Parameters** + `destination`：必填 - 结果将写入的 Amazon S3 URI。 + `format`: 必填-输出格式，目前仅支持 “[Graph SONv3](https://tinkerpop.apache.org/docs/3.7.3/dev/io/#graphson-3d0)”。 + `keyArn`: 可选-用于 Amazon S3 [服务器端AWS KMS](https://docs.aws.amazon.com//AmazonS3/latest/userguide/serv-side-encryption.html)加密的密钥的 ARN。 ## 示例 **示例查询** ``` g.V(). hasLabel('Comment'). valueMap(). call('neptune.query.exportToS3', [ 'destination': 's3://your-bucket/path/result.json', 'format': 'GraphSONv3', 'keyArn': 'optional-kms-key-arn' ]) ``` **查询响应示例** ``` { "destination":"s3://your-bucket/path/result.json, "exportedResults": 100, "exportedBytes": 102400 } ``` ## 先决条件 + 您的 Neptune 数据库实例必须能够通过类型网关的 VPC 端点访问 Amazon S3。 + 要在查询中使用自定义AWS KMS加密，需要接口类型的 VPC 终端节点，以允许 AWS KMS Neptune 与之通信。AWS KMS + 您必须在 Neptune 上启用 IAM 身份验证并拥有相应的 IAM 权限，才能写入目标 Amazon S3 存储桶。否则，会导致 400 错误请求错误：“集群必须启用 IAM 身份验证，才能进行 S3 导出”。 + 目标 Amazon S3 存储桶： + 目标 Amazon S3 存储桶不得是公有的。必须启用 `Block public access`。 + 目标 Amazon S3 目标必须为空。 + 目标 Amazon S3 存储桶必须针对 `Delete expired object delete markers or incomplete multipart uploads`（包含 `Delete incomplete multipart uploads`）启用生命周期规则。有关更多信息，请参阅 [Amazon S3 生命周期管理更新 – 支持分段上传和删除标记](https://aws.amazon.com/blogs/aws/s3-lifecycle-management-update-support-for-multipart-uploads-and-delete-markers/)。 ![\[图像：显示了生命周期规则操作。\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/images/lifecycleRuleActions.png) + 目标 Amazon S3 存储桶必须针对 `Delete expired object delete markers or incomplete multipart uploads` 启用生命周期规则，并将 `Delete incomplete multipart uploads` 设置为高于查询评估所需的值（例如 7 天）。这是删除未完成的上传（无法直接看到但会产生费用）所必需的，以防万一 Neptune 无法完成或中止（例如，由于失败）。 instance/engine 有关更多信息，请参阅 [Amazon S3 生命周期管理更新 – 支持分段上传和删除标记](https://aws.amazon.com/blogs/aws/s3-lifecycle-management-update-support-for-multipart-uploads-and-delete-markers/)。 ![\[图像：显示了生命周期规则操作和删除过期对象删除标记。\]](http://docs.aws.amazon.com/zh_cn/neptune/latest/userguide/images/lifecycleRuleActionsDelete.png) **重要注意事项** + 导出步骤必须是 Gremlin 查询的最后一步。 + 如果指定的 Amazon S3 位置已存在对象，则查询将失败。 + 导出查询的查询执行时间上限为 11 小时 50 分钟。此功能使用[转发访问会话](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_forward_access_sessions.html)。目前上限为 11 小时 50 分钟，以避免令牌过期问题。 **注意** 导出查询仍遵循查询超时限制。对于大型导出，应使用适当的查询超时设置。 + 所有上传到 Amazon S3 的新对象都会自动加密。 + 为了避免在出现错误或崩溃时由于分段上传未完成而产生存储费用，建议您在 Amazon S3 存储桶上设置包含 `Delete incomplete multipart uploads` 的生命周期规则。 ## 响应格式 查询不会直接返回查询结果，而是返回有关导出操作的元数据，包括状态和导出详细信息。Amazon S3 中的查询结果将SONv3采用[图表](https://tinkerpop.apache.org/docs/3.7.3/dev/io/#graphson-3d0)格式。 ``` { "data": { "@type": "g:List", "@value": [ { "@type": "g:Map", "@value": [ "browserUsed", { "@type": "g:List", "@value": [ "Safari" ] }, "length", { "@type": "g:List", "@value": [ { "@type": "g:Int32", "@value": 7 } ] }, "locationIP", { "@type": "g:List", "@value": [ "192.0.2.0/24" ] }, "creationDate", { "@type": "g:List", "@value": [ { "@type": "g:Date", "@value": 1348341961000 } ] }, "content", { "@type": "g:List", "@value": [ "no way!" ] } ] }, { "@type": "g:Map", "@value": [ "browserUsed", { "@type": "g:List", "@value": [ "Firefox" ] }, "length", { "@type": "g:List", "@value": [ { "@type": "g:Int32", "@value": 2 } ] }, "locationIP", { "@type": "g:List", "@value": [ "203.0.113.0/24" ] }, "creationDate", { "@type": "g:List", "@value": [ { "@type": "g:Date", "@value": 1348352960000 } ] }, "content", { "@type": "g:List", "@value": [ "ok" ] } ] }, ... ] } } ``` **安全性** + 传输到 Amazon S3 的所有数据全部使用 SSL 在传输过程中实现加密。 + 您可以为导出数据的服务器端加密指定密AWS KMS钥。默认情况下，Amazon S3 会对新数据进行加密。如果存储桶配置为使用特定AWS KMS密钥，则使用该密钥。 + 在开始导出之前，Neptune 会验证目标存储桶是否是公有的。 + 不支持跨账户和跨区域导出。 **错误处理** + 目标 Amazon S3 存储桶是公有的。 + 指定对象已经存在。 + 您没有足够的权限写入 Amazon S3 存储桶。 + 查询执行超过了最大时间限制。 **最佳实践** + 使用 Amazon S3 存储桶生命周期规则清理未完成的分段上传。 + 使用 Neptune 日志和指标监控导出操作。您可以检查 [Gremlin 状态端点](https://docs.aws.amazon.com//neptune/latest/userguide/gremlin-api-status.html)以查看查询当前是否正在运行。只要客户端没有收到响应，就会假定查询正在运行。 # 授予 Gremlin Amazon S3 导出功能的访问权限 **所需的 IAM 策略** 1. **Neptune 查询读取权限** ``` { "Sid": "NeptuneQueryRead", "Effect": "Allow", "Action": ["neptune-db:Read*"], "Resource": "arn:aws:neptune-db:us-east-1:123456789012:cluster-ABCD12/*" } ``` **为什么需要它：**此权限支持从 Neptune 数据库读取数据，这是执行要导出的 Gremlin 查询所必需的。前面的示例支持读取查询。对于 read/write 查询，需要 write/delete 权限。 1. **Amazon S3 导出权限** ``` { "Sid": "NeptuneS3Export", "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:PutObject", "s3:AbortMultipartUpload", "s3:GetBucketPublicAccessBlock" ], "Resource": "arn:aws:s3:::neptune-export-bucket/*" } ``` **为什么需要每项权限：** + `s3:ListBucket`：验证存储桶是否存在并列出内容所必需的。 + `s3:PutObject`：将导出数据写入 Amazon S3 所必需的。 + `s3:AbortMultipartUpload`：当导出失败时，清理未完成的分段上传所必需的。 + `s3:GetBucketPublicAccessBlock`：在导出数据之前验证存储桶是否是公有的所必需的一项安全措施。 1. **AWS KMS权限-可选**。仅在使用自定义 AWS KMS 加密时才是必需的。 ``` { "Sid": "NeptuneS3ExportKMS", "Effect": "Allow", "Action": [ "kms:Decrypt", "kms:GenerateDataKey", "kms:DescribeKey" ], "Resource": "arn:aws:kms:::key/mrk-48971c37" "Condition": { "StringEquals": { "kms:ViaService": [ "s3..amazonaws.com", "rds..amazonaws.com" ] } } } ``` **为什么需要每项权限：** + `kms:Decrypt`：需要解密密密AWS KMS钥以进行数据加密。 + `kms:GenerateDataKey`：生成用于加密导出数据的数据密钥所必需的。 + `kms:DescribeKey`：需要验证和检索有关AWS KMS密钥的信息。 + `kms:ViaService`：通过强制该角色不能将密钥用于任何其他AWS服务来提高安全性。 **重要先决条件** + **IAM 身份验证：**必须在 Neptune 集群上启用，才能实施这些权限。 + **VPC 终端节点：** + Amazon S3 需要网关类型 VPC 端点，才能支持 Neptune 与 Amazon S3 进行通信。 + 要在查询中使用自定义AWS KMS加密，需要接口类型的 VPC 终端节点，以允许 AWS KMS Neptune 与之通信。AWS KMS + **Amazon S3 存储桶配置：** + 不得是公有的。 + 应该有一条生命周期规则来清理未完成的分段上传。 + 会自动加密新对象。 这些权限和先决条件可确保安全可靠地导出 Gremlin 查询结果，同时保持适当的访问控制和数据保护措施。