翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# Amazon Neptune にデータをロードする
Amazon Neptune にグラフデータをロードするには、いくつかの方法があります。
+ 比較的少量のデータのみをロードする必要がある場合は、SPARQL `INSERT`ステートメントや Gremlin `mergeV`や `mergeE` ステップなどのクエリを使用できます。openCypher には `CREATE`および `MERGE`句も含まれます。
+ [Neptune 一括ローダー](bulk-load.md) を使用すると、外部ファイルに存在する大量のデータを取り込むことができます。バルクローダーコマンドは、クエリ言語コマンドよりも高速で、オーバーヘッドが少なくなります。これは、大規模なデータセットに最適化されており、RDF (リソース記述フレームワーク) データおよび Gremlin データの両方をサポートしています。
+ AWS Database Migration Service (AWS DMS) を使用して、他のデータストアからデータをインポートできます ([AWS Database Migration Service を使用して別のデータストアから Amazon Neptune にデータをロードする](dms-neptune.md)「」、[AWS Database Migration Service 「 ユーザーガイド](https://docs.aws.amazon.com/dms/latest/userguide/)」を参照）。
+ 1 つまたは複数の Amazon S3 ファイル内の小さなデータセットの場合、クエリベースのロード関数を使用して、クエリ内でデータを直接読み取り、処理できます。詳細については、「[クエリを使用して Amazon Neptune にデータをロードする](load-data-via-query.md)」を参照してください。
**Topics**
+ [Amazon Neptune 一括ローダーを使用したデータの取り込み](bulk-load.md)
+ [AWS Database Migration Service を使用して別のデータストアから Amazon Neptune にデータをロードする](dms-neptune.md)
+ [クエリを使用して Amazon Neptune にデータをロードする](load-data-via-query.md)
# Amazon Neptune 一括ローダーを使用したデータの取り込み
Amazon Neptune は、外部ファイルから Neptune DB クラスターに直接データをロードする `Loader` コマンドを提供します。多数の `INSERT` ステートメント、`addV` および `addE` ステップ、その他の API 呼び出しを実行する代わりに、このコマンドを使用できます。
この Neptune **Loader** コマンドは高速で、オーバーヘッドが少なく、大規模なデータセットに最適化されており、Gremlin データと RDF (リソース記述フレームワーク) データおよび SPARQL が使用するデータの両方をサポートしています。
次の図に示しているのは、このロードプロセスの概要です。
![\[Neptune にデータをロードする際の基本的なステップを示す図。\]](http://docs.aws.amazon.com/ja_jp/neptune/latest/userguide/images/load-diagram.png)
以下に示しているのは、ロードプロセスの手順です。
1. Amazon Simple Storage Service (Amazon S3) バケットに、 ファイルをコピーします。
1. バケットへの読み取りアクセスとリストアクセスのある IAM ロールを作成します。
1. Amazon S3 VPC エンドポイントを作成します。
1. HTTP 経由で Neptune DB インスタンスにリクエストを送信して、Neptune ローダーを起動します。
1. Neptune DB インスタンスでは、バケットからデータをロードする IAM ロールを前提としています。
**注記**
Amazon S3 `SSE-S3` または `SSE-KMS` モードのいずれかを使用して暗号化されている場合は、暗号化されたデータを Amazon S3 からロードできます。ただし、一括ロードに使用するロールが Amazon S3 オブジェクトにアクセスでき、SSE-KMS の場合は `kms:decrypt` にもアクセスできることが条件です。その場合、Neptune はユーザーの認証情報を偽装し、ユーザーに代わって `s3:getObject` 呼び出しを発行することができます。
ただし、Neptune は現在 `SSE-C` モードを使用して暗号化されたデータの読み込みをサポートしていません。
次のセクションでは、Neptune へのデータの準備とロードの手順を説明します。
**Topics**
+ [前提条件: IAM ロールと Amazon S3 アクセス](bulk-load-tutorial-IAM.md)
+ [ロードデータ形式](bulk-load-tutorial-format.md)
+ [例: Neptune DB インスタンスにデータをロードする](bulk-load-data.md)
+ [Amazon Neptune 一括ロードの最適化](bulk-load-optimize.md)
+ [Neptune ローダーリファレンス](load-api-reference.md)
# 前提条件: IAM ロールと Amazon S3 アクセス
Amazon Simple Storage Service (Amazon S3) バケットからデータをロードするには、バケットにアクセスできる AWS Identity and Access Management (IAM) ロールが必要です。Amazon Neptune はデータをロードするためにこのロールを引き受けます。
**注記**
Amazon S3 `SSE-S3` モードを使用して暗号化されている場合は、Amazon S3 から暗号化されたデータを読み込むことができます。その場合、Neptune はユーザーの認証情報を偽装し、ユーザーに代わって `s3:getObject` 呼び出しを発行することができます。
また、IAM ロールに AWS KMSにアクセスするために必要なアクセス権限が含まれている限り、`SSE-KMS` モードを使用して暗号化された Amazon S3 から、暗号化されたデータをロードすることもできます。適切な AWS KMS アクセス許可がない場合、一括ロードオペレーションは失敗し、`LOAD_FAILED`レスポンスを返します。
Neptune は現在 `SSE-C` モードを使用して暗号化された Amazon S3 データのロードをサポートしていません。
以下のセクションでは、マネージド IAM ポリシーを使用して Amazon S3 リソースにアクセスするための IAM ロールを作成し、Neptune クラスターにロールをアタッチする方法を示します。
**Topics**
+ [Amazon Neptune から Amazon S3 リソースにアクセスするための IAM ロールの作成](bulk-load-tutorial-IAM-CreateRole.md)
+ [Amazon Neptune クラスターに IAM ロールを追加する](bulk-load-tutorial-IAM-add-role-cluster.md)
+ [Amazon S3 VPC エンドポイントの作成](bulk-load-tutorial-vpc.md)
+ [Amazon Neptune で IAM ロールを連鎖する](bulk-load-tutorial-chain-roles.md)
**注記**
これらの手順では、IAM コンソールにアクセスでき、IAM ロールとポリシーを管理するアクセス許可が必要です。詳細については、*IAM ユーザーガイド*[の「 AWS マネジメントコンソールで作業するためのアクセス許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_permissions-required.html#Credentials-Permissions-overview-console)」を参照してください。
Amazon Neptune コンソールでは、Neptune クラスターにロールをアタッチする以下の IAM アクセス権限が必要です。
```
iam:GetAccountSummary on resource: *
iam:ListAccountAliases on resource: *
iam:PassRole on resource: * with iam:PassedToService restricted to rds.amazonaws.com
```
# Amazon Neptune から Amazon S3 リソースにアクセスするための IAM ロールの作成
`AmazonS3ReadOnlyAccess` マネージド IAM ポリシーを使用して、Amazon Neptune が Amazon S3 リソースにアクセスできるようにする新しい IAM ロールを作成します。
**Amazon Neptune が Amazon S3 サービスにアクセスすることを許可する新しい IAM ロールを作成するには**
1. IAM コンソール ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) を開きます。
1. ナビゲーションペインで **Roles (ロール) ** を選択してください。
1. [**ロールの作成**] を選択してください。
1. **[AWS のサービス]** で **[S3]** を選択します。
1. **[Next: Permissions]** (次のステップ: 許可) を選択します。
1. フィルタボックスを使用して用語「**S3**」でフィルタ処理し、**AmazonS3ReadOnlyAccess** の横にあるチェックボックスをオンにします。
**注記**
このポリシーによって、すべてのバケットに対する `s3:Get*` および `s3:List*` アクセス許可が付与されます。後の手順では、信頼ポリシーを使用してこのロールへのアクセスを制限します。
ローダーに必要なのは、ロード元のバケットに対する `s3:Get*` および `s3:List*` アクセス権限のみです。したがって、これらのアクセス権限を Amazon S3 リソース別に制限することもできます。
S3 バケットが暗号化されている場合には、`kms:Decrypt` 許可を追加する必要があります。
1. **[次へ: レビュー]** を選択します。
1. **[Role Name]** (ロール名) を IAM ロールの名前 (例: `NeptuneLoadFromS3`) に設定します。オプションの [**Role Description**] (ロールの説明) 値 (「Allows Neptune to access Amazon S3 resources on your behalf.」など) を追加することもできます。
1. **[ロールの作成]** を選択します。
1. ナビゲーションペインで **Roles (ロール) ** を選択してください。
1. [**検索**] フィールドで、作成したロールの名前を入力し、リストに表示されたらそのロールを選択します。
1. [**Trust Relationships**] (信頼関係) タブで、[**Edit trust relationship**] (信頼関係の編集) を選択します。
1. テキストフィールドに次の信頼ポリシーをコピーして貼り付けます。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": [
"rds.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. **[信頼ポリシーの更新]** を選択します。
1. 「[Amazon Neptune クラスターに IAM ロールを追加する](bulk-load-tutorial-IAM-add-role-cluster.md)」のステップを完了します。
# Amazon Neptune クラスターに IAM ロールを追加する
コンソールを使用して IAM ロールを Amazon Neptune クラスターに追加します。これにより、クラスター内の任意の Neptune DB インスタンスがロールを引き受け、Amazon S3 からロードできるようになります。
**注記**
Amazon Neptune コンソールでは、Neptune クラスターにロールをアタッチする以下の IAM アクセス権限が必要です。
```
iam:GetAccountSummary on resource: *
iam:ListAccountAliases on resource: *
iam:PassRole on resource: * with iam:PassedToService restricted to rds.amazonaws.com
```
**Amazon Neptune クラスターに IAM ロールを追加するには**
1. AWS マネジメントコンソールにサインインし、[https://console.aws.amazon.com/neptune/home](https://console.aws.amazon.com/neptune/home) で Amazon Neptune コンソールを開きます。
1. ナビゲーションペインで、**[Databases]** (データベース) を選択します。
1. 変更するクラスターのクラスター識別子を選択します。
1. **[接続とセキュリティ]** タブを選択します。
1. IAM ロールセクションで、前のセクションで作成したロールを選択します。
1. [**Add role**] を選択します。
1. IAM ロールがクラスターにアクセスできるようになるまで待ってから、使用します。
# Amazon S3 VPC エンドポイントの作成
Neptune ローダーには Amazon S3 のためにゲートウェイタイプの VPC エンドポイントが必要です。
**Amazon S3 のアクセスをセットアップするには**
1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/) で Amazon VPC コンソールを開きます。
1. ナビゲーションペインで、**[エンドポイント]** を選択します。
1. [**エンドポイントの作成**] を選択します。
1. ゲートウェイタイプのエンドポイントの **サービス名** `com.amazonaws.region.s3` を選択します。
**注記**
このリージョンが正しくない場合は、コンソールのリージョンが正しいことを確認してください。
1. Neptune DB インスタンスを含む VPC を選択します (Neptune コンソールに DB インスタンスとして一覧表示されます)。
1. クラスターに関連するサブネットに関連付けられているルートテーブルの横にあるチェックボックスをオンにします。ルートテーブルが 1 つだけの場合は、そのボックスを選択する必要があります。
1. **エンドポイントの作成** を選択します。
エンドポイント作成の詳細については、*Amazon VPC ユーザーガイド*の [VPC エンドポイント](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html#create-vpc-endpoint)を参照してください。VPC エンドポイントの制限については、[Amazon S3 の VPC エンドポイント](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-s3.html)を参照してください。
**次のステップ**
これで、Amazon S3 バケットへのアクセスが許可され、データをロードする準備ができました。サポートされる形式については、[ロードデータ形式](bulk-load-tutorial-format.md) を参照してください。
# Amazon Neptune で IAM ロールを連鎖する
**重要**
[エンジンリリース 1.2.1.0.R3](engine-releases-1.2.1.0.R3.md) で導入された IAM ロールの連鎖を利用する新しい一括読み込みクロスアカウント機能では、一括読み込みのパフォーマンスが低下する場合があります。そのため、この機能をサポートするエンジンリリースへのアップグレードは、問題が解決されるまで一時的に中断されました。
クラスターにロールをアタッチすると、クラスターはそのロールを引き受けて、Amazon S3 に保存されているデータにアクセスできるようになります。[エンジンリリース 1.2.1.0.R3](engine-releases-1.2.1.0.R3.md) 以降では、そのロールが必要なすべてのリソースにアクセスできない場合、クラスターが他のリソースにアクセスできるように引き受けることができる 1 つ以上の追加のロールを連鎖できます。チェーン内の各ロールは、クラスターがチェーンの末尾のロールを引き受けるまで、チェーン内の次のロールを引き受けます。
ロールを連鎖するには、ロール間で信頼関係を確立します。例えば、`RoleB` を `RoleA` に連鎖するには、`RoleA` は `RoleB` の引き受けを許可するアクセス許可ポリシーを持っている必要があり、`RoleB` はそのアクセス許可を `RoleA` に戻すことを許可する信頼ポリシーが必要です。詳細については、「[IAM ロールの使用](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)」を参照してください。
チェーン内の最初のロールは、データをロードするクラスターにアタッチされる必要があります。
最初のロールと、チェーン内の次のロールを引き受ける後続の各ロールには、以下のものが必要です。
+ `sts:AssumeRole` アクションに対する `Allow` 効果を持つ特定のステートメントを含むポリシー。
+ `Resource` 要素内の次のロールの Amazon リソースネーム (ARN)。
**注記**
ターゲット Amazon S3 バケットは、クラスターと同じ AWS リージョンに存在する必要があります。
## 連鎖したロールを使用したクロスアカウントアクセス
別のアカウントに属する 1 つまたは複数のロールを連鎖することによって、クロスアカウントアクセスを付与できます。クラスターが別のアカウントに属するロールを一時的に引き受けると、そのアカウントのリソースにアクセスできるようになります。
例えば、**アカウント A** が**アカウント B** に属する Amazon S3 バケットのデータにアクセスしたいとします。
+ **アカウント A **は、 という名前の Neptune AWS のサービスロールを作成し`RoleA`、クラスターにアタッチします。
+ **アカウント B** は、**アカウント B** バケット内のデータにアクセスすることが承認されている `RoleB` という名前のロールを作成します。
+ **アカウント A** は、`RoleB` を引き受けることを許可するアクセス許可ポリシーを `RoleA` にアタッチします。
+ **アカウント B** は、`RoleB`アクセス許可を渡すことができる信頼ポリシーをアタッチします。`RoleA`
+ **アカウント B** バケットのデータにアクセスするには、**アカウント A** は `RoleA` と `RoleB` を連鎖する `iamRoleArn` パラメータを使用してローダーコマンドを実行します。ローダー操作の継続期間中、`RoleA` は一時的に `RoleB` を引き受けて、**アカウント B** で Amazon S3 バケットにアクセスします。
![\[連鎖したロールを使用したクロスアカウントアクセスの図\]](http://docs.aws.amazon.com/ja_jp/neptune/latest/userguide/images/cross-account-bulk-load.png)
例えば、`RoleA` には、Neptune との信頼関係を確立する信頼ポリシーがあるとします。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "rds.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
`RoleA` には、**アカウント B** が所有する `RoleB` を引き受けることを許可するアクセス許可ポリシーもあります。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Stmt1487639602000",
"Effect": "Allow",
"Action": [
"sts:AssumeRole"
],
"Resource": "arn:aws:iam::111122223333:role/RoleB"
}
]
}
```
------
逆に、`RoleB` には、`RoleA` との信頼関係を確立する次のような信頼ポリシーがあるとします。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/RoleA"
}
}
]
}
```
------
`RoleB` には、**アカウント B** にある Amazon S3 バケット内のデータにアクセスするアクセス許可も必要です。
## AWS Security Token Service (STS) VPC エンドポイントの作成
Neptune ローダーは、プライベート IP アドレスを介して AWS STS APIs にプライベートにアクセスするために IAM ロールを連鎖させる AWS STS 場合、 の VPC エンドポイントを必要とします。Amazon VPC から VPC エンドポイント AWS STS を介して、安全でスケーラブルな方法で に直接接続できます。インターフェイス VPC エンドポイントを使用すると、アウトバウンドトラフィックのファイアウォールを開く必要がないため、セキュリティ体制が強化されます。また、Amazon VPC エンドポイントを使用する利点は他にもあります。
VPC エンドポイントを使用する場合、 へのトラフィック AWS STS はインターネット経由で送信されず、Amazon ネットワークを離れることもありません。VPC は、ネットワークトラフィックの可用性リスクや帯域幅の制約 AWS STS なしに、 に安全に接続されます。詳細については、「[AWS STS インターフェイス VPC エンドポイントの使用](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_sts_vpce.html)」を参照してください。
**( AWS Security Token Service STS) のアクセスを設定するには**
1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/) で Amazon VPC コンソールを開きます。
1. ナビゲーションペインで、**[エンドポイント]** を選択します。
1. [**エンドポイントの作成**] を選択します。
1. インターフェイスタイプのエンドポイントの **サービス名** `com.amazonaws.region.sts` を選択します。
1. Neptune DB インスタンスと EC2 インスタンスが含まれている **VPC** を選択します。
1. EC2 インスタンスが存在するサブネットの横にあるチェックボックスを選択します。同じアベイラビリティーゾーンから複数のサブネットを選択することはできません。
1. [IP address type] (IP アドレスのタイプ) で、次のオプションから選択します。
+ **[IPv4]** — IPv4 アドレスをエンドポイントのネットワークインターフェイスに割り当てます。このオプションは、選択したすべてのサブネットに IPv4 アドレス範囲がある場合にのみサポートされます。
+ **[IPv6]** — IPv6 アドレスをエンドポイントのネットワークインターフェイスに割り当てます。このオプションは、選択されたすべてのサブネットが IPv6 のみのサブネットである場合にのみサポートされます。
+ **[Dualstack]** — IPv4 と IPv6 の両方のアドレスをエンドポイントのネットワークインターフェイスに割り当てます。このオプションは、選択されたすべてのサブネットに IPv4 と IPv6 両方のアドレス範囲がある場合にのみサポートされます。
1. **[セキュリティグループ]** で、VPC エンドポイントのエンドポイントネットワークインターフェイスに関連付けるセキュリティグループを選択します。Neptune DB インスタンスと EC2 インスタンスにアタッチされているすべてのセキュリティグループを選択する必要があります。
1. **[Policy]** (ポリシー) で **[Full access]** (フルアクセス) を選択して、すべてのリソースに対するすべてのプリンシパルによる VPC エンドポイント経由のすべてのオペレーションを許可します。それ以外の場合は、**[Custom]** (カスタム) を選択して、VPC エンドポイント経由でリソースに対してアクションを実行するためにプリンシパルが持つ許可を制御する VPC エンドポイントポリシーをアタッチします。このオプションは、サービスが VPC エンドポイントポリシーをサポートしている場合にのみ使用できます。詳細については、「[エンドポイントポリシー](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html)」を参照してください。
1. (*オプション*) タグを追加するには、**[新しいタグを追加]** を選択し、そのタグのキーと値を入力します。
1. **エンドポイントの作成** を選択します。
エンドポイント作成の詳細については、「Amazon VPC ユーザーガイド」の「[VPC エンドポイント](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html)」を参照してください。Amazon STS VPC エンドポイントは IAM ロール連鎖に必要な前提条件であることに注意してください。
AWS STS エンドポイントへのアクセスを許可したので、データのロードを準備できます。サポートされる形式の詳細については、「[データ読み込み形式](bulk-load-tutorial-format.md)」を参照してください。
## ローダーコマンド内でのロールの連鎖
`iamRoleArn` パラメータにロールの ARN のカンマ区切りリストを含めることによって、ローダーコマンドの実行時にロールの連鎖を指定できます。
ほとんどの場合、チェーンに含める必要があるのは 2 つのロールだけですが、3 つ以上のロールを連鎖することも可能です。例えば、このローダーコマンドは次の 3 つのロールを連鎖します。
```
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"
}'
```
# ロードデータ形式
Amazon Neptune `Load` API は、さまざまな形式のデータのロードをサポートしています。
**プロパティグラフのロード形式**
以下のプロパティグラフ形式のいずれかでロードされたデータは、Gremlin と openCypher の両方を使用してクエリできます。
+ [Gremlin ロードデータ形式](bulk-load-tutorial-format-gremlin.md) (`csv`): カンマ区切り値 (CSV) 形式。
+ [openCypher データロード形式](bulk-load-tutorial-format-opencypher.md) (`opencypher`): カンマ区切り値 (CSV) 形式。
**RDF ロード形式**
SPARQL を使用してクエリするリソース記述フレームワーク (RDF) データをロードするには、World Wide Web Consortium (W3C) によって指定されている次の標準形式のいずれかを使用できます。
+ N -Triples (`ntriples`) [https://www.w3.org/TR/n-triples/](https://www.w3.org/TR/n-triples/) の仕様より。
+ N-Quads (`nquads`) [https://www.w3.org/TR/n-quads/](https://www.w3.org/TR/n-quads/) の仕様より。
+ RDF/XML (`rdfxml`) [https://www.w3.org/TR/rdf-syntax-grammar/](https://www.w3.org/TR/rdf-syntax-grammar/) の仕様より。
+ Turtle (`turtle`) [https://www.w3.org/TR/turtle/](https://www.w3.org/TR/turtle/) の仕様より。
**ロードデータは UTF-8 エンコードを使用する必要がある**
**重要**
すべてのロードデータファイルは、UTF-8 形式でエンコードされている必要があります。ファイルが UTF-8 でエンコードされていない場合でも、Neptune は UTF-8 形式のデータとしてロードしようとします。
Unicode 文字を含む N-Quads および N-Triples データの場合、`\uxxxxx` エスケープシーケンスがサポートされています。ただし、Neptune では正規化はサポートされていません。正規化が必要な値が存在する場合、クエリ中にバイトごとに一致することはありません。正規化の詳細については、[Unicode.org](https://unicode.org/faq/normalization.html) の[正規化](https://unicode.org)ページを参照してください。
データがサポートされている形式でない場合は、ロードする前に変換する必要があります。
GraphML を Neptune CSV 形式に変換するためのツールは、[GitHub](https://github.com/awslabs/amazon-neptune-tools/blob/master/graphml2csv/README.md) の [GraphML2CSV プロジェクト](https://github.com/)で利用できます。
## ロードデータファイルの圧縮サポート
Neptune は、`gzip` または `bzip2` 形式の個別ファイルの圧縮をサポートしています。
圧縮されたファイルには `.gz` または `.bz2` 拡張子を付ける必要があり、UTF-8 形式でエンコードされた単一のテキストファイルである必要があります。複数のファイルをロードできますが、それぞれ個別の `.gz`、`.bz2`、または圧縮されていないテキストファイルである必要があります。`.tar`、`.tar.gz`、`.tgz` などの拡張子の付いたアーカイブファイルはサポートされていません。
以下のセクションで、これらの形式についてさらに詳しく説明します。
**Topics**
+ [ロードデータファイルの圧縮サポート](#bulk-load-tutorial-format-compression)
+ [Gremlin ロードデータ形式](bulk-load-tutorial-format-gremlin.md)
+ [openCypher データのロード形式](bulk-load-tutorial-format-opencypher.md)
+ [RDF ロードデータ形式](bulk-load-tutorial-format-rdf.md)
# Gremlin ロードデータ形式
Apache TinkerPop Gremlin データを CSV 形式を使用してロードするには、頂点とエッジを別々のファイルで指定する必要があります。
ローダーは、単一のロードジョブで複数の頂点ファイルおよび複数のエッジファイルからロードできます。
各ロードコマンドは、ロードされる一連のファイルと同じ Amazon S3 バケットのフォルダにある必要があり、`source` パラメータにフォルダ名を指定します。このファイル名とファイル名拡張子は重要ではありません。
Amazon Neptune CSV 形式は RFC 4180 の CSV の仕様に従います。詳細については、Internet Engineering Task Force (IETF) ウェブサイトの、[CSV ファイルの一般形式と MIME タイプ](https://tools.ietf.org/html/rfc4180)を参照してください。
**注記**
すべてのファイルは、UTF-8 形式でエンコードする必要があります。
各ファイルには、カンマ区切りのヘッダー行があります。ヘッダー行は、システム列ヘッダーとプロパティ列ヘッダーの両方で構成されます。
## システム列ヘッダー
頂点ファイルとエッジファイルでは、必須および許可されたシステム列ヘッダーが異なります。
各システム列は、ヘッダーに 1 回のみ表示できます。
すべてのラベルで大文字と小文字が区別されます。
**頂点ヘッダー**
+ `~id` – **必須**
頂点の ID。
+ `~label`
頂点のラベル。複数のラベル値を使用できます。セミコロン (`;`) で区切ります。
`~label` が存在しない場合、TinkerPop は値 `vertex` のラベルを提供します。これは、すべての頂点に少なくとも 1 つのラベルが必要なためです。
**エッジヘッダー**
+ `~id` – **必須**
エッジの ID。
+ `~from` – **必須**
*from* 頂点の頂点 ID。
+ `~to` – **必須**
*to* 頂点の頂点 ID。
+ `~label`
エッジのラベル。エッジには 1 つのラベルのみを含めることができます。
`~label` が存在しない場合、TinkerPop は値 `edge` のラベルを提供します。これは、すべてのエッジにラベルが必要なためです。
## プロパティ列ヘッダー
次の構文を使用して、プロパティ列 (`:`) を指定できます。タイプ名では大文字と小文字が区別されません。ただし、プロパティ名内にコロンがある場合は、次のように、その前にバックスラッシュを付けてエスケープする必要があります。`\:`。
```
propertyname:type
```
**注記**
列ヘッダーでは、スペース、カンマ、キャリッジリターン、改行文字は使用できません。そのため、プロパティ名にこれらの文字を使用することはできません。
タイプに `[]` を追加することで、配列型の列を指定できます。
```
propertyname:type[]
```
**注記**
エッジのプロパティに指定できるのは 1 つの値のみです。配列型が指定された場合や 2 つ目の値が指定された場合はエラーが発生します。
次の例は、`Int` 型の `age` という名前のプロパティの列ヘッダーを示しています。
```
age:Int
```
ファイルのすべての行は、その位置に整数があるか、空のままにする必要があります。
文字列の配列は許可されますが、バックスラッシュを使用してエスケープされないり限配列内の文字列にはセミコロン (`;`) 文字を含めることはできません (次のように:`\;`)。
**列の濃度を指定する**
列ヘッダーを使用して列で識別されたプロパティの*濃度*を指定できます。これにより、バルクローダーで Gremlin クエリと同様に濃度を重視できます。
列の濃度は、次のように指定します。
```
propertyname:type(cardinality)
```
*濃度*値は `single` または `set` となります。デフォルトは `set` であると想定されます。これは、列が複数の値を受け入れられることを意味します。エッジファイルの場合、濃度は常に単一であり、他の濃度を指定すると、ローダーは例外をスローします。
濃度が `single` のとき、値がロードされたときに前の値が既に存在する場合、または複数の値がロードされた場合、ローダーによりエラーがスローされます。`updateSingleCardinalityProperties` フラグを使用して新しい値がロードされたとき、既存の値が置き換えられるように、 この動作をオーバーライドできます。「[ローダーコマンド](load-api-reference-load.md)」を参照してください。
通常、その必要はありませんが、配列型で濃度設定を使用できます。可能な組み合わせは次のとおりです。
+ `name:type` - 濃度は `set` で、コンテンツは単一の値です。
+ `name:type[]` - 濃度は `set` で、コンテンツは複数の値です。
+ `name:type(single)` - 濃度は `single` で、コンテンツは単一の値です。
+ `name:type(set)` - 濃度は、デフォルトと同じ `set` で、コンテンツは単一の値です。
+ `name:type(set)[]` - 濃度は `set` で、コンテンツは複数の値です。
+ `name:type(single)[]` - これは矛盾しており、エラーがスローされます。
次のセクションでは、使用可能なすべての Gremlin データ型を示します。
## Gremlin データ型
これは許可されたプロパティタイプの一覧で、各タイプの説明を含みます。
**Bool (または Boolean)**
ブールフィールドであることを示しています。許可された値: `false`、`true`
**注記**
`true` 以外の値は false として扱われます。
**整数型**
定義された範囲外の値の場合、エラーが発生します。
|
|
| タイプ | Range |
| --- |--- |
| Byte | -128 to 127 |
| Short | -32768 to 32767 |
| Int | -2^31 to 2^31-1 |
| Long | -2^63 to 2^63-1 |
**10 進数型**
指数表記または 10 進表記の両方をサポートしています。また、(\$1/-) INFINITY や NaN などの記号も使用できます。INF はサポートされていません。
|
|
| タイプ | Range |
| --- |--- |
| Float | 32-bit IEEE 754 floating point |
| Double | 64-bit IEEE 754 floating point |
長すぎる浮動小数点数や倍精度浮動小数点数の値は、24 ビット (浮動小数点数) および 53 ビット (倍精度浮動小数点数) の精度で最も近い値にロードされ、丸められます。中間の値は、ビットレベルの最後の残りの桁で 0 に丸められます。
**String**
引用符はオプションです。カンマ、改行、およびキャリッジリターン文字は、二重引用符 (`"`) で囲まれた文字列に含まれると自動的にエスケープされます。*例*: `"Hello, World"`
引用符で囲まれた文字列に引用符を含めるには、行内で 2 つ使用して引用符をエスケープします。*例 :* `"Hello ""World"""`
文字列の配列は許可されますが、バックスラッシュを使用してエスケープされないり限配列内の文字列にはセミコロン (`;`) 文字を含めることはできません (次のように:`\;`)。
配列内の文字列を引用符で囲む場合は、配列全体を 1 組の引用符で囲む必要があります。*例*: `"String one; String 2; String 3"`
**日付**
ISO-8601 形式の Java の日付。`yyyy-MM-dd`、`yyyy-MM-ddTHH:mm`、`yyyy-MM-ddTHH:mm:ss`、`yyyy-MM-ddTHH:mm:ssZ` の形式がサポートされています。値はエポック時間に変換され、保存されます。
**Datetime**
ISO-8601 形式の Java の日付。`yyyy-MM-dd`、`yyyy-MM-ddTHH:mm`、`yyyy-MM-ddTHH:mm:ss`、`yyyy-MM-ddTHH:mm:ssZ` の形式がサポートされています。値はエポック時間に変換され、保存されます。
## Gremlin 行形式
**区切り記号**
行内のフィールドはカンマで区切られます。レコードは、改行またはキャリッジリターンとそれに続く改行で区切られます。
**空のフィールド**
空のフィールドは、必須ではない列 (ユーザー定義のプロパティなど) に許可されています。空のフィールドにもカンマ区切り記号が必要です。必須列のフィールドが空白の場合は、解析エラーが発生します。空の文字列値は、フィールドの空の文字列値として解釈され、空白のフィールドとしては解釈されません。次のセクションの例では、各頂点の例に空白のフィールドがあります。
**頂点 ID**
`~id` 値はすべての頂点ファイル内のすべての頂点に対して一意である必要があります。`~id` 値が同一の複数の頂点行はグラフの単一の頂点に適用されます。空の文字列 (`""`) は有効な ID であり、頂点は空の文字列を ID として作成されます。
**エッジ ID**
また、`~id` 値はすべてのエッジファイル内のすべてのエッジに対して一意である必要があります。`~id` 値が同一の複数のエッジ行はグラフの単一のエッジに適用されます。空の文字列 (`""`) は有効な ID であり、エッジは空の文字列を ID として作成されます。
**ラベル**
ラベルでは大文字と小文字が区別され、空にすることはできません。`""` の値を指定すると、エラーが発生します。
**文字列値**
引用符はオプションです。カンマ、改行、およびキャリッジリターン文字は、二重引用符 (`"`) で囲まれた文字列に含まれると自動的にエスケープされます。空の文字列値 `("")` は、空のフィールドとしてではなく、フィールドの空の文字列値として解釈されます。
## CSV 形式の仕様
Neptune CSV 形式は RFC 4180 の CSV の仕様に従い、次の要件を含みます。
+ Unix と Windows の両方のスタイルの行末処理がサポートされています (\$1n または \$1r\$1n)。
+ フィールドはすべて引用符で囲むことができます (二重引用符を使用)。
+ 改行、二重引用符、またはカンマを含むフィールドは、引用符で囲む必要があります。(そうでない場合、ロードは即座に中止されます)。
+ フィールド内の二重引用符文字 (`"`) は、2 つの二重引用符文字で示す必要があります。たとえば、データ内で、文字列 `Hello "World"` は、`"Hello ""World"""` であることが必要です。
+ 区切り記号間のスペースは無視されます。行が `value1, value2` である場合は、`"value1"` および `"value2"` として保存されます。
+ その他のエスケープ文字はすべてそのまま保存されます。たとえば、`"data1\tdata2"` であれば `"data1\tdata2"` として保存されます。これらの文字が引用符で囲まれている場合、これ以上エスケープする必要はありません。
+ 空のフィールドは許可されます。空白のフィールドは空の値と見なされます。
+ フィールドの複数の値は、値と値の間にセミコロン (`;`) を使用して指定します。
詳細については、Internet Engineering Task Force (IETF) ウェブサイトの、[CSV ファイルの一般形式と MIME タイプ](https://tools.ietf.org/html/rfc4180)を参照してください。
## Gremlin の例
次の図の例では、TinkerPop 最新グラフから取得した 2 つの頂点と、エッジの例を示しています。
![\[2 つの頂点と 1 つのエッジを描いた図には、marko 29 歳と、lop ソフトウェア Java 言語が含まれています。\]](http://docs.aws.amazon.com/ja_jp/neptune/latest/userguide/images/tiny-modern-graph.png)
以下に示しているのは、Neptune CSV ロード形式のグラフです。
頂点ファイル:
```
~id,name:String,age:Int,lang:String,interests:String[],~label
v1,"marko",29,,"sailing;graphs",person
v2,"lop",,"java",,software
```
頂点ファイルの表形式のビュー:
| | | | | | |
| --- |--- |--- |--- |--- |--- |
| \$1id | name:String | age:Int | lang:String | interests:String[] | \$1label |
| v1 | "marko" | 29 | | ["sailing", "graphs"] | person |
| v2 | "lop" | | "java" | | software |
エッジファイル:
```
~id,~from,~to,~label,weight:Double
e1,v1,v2,created,0.4
```
エッジファイルの表形式のビュー:
| | | | | |
| --- |--- |--- |--- |--- |
| \$1id | \$1from | \$1to | \$1label | weight:Double |
| e1 | v1 | v2 | created | 0.4 |
**次のステップ**
次に、ロード形式の詳細については、[例: Neptune DB インスタンスにデータをロードする](bulk-load-data.md) を参照してください。
# openCypher データのロード形式
openCypher CSV 形式を使用して openCypher データをロードするには、ノードとリレーションシップを別々のファイルで指定する必要があります。ローダーは、単一のロードジョブで、これらのノードファイルとリレーションシップファイルの複数のからロードできます。
各ロードコマンドは、ロードされる一連のファイルと同じAmazon Simple Storage Service バケットのパスプレフィックスを持つ必要があります。そのプレフィックスは始点パラメータで指定します。実際のファイル名と拡張子は重要ではありません。
Amazon Neptune では openCypher CSV 形式は RFC 4180 の CSV の仕様に従います。詳細については、Internet Engineering Task Force (IETF) ウェブサイトの、[CSV ファイルの一般形式と MIME タイプ](https://tools.ietf.org/html/rfc4180) (https://tools.ietf.org/html/rfc4180) を参照してください。
**注記**
これらのファイルは、UTF-8 形式でエンコードする必要があります。
各ファイルには、システム列ヘッダーとプロパティ列ヘッダーの両方を含むカンマ区切りのヘッダー行があります。
## openCypher データロードファイルのシステム列ヘッダー
特定のシステム列は、各ファイルに 1 回のみ表示できます。すべてのシステム列ヘッダーラベルで、大文字と小文字が区別されます。
openCypher ノードのロードファイルおよびリレーションシップロードファイルでは、必須および許可されるシステム列ヘッダーが異なります。
### ノードファイル内のシステム列ヘッダー
+ **`:ID`** — (必須) ノードの ID。
オプションの ID スペースを `:ID(ID Space)` のように、ノード `:ID` 列ヘッダーに追加できます。例は `:ID(movies)` です。
このファイル内のノードを接続するリレーションシップをロードするときは、リレーションシップファイルの `:START_ID` および/または `:END_ID` 列で同じ ID スペースを使用します。
ノード `:ID` はオプションで、フォーム、`property name:ID` にプロパティとして格納できます。例は `name:ID` です。
ノード ID は、現在および以前のロードのすべてのノードファイルで一意である必要があります。ID スペースを使用する場合、ノード ID は、現在のロードと以前のロードで同じ ID スペースを使用するすべてのノードファイルで一意である必要があります。
+ **`:LABEL`** — ノードのラベル。
1 つのノードに複数のラベル値を使用する場合は、各ラベルをセミコロン (`;`) で区切る必要があります。
### リレーションシップファイル内のシステム列ヘッダー
+ **`:ID`** — リレーションシップの ID。これは、`userProvidedEdgeIds` が true (デフォルト) である場合に必要ですが、`userProvidedEdgeIds` が `false` の場合は無効となります。
リレーションシップ ID は、現在および以前のロードのすべてのリレーションシップファイルで一意である必要があります。
+ **`:START_ID`** — (*必須*) このリレーションシップが始まるノードのノード ID。
必要に応じて、ID スペースをフォーム `:START_ID(ID Space)` の開始 ID 列に関連付けることができます。開始ノード ID に割り当てられた ID スペースは、ノードファイル内のノードに割り当てられている ID スペースと一致する必要があります。
+ **`:END_ID`** — (*必須*) このリレーションシップが終了するノードのノード ID。
必要に応じて、ID スペースをフォーム `:END_ID(ID Space)` の終了 ID 列に関連付けることができます。終了ノード ID に割り当てられた ID スペースは、ノードファイル内のノードに割り当てられた ID スペースと一致する必要があります。
+ **`:TYPE`** — リレーションシップのタイプ。リレーションシップには、単一タイプのみを含めることができます。
**注記**
一括ロードプロセスで重複するノードまたはリレーションシップ ID がどのように処理されるかについては、[openCypher データをロードする](load-api-reference-load.md#load-api-reference-load-parameters-opencypher) を参照してください。
### openCypher データロードファイルのプロパティ列ヘッダー
次の形式のプロパティ列ヘッダーを使用して、列が特定のプロパティの値を保持するように指定できます。
```
propertyname:type
```
列ヘッダーでは、スペース、カンマ、キャリッジリターン、改行文字は使用できません。そのため、プロパティ名にこれらの文字を使用することはできません。以下に示しているのは、タイプ `Int` の `age` という名前のプロパティの列ヘッダーの例です。
```
age:Int
```
列ヘッダーとして `age:Int` がある列は、すべての行に整数または空の値を含める必要があります。
## Neptune openCypher データロードファイルのデータ型
+ **`Bool`** または **`Boolean`** — ブールフィールド。指定できる値は `true` と `false` です。
`true` 以外の値は `false` として扱われます。
+ **`Byte`** — `-128` から `127` 範囲内の整数。
+ **`Short`** — `-32,768` から `32,767` 範囲内の整数。
+ **`Int`** — `-2^31` から `2^31 - 1` 範囲内の整数。
+ **`Long`** — `-2^63` から `2^63 - 1` 範囲内の整数。
+ **`Float`** — 32 ビット IEEE 754 浮動小数点数。十進表記と科学記法の両方がサポートされています。`Infinity`、`-Infinity` および `NaN` はすべて認識されますが、`INF` はされません。
桁数が多すぎて収まらない値は、最も近い値に丸められます (中間の値は、ビットレベルの最後の残りの桁で 0 に丸められます)。
+ **`Double`** — 64 ビット IEEE 754 浮動小数点数。十進表記と科学記法の両方がサポートされています。`Infinity`、`-Infinity` および `NaN` はすべて認識されますが、`INF` はされません。
桁数が多すぎて収まらない値は、最も近い値に丸められます (中間の値は、ビットレベルの最後の残りの桁で 0 に丸められます)。
+ **`String`** - 引用符はオプションです。カンマ、改行、およびキャリッジリターン文字は、`"Hello, World"` のような二重引用符 (`"`) で囲まれた文字列に含まれると自動的にエスケープされます。
引用符で囲まれた文字列に引用符を含めるには、`"Hello ""World"""` のように、行内で 2 つ使用してください。
+ **`DateTime`** — 次のいずれかの ISO-8601 形式の Java 日付。
+ `yyyy-MM-dd`
+ `yyyy-MM-ddTHH:mm`
+ `yyyy-MM-ddTHH:mm:ss`
+ `yyyy-MM-ddTHH:mm:ssZ`
### Neptune openCypher データロードファイルのオートキャストデータ型
オートキャストデータ型は、現在 Neptune がネイティブにサポートしていないデータ型をロードするために提供されます。このような列のデータは文字列として保存され、意図した形式に対する検証は行われません。次のオートキャストデータ型を使用できます。
+ **`Char`** — `Char` フィールド。文字列として格納されます。
+ **`Date`**、**`LocalDate`** および **`LocalDateTime`**、 — `date`、`localdate` および `localdatetime` タイプの説明については、[Neo4j 一時的インスタント](https://neo4j.com/docs/cypher-manual/current/values-and-types/temporal/#cypher-temporal-instants)を参照してください。値は、検証なしで文字列として逐語的にロードされます。
+ **`Duration`** — [Neo4j デュレーション形式](https://neo4j.com/docs/cypher-manual/current/values-and-types/temporal/#cypher-temporal-durations)を参照してください。値は、検証なしで文字列として逐語的にロードされます。
+ **ポイント** — 空間データを格納するためのポイントフィールド。「[空間インスタント](https://neo4j.com/docs/cypher-manual/current/values-and-types/spatial/#spatial-values-spatial-instants)」を参照してください。値は、検証なしで文字列として逐語的にロードされます。
## openCypher ロードフォーマットの例
次の図では、TinkerPop 最新グラフから取得した 2 つの頂点と、リレーションシップの例を示しています。
![\[2 つのノードとそれらのリレーションシップの図表。\]](http://docs.aws.amazon.com/ja_jp/neptune/latest/userguide/images/tinkerpop-2-nodes-and-relationship.png)
以下に示しているのは、通常の Neptune openCypher ロード形式のグラフです。
**ノードファイル:**
```
:ID,name:String,age:Int,lang:String,:LABEL
v1,"marko",29,,person
v2,"lop",,"java",software
```
**リレーションシップファイル:**
```
:ID,:START_ID,:END_ID,:TYPE,weight:Double
e1,v1,v2,created,0.4
```
または、次のようにプロパティとして ID スペースと ID を使用することもできます。
**最初のノードファイル:**
```
name:ID(person),age:Int,lang:String,:LABEL
"marko",29,,person
```
**2 番目のノードファイル:**
```
name:ID(software),age:Int,lang:String,:LABEL
"lop",,"java",software
```
**リレーションシップファイル:**
```
:ID,:START_ID(person),:END_ID(software),:TYPE,weight:Double
e1,"marko","lop",created,0.4
```
# RDF ロードデータ形式
Resource Description Framework (RDF) データをロードするには、World Wide Web Consortium (W3C) によって指定されている次の標準形式のいずれかを使用できます。
+ N -Triples (`ntriples`) [https://www.w3.org/TR/n-triples/](https://www.w3.org/TR/n-triples/) の仕様より。
+ N-Quads (`nquads`) [https://www.w3.org/TR/n-quads/](https://www.w3.org/TR/n-quads/) の仕様より
+ RDF/XML (`rdfxml`) [https://www.w3.org/TR/rdf-syntax-grammar/](https://www.w3.org/TR/rdf-syntax-grammar/) の仕様より
+ Turtle (`turtle`) [https://www.w3.org/TR/turtle/](https://www.w3.org/TR/turtle/) の仕様より
**重要**
すべてのファイルは、UTF-8 形式でエンコードする必要があります。
Unicode 文字を含む N-Quads および N-Triples データの場合、`\uxxxxx` エスケープシーケンスがサポートされています。ただし、Neptune では正規化はサポートされていません。正規化が必要な値が存在する場合、クエリ中にバイトごとに一致することはありません。正規化の詳細については、[Unicode.org](https://unicode.org/faq/normalization.html) の[正規化](https://unicode.org)ページを参照してください。
**次のステップ**
次に、ロード形式の詳細については、[例: Neptune DB インスタンスにデータをロードする](bulk-load-data.md) を参照してください。
# 例: Neptune DB インスタンスにデータをロードする
この例では、Amazon Neptune にデータをロードする方法を示しています。別途指定されていない限り、Neptune DB インスタンスと同じ Amazon Virtual Private Cloud (VPC) の Amazon Elastic Compute Cloud (Amazon EC2) インスタンスからの手順に従います。
## データをロードする例の前提条件
始めるには以下のものが必要です。
+ Neptune DB インスタンス。
Neptune DB インスタンスの起動方法についての詳細は、[Amazon Neptune クラスターの作成](get-started-create-cluster.md) を参照してください。
+ データファイルを入れる Amazon Simple Storage Service (Amazon S3) バケット。
既存のバケットを使用することもできます。S3 バケットがない場合は、*[Amazon S3 入門ガイド](https://docs.aws.amazon.com/AmazonS3/latest/userguide/)*の[バケットの作成](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html)を参照してください。
+ ロードするグラフデータ (Neptune ローダーでサポートされている形式のいずれか):
Gremlin を使用してグラフのクエリを実行している場合、Neptune では、[Gremlin ロードデータ形式](bulk-load-tutorial-format-gremlin.md) の説明に従って、カンマ区切り値 (`CSV`) 形式でデータをロードできます。
openCypher を使用してグラフのクエリを実行している場合、Neptune では、[openCypher データのロード形式](bulk-load-tutorial-format-opencypher.md) の説明に従って、openCypher 固有の `CSV` 形式でデータをロードすることもできます。
SPARQL を使用している場合、Neptune は多くの RDF 形式でデータをロードできます ([RDF ロードデータ形式](bulk-load-tutorial-format-rdf.md) を参照)。
+ S3 バケット内のデータファイルへのアクセスを許可する IAM ポリシーが設定されている Neptune DB インスタンスの IAM ロール。このポリシーが読み取りとリストアクセス許可を付与する必要があります。
Amazon S3 にアクセスできるロールを作成し、Neptune クラスターに関連付ける方法の詳細については、[前提条件: IAM ロールと Amazon S3 アクセス](bulk-load-tutorial-IAM.md) を参照してください。
**注記**
Neptune `Load` API はデータファイルへの読み取りアクセスが必要です。IAM ポリシーに書き込みアクセスまたはバケット全体へのアクセスを許可する必要はありません。
+ Amazon S3 VPC エンドポイント 詳細については「[Amazon S3 VPC エンドポイントの作成](#bulk-load-prereqs-s3)」セクションを参照してください。
### Amazon S3 VPC エンドポイントの作成
Neptune ローダーには Amazon S3 の VPC エンドポイントが必要です。
**Amazon S3 のアクセスをセットアップするには**
1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/) で Amazon VPC コンソールを開きます。
1. 左のナビゲーションペインで [**エンドポイント**] を選択してください。
1. **エンドポイントの作成** を選択します。
1. [**Service Name**] (サービス名) `com.amazonaws.region.s3` を選択します。
**注記**
このリージョンが正しくない場合は、コンソールのリージョンが正しいことを確認してください。
1. [VPC] で、Neptune DB インスタンスが含まれている VPC を選択します。
1. クラスターに関連するサブネットに関連付けられているルートテーブルの横にあるチェックボックスをオンにします。ルートテーブルが 1 つだけの場合は、そのボックスを選択する必要があります。
1. **エンドポイントの作成** を選択します。
エンドポイント作成の詳細については、*Amazon VPC ユーザーガイド*の [VPC エンドポイント](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html#create-vpc-endpoint)を参照してください。VPC エンドポイントの制限については、[Amazon S3 の VPC エンドポイント](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-s3.html)を参照してください。
**Neptune DB インスタンスにデータをロードするには**
1. データファイルを Amazon S3 バケットにコピーします。S3 バケットは、データをロードするクラスターと同じ AWS リージョンに存在する必要があります。
次の AWS CLI コマンドを使用して、ファイルをバケットにコピーできます。
**注記**
このコマンドは、Amazon EC2 インスタンスから実行する必要はありません。
```
aws s3 cp data-file-name s3://bucket-name/object-key-name
```
**注記**
Amazon S3 で、**オブジェクトキー名**は、ファイル名を含むファイルの完全なパスです。
*例:* コマンド `aws s3 cp datafile.txt s3://examplebucket/mydirectory/datafile.txt` では、オブジェクトキー名は **`mydirectory/datafile.txt`** です。
または、 を使用して AWS マネジメントコンソール S3 バケットにファイルをアップロードすることもできます。Amazon S3 コンソール ([https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)) を開きバケットを選択ます。左上隅の [**Upload**] (アップロード) を選択して、ファイルをアップロードします。
1. コマンドラインウィンドウから次のように入力し、エンドポイント、Amazon S3 パス、フォーマット、IAM ロール ARN の正しい値を使用して Neptune ローダーを実行します。
`format` パラメータには、Gremlin の場合は `csv`、openCypher の場合は `opencypher`、または RDF の場合は `ntriples`、`nquads`、`turtle`、および `rdfxml` のいずれかの値を指定できます。他のパラメータについての詳細は、「[Neptune ローダーコマンド](load-api-reference-load.md)」を参照してください。
Neptune DB インスタンスのホスト名を見つける方法については、[Amazon Neptune エンドポイントに接続する](feature-overview-endpoints.md) セクションを参照してください。
region パラメータの値はクラスターおよび S3 バケットのリージョンと一致する必要があります。
Amazon Neptune は、次の AWS リージョンで利用できます。
+ 米国東部 (バージニア北部): `us-east-1`
+ 米国東部 (オハイオ): `us-east-2`
+ 米国西部 (北カリフォルニア): `us-west-1`
+ 米国西部 (オレゴン): `us-west-2`
+ カナダ (中部): `ca-central-1`
+ カナダ西部 (カルガリー): `ca-west-1`
+ 南米 (サンパウロ): `sa-east-1`
+ 欧州 (ストックホルム): `eu-north-1`
+ 欧州 (スペイン): `eu-south-2`
+ 欧州 (アイルランド): `eu-west-1`
+ 欧州 (ロンドン): `eu-west-2`
+ 欧州 (パリ): `eu-west-3`
+ 欧州 (フランクフルト): `eu-central-1`
+ 中東 (バーレーン): `me-south-1`
+ 中東 (アラブ首長国連邦): `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-southeast-3`
+ アジアパシフィック (メルボルン): `ap-southeast-4`
+ アジアパシフィック (マレーシア): `ap-southeast-5`
+ アジアパシフィック (ムンバイ): `ap-south-1`
+ アジアパシフィック (ハイデラバード): `ap-south-2`
+ 中国 (北京): `cn-north-1`
+ 中国 (寧夏): `cn-northwest-1`
+ AWS GovCloud (米国西部): `us-gov-west-1`
+ AWS GovCloud (米国東部): `us-gov-east-1`
```
curl -X POST \
-H 'Content-Type: application/json' \
https://your-neptune-endpoint:port/loader -d '
{
"source" : "s3://bucket-name/object-key-name",
"format" : "format",
"iamRoleArn" : "arn:aws:iam::account-id:role/role-name",
"region" : "region",
"failOnError" : "FALSE",
"parallelism" : "MEDIUM",
"updateSingleCardinalityProperties" : "FALSE",
"queueRequest" : "TRUE",
"dependencies" : ["load_A_id", "load_B_id"]
}'
```
Neptune クラスターへの IAM ロールの作成と関連付けの詳細については、[前提条件: IAM ロールと Amazon S3 アクセス](bulk-load-tutorial-IAM.md) を参照してください。
**注記**
ロードリクエストパラメータの詳細については、[Neptune ローダーのリクエストパラメータ](load-api-reference-load.md#load-api-reference-load-parameters) を参照してください。概要:
`source` パラメータは、単一のファイルまたはフォルダを指す Amazon S3 URl を受け取ります。フォルダを指定すると、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`
この `format` パラメータは、次のいずれかになります。
Gremlin プロパティグラフの Gremlin CSV 形式 (`csv`)
openCypher プロパティグラフの openCypher CSV 形式 (`opencypher`)
RDF の N -Triples (`ntriples`) 形式 / SPARQL
RDF の N-Quads (`nquads`) 形式 / SPARQL
RDF の RDF/XML (`rdfxml`) 形式 / SPARQL
RDF の Turtle (`turtle`) 形式 / SPARQL
オプションの `parallelism` パラメータを使用すると、バルクロードプロセスで使用されるスレッドの数を制限できます。`LOW`、`MEDIUM`、`HIGH`、または `OVERSUBSCRIBE` に設定できます。
`updateSingleCardinalityProperties` を `"FALSE"` に設定すると、エッジまたは単一カーディナリティ頂点プロパティにロードされているソースファイルに複数の値が指定されている場合、ローダーはエラーを返します。
`queueRequest` を `"TRUE"` に設定すると、ロードジョブが既に実行されている場合、キューにロードリクエストが配置されます。
`dependencies` パラメータは、既にキューに配置されている 1 つ以上のロードジョブが正常に完了した場合に、ロードリクエストを実行します。
1. Neptune ローダーは、ステータスを確認したり、ロードプロセスをキャンセルしたりできるジョブ `id` を返します。
```
{
"status" : "200 OK",
"payload" : {
"loadId" : "ef478d76-d9da-4d94-8ff1-08d9d4863aa5"
}
}
```
1. **ステップ 3** の `loadId` でロードのステータスを取得するには、次のように入力します。
```
curl -G 'https://your-neptune-endpoint:port/loader/ef478d76-d9da-4d94-8ff1-08d9d4863aa5'
```
ロードのステータスにエラーが表示されている場合は、より詳細なステータスとエラーのリストをリクエストできます。詳細な説明と例については、[Neptune Loader Get-Status API](load-api-reference-status.md) を参照してください。
1. (オプション) `Load` ジョブをキャンセルします。
**ステップ 3 ** のジョブからの `id` とともに、次の `Delete` をローダージョブに入力します。
```
curl -X DELETE 'https://your-neptune-endpoint:port/loader/ef478d76-d9da-4d94-8ff1-08d9d4863aa5'
```
この `DELETE` コマンドを使用すると、キャンセルが成功したときに HTTP コード `200 OK` が返されます。
ロードが完了したロードジョブのファイルからのデータはロールバックされません。データは Neptune DB インスタンスに残ります。
# Amazon Neptune 一括ロードの最適化
Neptune 一括ロードのロード時間を最小限に抑えるには、次の方法を使用します。
+ **データを消去します。**
+ データを必ずロードする前に[サポートされているデータ形式](bulk-load-tutorial-format.md)へ変換してください。
+ 重複または既知のエラーをすべて削除します。
+ 一意の述語 (エッジや頂点のプロパティなど) の数をできるだけ減らします。
+ **ファイルを最適化します:**
+ Amazon S3 バケットから CSV ファイルなどの大きなファイルをロードする場合、ローダーはそれらを並行してロードできるチャンクに解析することによって同時性を管理します。非常に多くの小さなファイルを使用すると、このプロセスが遅くなる可能性があります。
+ Amazon S3 プレフィックスから複数のファイルをロードする場合、ローダーは最初に頂点ファイルをロードし、次にエッジファイルをロードします。ただし、エッジファイルのみをロードすることがわかっている場合は、`edgeOnlyLoad` を `TRUE` に設定して、すべてのファイルがスキャンされる最初のパスをスキップしてコンテンツ (頂点またはエッジ) を判別し、検出された頂点ファイルがエッジファイルの前にロードされるようにできます。これにより、特に多くのエッジファイルが関係している場合に、ロード時間を大幅に短縮できます。一部の頂点ファイルが同じ Amazon S3 プレフィックス (`source` パラメータ) にも存在する場合、それらはロードされますが、他のファイルに対する順序の保証はありません。また、データベースに一部の `from` または `to` の頂点が存在しない場合、エッジ挿入でメッセージ `FROM_OR_TO_VERTEX_ARE_MISSING` によりエラーが報告される可能性があります。ベストプラクティスとして、ノードとエッジを個別の Amazon S3 プレフィックスに配置します。
+ **ローダーの設定を確認します。**
+ ロード中に他の操作を行う必要がない場合は、[`OVERSUBSCRIBE``parallelism`](load-api-reference-load.md#load-api-reference-load-syntax) パラメータを使用します。このパラメータ設定では、一括ローダーは、実行時に使用可能なすべての CPU リソースを使用するようになります。一般に、I/O 制約が許す限り速くオペレーションを実行し続けるには、CPU 容量の 60%～70% が必要です。
**注記**
`parallelism` が `OVERSUBSCRIBE` または `HIGH` (デフォルト設定) に設定されていると、openCypher データをロードするときに、スレッドが競合状態となりデッドロックが発生する可能性があり、`LOAD_DATA_DEADLOCK` というエラーが表示されます。この場合は、`parallelism` を低い設定にして、ロードを再試行します。
+ ロードジョブに複数のロードリクエストが含まれる場合は、`queueRequest` パラメータを使用します。`queueRequest` を `TRUE` に設定すると、Neptune はリクエストをキューに入れるので、別のリクエストを発行する前にリクエストが完了するのを待つ必要がありません。
+ ロードリクエストがキューに入れられている場合は、`dependencies` パラメータを指定すると、1 つのジョブが失敗すると、依存ジョブが失敗します。これにより、ロードされたデータの不整合を防ぐことができます。
+ ロードジョブで以前にロードされた値の更新が含まれる場合は、必ず `updateSingleCardinalityProperties` パラメータを `TRUE` に設定してください。そうでない場合、ローダーは既存の単一カーディナリティ値の更新試行をエラーとして扱います。Gremlin データの場合、カーディナリティはプロパティの列ヘッダーにも指定されます ([プロパティ列ヘッダー](bulk-load-tutorial-format-gremlin.md#bulk-load-tutorial-format-gremlin-propheaders))。
**注記**
`updateSingleCardinalityProperties` パラメータは Resource Description Framework (RDF) データには使用できません。
+ `failOnError` パラメータを使用して、エラーが発生したときにバルクロード操作が失敗するか、続行するかを決定します。また、`mode` パラメータを使用して、ロードジョブが既にロードされたデータをリロードするのではなく、前のジョブが失敗した時点からロードを再開するようにします。
+ **スケールアップ** — 一括ロードする前に、DB クラスターのライターインスタンスを最大サイズに設定します。この場合、DB クラスター内のリードレプリカインスタンスもスケールアップするか、データのロードが完了するまで削除する必要があります。
一括ロードが完了したら、ライターインスタンスを再度スケールダウンしてください。
**重要**
一括ロード中のレプリケーション遅延が原因で、リードレプリカが繰り返し再起動されるサイクルが発生した場合、レプリカは DB クラスター内のライターに追いつけない可能性があります。リーダーをライターよりも大きくするか、一括ロード中にリーダーを一時的に削除し、完了後に再作成してください。
ローダーリクエストパラメータ設定の詳細については、[リクエストパラメーター](load-api-reference-load.md#load-api-reference-load-parameters) を参照してください。
# Neptune ローダーリファレンス
このセクションでは、Neptune DB インスタンスの HTTP エンドポイントから利用可能な Amazon Neptune の `Loader` API について説明します。
**注記**
エラー発生時にローダーから返されるエラーおよびフィードメッセージのリストについては、[Neptune ローダーのエラーおよびフィードメッセージ](loader-message.md) を参照してください。
**Contents**
+ [Neptune ローダーコマンド](load-api-reference-load.md)
+ [Neptune ローダーリクエストの構文](load-api-reference-load.md#load-api-reference-load-syntax)
+ [Neptune ローダーのリクエストパラメータ](load-api-reference-load.md#load-api-reference-load-parameters)
+ [openCypher データのロードに関する特別な考慮事項](load-api-reference-load.md#load-api-reference-load-parameters-opencypher)
+ [Neptune ローダーレスポンスの構文](load-api-reference-load.md#load-api-reference-load-return)
+ [Neptune ローダーエラー](load-api-reference-load-errors.md)
+ [Neptune ローダーの例](load-api-reference-load-examples.md)
+ [Neptune Loader Get-Status API](load-api-reference-status.md)
+ [Neptune Loader Get-Status リクエスト](load-api-reference-status-requests.md)
+ [Loader Get-Status リクエストの構文](load-api-reference-status-requests.md#load-api-reference-status-request-syntax)
+ [Neptune Loader Get-Status リクエストパラメータ](load-api-reference-status-requests.md#load-api-reference-status-parameters)
+ [Neptune Loader Get-Status レスポンス](load-api-reference-status-response.md)
+ [Neptune Loader Get-Status レスポンスのレイアウト](load-api-reference-status-response.md#load-api-reference-status-response-layout)
+ [Neptune Loader Get-Status `overallStatus` および `failedFeeds` レスポンスオブジェクト](load-api-reference-status-response.md#load-api-reference-status-response-objects)
+ [Neptune Loader Get-Status `errors` レスポンスオブジェクト](load-api-reference-status-response.md#load-api-reference-status-errors)
+ [Neptune Loader Get-Status `errorLogs` レスポンスオブジェクト](load-api-reference-status-response.md#load-api-reference-error-logs)
+ [Neptune Loader Get-Status の例](load-api-reference-status-examples.md)
+ [ロードステータスのリクエスト例](load-api-reference-status-examples.md#load-api-reference-status-examples-status-request)
+ [loadId のリクエストの例](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 Loader 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 Loader Cancel Job](load-api-reference-cancel.md)
+ [ジョブキャンセルリクエストの構文](load-api-reference-cancel.md#load-api-reference-cancel-syntax)
+ [ジョブキャンセルリクエストのパラメータ](load-api-reference-cancel.md#load-api-reference-cancel-parameters)
+ [ジョブキャンセルレスポンスの構文](load-api-reference-cancel.md#load-api-reference-cancel-parameters-response)
+ [ジョブキャンセルエラー](load-api-reference-cancel.md#load-api-reference-cancel-parameters-errors)
+ [ジョブキャンセルエラーメッセージ](load-api-reference-cancel.md#load-api-reference-cancel-parameters-errors-messages)
+ [ジョブキャンセルの例](load-api-reference-cancel.md#load-api-reference-cancel-examples)
# Neptune ローダーコマンド
Amazon S3 バケットから Neptune DB インスタンスにデータをロードします。
データをロードするには、`POST` エンドポイントに、HTTP `https://your-neptune-endpoint:port/loader` リクエストを送信する必要があります。`loader` リクエストのパラメータは、`POST` 本文、または URL エンコードされたパラメータとして送信できます。
**重要**
MIME タイプは、`application/json` である必要があります。
Amazon S3 バケットは、クラスターと同じ AWS リージョンにある必要があります。
**注記**
Amazon S3 `SSE-S3` モードを使用して暗号化されている場合は、Amazon S3 から暗号化されたデータを読み込むことができます。その場合、Neptune はユーザーの認証情報を偽装し、ユーザーに代わって `s3:getObject` 呼び出しを発行することができます。
また、IAM ロールに AWS KMSにアクセスするために必要なアクセス権限が含まれている限り、`SSE-KMS` モードを使用して暗号化された Amazon S3 から、暗号化されたデータをロードすることもできます。適切な AWS KMS アクセス許可がない場合、一括ロードオペレーションは失敗し、`LOAD_FAILED`レスポンスを返します。
Neptune は現在 `SSE-C` モードを使用して暗号化された Amazon S3 データのロードをサポートしていません。
別のジョブを開始する前に、1 つのロードジョブが完了するのを待つ必要はありません。Neptune は、`queueRequest` パラメータがすべて `"TRUE"` に設定されている場合、一度に最大 64 個のロードリクエストをキューに入れることができます。ジョブのキューの順序は、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"]
}
```
**edgeOnlyLoad 構文**
`edgeOnlyLoad` の場合、構文は次のとおりです。
```
{
"source" : "string",
"format" : "string",
"iamRoleArn" : "string",
"mode": "NEW|RESUME|AUTO",
"region" : "us-east-1",
"failOnError" : "string",
"parallelism" : "string",
"edgeOnlyLoad" : "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 S3 URI。
`SOURCE` パラメータは、単一のファイル、複数のファイル、1 つのフォルダ、または複数のフォルダを識別する Amazon S3 URI を受け入れます。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`
URI の `object-key-name` 要素は、Amazon S3 の [ListObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html) API コール内の[プレフィックス](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html#API_ListObjects_RequestParameters)パラメータと同等です。これは、名前がそのプレフィックスで始まる指定された Amazon S3 バケット内のすべてのオブジェクトを識別します。これは、単一のファイルまたはフォルダ、または複数のファイルやフォルダにすることができます。
特定のフォルダには複数の頂点ファイルおよび複数のエッジファイルが含まれている場合があります。
例えば、`bucket-name` という名前の Amazon S3 バケットに次のフォルダ構造とファイルがある場合については、次のとおりです。
```
s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade
s3://bucket-name/bcd
```
ソースパラメータが `s3://bucket-name/a` として指定されている場合は、最初の 3 つのファイルがロードされます。
```
s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade
```
+ **`format`** - データの形式。Neptune `Loader` コマンドのデータ形式の詳細については、[Amazon Neptune 一括ローダーを使用したデータの取り込み](bulk-load.md) を参照してください。
**許可される値**
+ **`csv`** [Gremlin CSV データ形式用](bulk-load-tutorial-format-gremlin.md)。
+ **`opencypher`** [openCypher CSV データ形式用](bulk-load-tutorial-format-opencypher.md)。
+ **`ntriples`** [N-Triples RDF データ形式用](https://www.w3.org/TR/n-triples/)。
+ **`nquads`** [N-Quads RDF データ形式用](https://www.w3.org/TR/n-quads/)。
+ **`rdfxml`** [RDF\$1XML RDF データ形式用](https://www.w3.org/TR/rdf-syntax-grammar/)。
+ **`turtle`** [Turtle RDF データ形式用](https://www.w3.org/TR/turtle/)。
+ **`iamRoleArn`** - S3 バケットにアクセスするために、Neptune DB インスタンスによって想定される IAM ロールの Amazon リソースネーム (ARN)。Amazon S3 にアクセスできるロールを作成し、Neptune クラスターに関連付ける方法の詳細については、[前提条件: IAM ロールと Amazon S3 アクセス](bulk-load-tutorial-IAM.md) を参照してください。
[エンジンリリース 1.2.1.0.R3](engine-releases-1.2.1.0.R3.md) 以降、Neptune DB インスタンスと Amazon S3 バケットが異なる AWS アカウントにある場合、複数の IAM ロールを連鎖させることもできます。この場合、[Amazon Neptune で IAM ロールを連鎖する](bulk-load-tutorial-chain-roles.md) で説明されているように、`iamRoleArn` にはロール ARN のカンマ区切りのリストが含まれます。例えば、次のようになります。
```
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`
+ カナダ西部 (カルガリー): `ca-west-1`
+ 南米 (サンパウロ): `sa-east-1`
+ 欧州 (ストックホルム): `eu-north-1`
+ 欧州 (スペイン): `eu-south-2`
+ 欧州 (アイルランド): `eu-west-1`
+ 欧州 (ロンドン): `eu-west-2`
+ 欧州 (パリ): `eu-west-3`
+ 欧州 (フランクフルト): `eu-central-1`
+ 中東 (バーレーン): `me-south-1`
+ 中東 (アラブ首長国連邦): `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-southeast-3`
+ アジアパシフィック (メルボルン): `ap-southeast-4`
+ アジアパシフィック (マレーシア): `ap-southeast-5`
+ アジアパシフィック (ムンバイ): `ap-south-1`
+ アジアパシフィック (ハイデラバード): `ap-south-2`
+ 中国 (北京): `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` モードの場合と同様に、ソースからすべてのデータがロードされます。
+ **`edgeOnlyLoad`** – 一括ロード中のファイル処理順序を制御するフラグ。
*使用できる値*: `"TRUE"`、`"FALSE"`。
*デフォルト値*: `"FALSE"`。
このパラメータを「FALSE」に設定すると、ローダーは最初に頂点ファイルを自動的にロードし、次にエッジファイルをロードします。これは、まずすべてのファイルをスキャンしてそれらの内容 (頂点またはエッジ) を判別することによって行われます。このパラメータを「TRUE」に設定すると、ローダーは最初のスキャンフェーズをスキップし、すべてのファイルを表示されている順序で直ちにロードします。詳細については、「[一括ロードの最適化](https://docs.aws.amazon.com//neptune/latest/userguide/bulk-load-optimize.html)」を参照してください。
+ **`failOnError`** - エラー時に完全な停止を切り替えるフラグ。
*使用できる値*: `"TRUE"`、`"FALSE"`。
*デフォルト値*: `"TRUE"`。
このパラメータを `"FALSE"` に設定すると、ローダーは指定された場所のすべてのデータをロードし、エラーのあるエントリはスキップします。
このパラメータを `"TRUE"` に設定すると、ローダーはエラー発生時にすぐに停止します。その時点までロードされたデータは保持されます。
+ **`parallelism`** - これは、一括ロードプロセスで使用されるスレッド数を減らすように設定することができるオプションのパラメータです。
*許可される値:*
+ `LOW` - 使用されるスレッドの数は、コア数を 8 で割った値です。
+ `MEDIUM` - 使用されるスレッドの数は、コア数を 2 で割った値です。
+ `HIGH` - 使用されるスレッドの数は、コア数と同じです。
+ `OVERSUBSCRIBE` - 使用されるスレッドの数は、コア数に 2 をかけた値です。この値を使用する場合、バルクローダーは利用可能なすべてのリソースを消費します。
ただし、これは、`OVERSUBSCRIBE` 設定すると、CPU 使用率が 100% になります。ロードオペレーションは I/O バウンドであるため、予想される CPU 最高使用率は 60%～70% の範囲にあります。
*デフォルト値*: `HIGH`
`parallelism` openCypher データをロードするときに、設定によってスレッド間でデッドロックが発生することがあります。こうなると、Neptune は `LOAD_DATA_DEADLOCK` というエラーを返します。通常、この問題は次のようにして修正できます。`parallelism` より低い設定にし、ロードコマンドを再試行します。
+ **`parserConfiguration`** - 追加のパーサー設定値のあるオプションのオブジェクト。それぞれの子パラメータもオプションです。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/neptune/latest/userguide/load-api-reference-load.html)
詳細については、「[SPARQL デフォルトグラフと名前が付いたグラフ](feature-sparql-compliance.md#sparql-default-graph)」を参照してください。
+ **`updateSingleCardinalityProperties`** - これは、バルクローダーが単一濃度の頂点またはエッジプロパティの新しい値を処理する方法を制御するオプションのパラメータです。これは openCypher データのロードではサポートされていません ([openCypher データをロードする](#load-api-reference-load-parameters-opencypher) を参照)。
*使用できる値*: `"TRUE"`、`"FALSE"`。
*デフォルト値*: `"FALSE"`。
デフォルトでは、または `updateSingleCardinalityProperties` が明示的に `"FALSE"` に設定されている場合、ローダーは単一の濃度に違反するため、新しい値をエラーとして扱います。
一方、`updateSingleCardinalityProperties` が `"TRUE"` に設定されている場合、バルクローダーは既存の値を新しい値に置き換えます。ロードされるソースファイルで複数のエッジまたは単一濃度の頂点プロパティ値が指定されている場合、バルクロードの終了時の最終値は、これらの新しい値のいずれかになります。ローダーは、既存の値が新しい値の 1 つに置き換えられたことを保証します。
+ **`queueRequest`** - これは、ロードリクエストをキューに入れることができるかどうかを示すオプションのフラグパラメータです。
`queueRequest` パラメータをすべて `"TRUE"`に設定している場合、Neptune は一度に最大 64 個のジョブをキューに入れることができるので、次のジョブを発行する前に 1 つのロードジョブが完了するのを待つ必要はありません。ジョブのキューの順序は、FIFO (先入れ先出し) です。
`queueRequest` パラメータを省略するるか、`"FALSE"` に設定した場合、別のロードジョブが既に実行されていると、ロードリクエストは失敗します。
*使用できる値*: `"TRUE"`、`"FALSE"`。
*デフォルト値*: `"FALSE"`。
+ **`dependencies`** - これは、キュー内の 1 つ以上の前のジョブが正常に完了することを条件に、キューに入れられたロードリクエストを作成することができるオプションのパラメータです。
Neptune は、`queueRequest` パラメータが `"TRUE"` に設定されている場合、一度に最大 64 個のロードリクエストをキューに入れることができます。`dependencies` パラメータを使用すると、キュー内で指定された 1 つ以上前のリクエストが正常に完了したかどうかに応じて、キューに入れられたそのようなリクエストを実行できます。
たとえば、ロード `Job-A` と `Job-B` が互いに独立しているものの、ロード `Job-C` を開始する前に `Job-A` および `Job-B` を終了する必要がある場合は、次の手順を実行します。
1. 任意の順序で `load-job-A` と `load-job-B` を 1 つずつ送信し、load-id を保存します。
1. `dependencies` フィールドで 2 つのジョブの load-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` に設定されます。
この方法で複数のレベルの依存関係を設定できます。これにより、1 つのジョブが失敗すると、直接的または間接的に依存するすべてのリクエストがキャンセルされます。
+ **`userProvidedEdgeIds`** — このパラメータは、リレーションシップ ID を含む openCypher データをロードする場合にのみ必要です。openCypher 関係 ID がロードデータに明示的に指定されている場合 (推奨)、必ず含められ `True` に設定されています。
`userProvidedEdgeIds` がないか、`True` に設定されている場合、`:ID` 列は、ロード内のすべてのリレーションシップファイルにある必要があります。
`userProvidedEdgeIds` があり、`False` に設定されている場合、ロード内のリレーションシップファイルに `:ID` 列が**あってはなりません**。代わりに、Neptune ローダーは各リレーションシップの ID を自動的に生成します。
CSV データのエラーが修正された後にローダーがロードを再開できるように、リレーションシップ ID を明示的に指定すると便利です。既にロードされているリレーションシップをリロードする必要はありません。リレーションシップ ID が明示的に割り当てられていない場合、リレーションシップファイルを修正する必要があれば、ローダーは失敗したロードを再開できず、代わりにすべてのリレーションシップを再ロードする必要があります。
+ `accessKey` – **[非推奨]** S3 バケットおよびデータファイルにアクセスするための IAM ロールのアクセスキー ID。
代わりに、`iamRoleArn` パラメータを使用することをお勧めします。Amazon S3 にアクセスできるロールを作成し、Neptune クラスターに関連付ける方法の詳細については、[前提条件: IAM ロールと Amazon S3 アクセス](bulk-load-tutorial-IAM.md) を参照してください。
詳細については、「[アクセスキー (アクセスキー ID とシークレットアクセスキー)](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)」を参照してください。
+ `secretKey` – **[非推奨]** 代わりに `iamRoleArn` パラメータを使用することをお勧めします。Amazon S3 にアクセスできるロールを作成し、Neptune クラスターに関連付ける方法の詳細については、[前提条件: IAM ロールと Amazon S3 アクセス](bulk-load-tutorial-IAM.md) を参照してください。
詳細については、「[アクセスキー (アクセスキー ID とシークレットアクセスキー)](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys)」を参照してください。
### openCypher データのロードに関する特別な考慮事項
+ openCypher データを CSV 形式でロードする場合、形式パラメータを `opencypher` に設定する必要があります。
+ すべての openCypher プロパティが単一のカーディナリティを持つため、`updateSingleCardinalityProperties` パラメータはopenCypher のロードではサポートされていません。openCypher ロードフォーマットは配列をサポートしておらず、ID 値が複数回表示される場合は、重複エラーまたは挿入エラーとして扱われます (下記参照)。
+ Neptune ローダーは openCypher データで検出された重複を次のように処理します。
+ ローダーが同じノードIDを持つ複数の行を検出すると、次のルールを使用してマージされます。
+ 行のすべてのラベルがノードに追加されます。
+ 各プロパティには、プロパティ値が 1 つだけ読み込まれます。ロードする値の選択は決定的ではありません。
+ ローダーが同じリレーションシップ ID を持つ複数の行を検出すると、そのうちの 1 つだけがロードされます。ロードする行の選択は決定的ではありません。
+ ローダーは、既存のノードまたはリレーションシップの ID を持つロード・データに遭遇した場合、データベース内の既存のノードまたはリレーションシップのプロパティ値を更新することはありません。ただし、既存のノードやリレーションシップには存在しないノードラベルやプロパティがロードされます。
+ リレーションシップに ID を割り当てる必要はありませんが、通常はお勧めします (上記の `userProvidedEdgeIds` パラメータを参照)。明示的なリレーションシップ ID がない場合、ローダーは、リレーションシップファイルにエラーが発生した場合にロードが失敗した場所からロードを再開するのではなく、すべてのリレーションシップをリロードする必要があります。
また、ロードデータに明示的なリレーションシップ ID が含まれていない場合、ローダーは重複リレーションシップを検出することはありません。
以下に示しているのは openCypher ロードコマンドの例です。
```
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 ローダーエラー
エラーが発生すると、JSON オブジェクトがレスポンスの `BODY` に返されます。`message` オブジェクトには、エラーの説明が含まれています。
**エラーカテゴリ**
+ `Error 400` - 構文エラーは HTTP `400` 無効なリクエストエラーを返します。エラーを説明するメッセージ。
+ `Error 500` - 処理できない有効なリクエストは、HTTP `500` 内部サーバーエラーを返します。エラーを説明するメッセージ。
以下は、ローダーからエラーの説明とともに返される可能性があるエラーメッセージです。
**ローダーエラーメッセージ**
+ `Couldn't find the AWS credential for iam_role_arn` (HTTP 400)
認証情報が見つかりませんでした。提供された認証情報を IAM コンソールまたは AWS CLI 出力と照合します。`iamRoleArn` で指定した IAM ロールをクラスターに追加したことを確認します。
+ `S3 bucket not found for source` (HTTP 400)
その S3 バケットは存在しません。バケットの名前を確認します。
+ `The source source-uri does not exist/not reachable` (HTTP 400)
S3 バケットに一致するファイルがありません。
+ `Unable to connect to S3 endpoint. Provided source = source-uri and region = aws-region` (HTTP 500)
Amazon S3 に接続できません。このリージョンはクラスターのリージョンと一致する必要があります。VPC エンドポイントがあることを確認します。VPC エンドポイント作成の詳細については、「[Amazon S3 VPC エンドポイントの作成](bulk-load-data.md#bulk-load-prereqs-s3)」を参照してください。
+ `Bucket is not in provided Region (aws-region)` (HTTP 400)
バケットは Neptune DB インスタンスと同じ AWS リージョンにある必要があります。
+ `Unable to perform S3 list operation` (HTTP 400)
提供された IAM ユーザーまたはロールに、バケットまたはフォルダに対する `List` アクセス許可がありません。バケットのポリシーまたはアクセスコントロールリスト (ACL) を確認します。
+ `Start new load operation not permitted on a read replica instance` (HTTP 405)
ロードは書き込み操作です。読み取り/書き込みクラスターエンドポイントの再試行。
+ `Failed to start load because of unknown error from S3` (HTTP 500)
Amazon S3 が不明なエラーを返しました。[AWS サポート](https://aws.amazon.com/premiumsupport/) に連絡する。
+ `Invalid S3 access key` (HTTP 400)
アクセスキーが無効です。提供された認証情報を確認します。
+ `Invalid S3 secret key` (HTTP 400)
シークレットキーが無効です。提供された認証情報を確認します。
+ `Max concurrent load limit breached` (HTTP 400)
ロードリクエストが `"queueRequest" : "TRUE"` なしで送信され、ロードジョブが現在実行中の場合、リクエストはこのエラーで失敗します。
+ `Failed to start new load for the source "source name". Max load task queue size limit breached. Limit is 64` (HTTP 400)
Neptune は、一度に 64 個のローダージョブのキューイングをサポートしています。既にキューに 64 個のジョブが含まれている場合、追加のロードリクエストが送信されると、リクエストはこのメッセージで失敗します。
# Neptune ローダーの例
この例では、Neptune ローダーを使用して、Gremlin CSV 形式を使用し Neptune グラフデータベースにデータをロードする方法を示します。リクエストは HTTP POST リクエストとして Neptune ローダーエンドポイントに送信され、リクエスト本文にはデータソース、形式、IAM ロール、およびその他の設定オプションを指定するために必要なパラメータが含まれています。レスポンスにはロード ID が含まれており、データロードプロセスの進行状況を追跡するために使用できます。
**Example リクエスト**
以下は、`curl` コマンドを使用して HTTP POST 経由で送信されるリクエストです。Neptune CSV 形式のファイルをロードします。詳細については、「[Gremlin ロードデータ形式](bulk-load-tutorial-format-gremlin.md)」を参照してください。
```
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"
}'
```
**Example 応答**
```
{
"status" : "200 OK",
"payload" : {
"loadId" : "ef478d76-d9da-4d94-8ff1-08d9d4863aa5"
}
}
```
# Neptune Loader Get-Status API
`loader` ジョブのステータスを取得します。
ロードステータスを取得するには、`https://your-neptune-endpoint:port/loader` エンドポイントに、HTTP `GET` リクエストを送信する必要があります。特定のロードリクエストのステータスを取得するには、URL パラメータに `loadId` を含めるか、`loadId` を URL パスに追加する必要があります。
Neptune は、直近 1,024 個のバルクロードジョブのみを追跡し、ジョブごとに直近 10,000 個のエラーの詳細のみを保存します。
エラー発生時にローダーから返されるエラーおよびフィードメッセージのリストについては、[Neptune ローダーのエラーおよびフィードメッセージ](loader-message.md) を参照してください。
**Contents**
+ [Neptune Loader Get-Status リクエスト](load-api-reference-status-requests.md)
+ [Loader Get-Status リクエストの構文](load-api-reference-status-requests.md#load-api-reference-status-request-syntax)
+ [Neptune Loader Get-Status リクエストパラメータ](load-api-reference-status-requests.md#load-api-reference-status-parameters)
+ [Neptune Loader Get-Status レスポンス](load-api-reference-status-response.md)
+ [Neptune Loader Get-Status レスポンスのレイアウト](load-api-reference-status-response.md#load-api-reference-status-response-layout)
+ [Neptune Loader Get-Status `overallStatus` および `failedFeeds` レスポンスオブジェクト](load-api-reference-status-response.md#load-api-reference-status-response-objects)
+ [Neptune Loader Get-Status `errors` レスポンスオブジェクト](load-api-reference-status-response.md#load-api-reference-status-errors)
+ [Neptune Loader Get-Status `errorLogs` レスポンスオブジェクト](load-api-reference-status-response.md#load-api-reference-error-logs)
+ [Neptune Loader Get-Status の例](load-api-reference-status-examples.md)
+ [ロードステータスのリクエスト例](load-api-reference-status-examples.md#load-api-reference-status-examples-status-request)
+ [loadId のリクエストの例](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 Loader 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 Loader Get-Status リクエスト
## Loader 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 Loader 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 の数。`loadId` が指定されていない `GET` リクエストを送信して、ロード ID のリストをリクエストするときにのみ有効です。
*使用できる値*: 1～100 の正の整数。
*デフォルト値*: 100。
+ **`includeQueuedLoads`** - ロード ID のリストがリクエストされたときに、キューに入れられたロードリクエストのロード ID を除外するために使用できるオプションのパラメータ。
デフォルトでは、ステータスが `LOAD_IN_QUEUE` のすべてのロードジョブのロード ID がこのようなリストに含まれます。これらは、他のジョブのロード ID の前に表示され、キューに追加された時間順に最新のものから古いものにソートされます。
*使用できる値*: `TRUE`、`FALSE`。
*デフォルト値*: `TRUE`。
# Neptune Loader Get-Status レスポンス
Neptune Get-Status API からの次のレスポンスの例では、レスポンスの全体的な構造、さまざまなフィールドとそれらのデータ型、およびエラー処理とエラーログの詳細について説明します。
## Neptune Loader Get-Status レスポンスのレイアウト
ローダーステータスレスポンスの一般的なレイアウトは次のとおりです。
```
{
"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 Loader Get-Status `overallStatus` および `failedFeeds` レスポンスオブジェクト
エラーの説明とともに、ローダーからの失敗したフィードごとに返される可能性のある応答は、`Get-Status` レスポンスの `overallStatus` オブジェクトの場合と同じです。
これらのフィールドは、すべてのロードの `overallStatus` オブジェクト、および失敗した各フィードの `failedFeeds` オブジェクトに表示されます。
+ **`fullUri`** - ロードされる 1 つ以上のファイルの URI。
*タイプ:* *文字列*
*形式*: `s3://bucket/key`。
+ **`runNumber`** - このロードまたはフィードの実行数。これは、ロードが再開されると増加します。
*タイプ:* *符号なし long*。
+ **`retryNumber`** - このロードまたはフィードの再試行回数。これは、ローダーがフィードまたはロードを自動的に再試行するときに増分されます。
*タイプ:* *符号なし long*。
+ **`status`** - ロードあるいはフィードの返されたステータス。`LOAD_COMPLETED` はロードが問題なく成功したことを示します。その他のロードステータスメッセージのリストについては、[Neptune ローダーのエラーおよびフィードメッセージ](loader-message.md) を参照してください。
*タイプ:* *文字列*。
+ **`totalTimeSpent`** - ロードまたはフィードのデータの解析や挿入に費やした時間 (秒単位)。これには、ソースファイルのリストを取得するのに費やされた時間は含まれません。
*タイプ:* *符号なし long*。
+ **`totalRecords`** - ロードされた、またはロードしようとした全レコード。
*タイプ:* *符号なし 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`** - 発生した重複レコードの数。
*タイプ:* *符号なし 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`** - 発生した解析エラーの数。
*タイプ:* *符号なし long*。
+ **`datatypeMismatchErrors`** - 指定されたデータとデータ型が一致しないレコードの数。
*タイプ:* *符号なし long*。
+ **`insertErrors`** - エラーにより挿入できなかったレコード数。
*タイプ:* *符号なし long*。
## Neptune Loader Get-Status `errors` レスポンスオブジェクト
エラーは以下のカテゴリに分類されます。
+ **`Error 400`** - `loadId` が無効の場合、HTTP `400` 無効な要求エラーが返されます。エラーを説明するメッセージ。
+ **`Error 500`** - 処理できない有効なリクエストは、HTTP `500` 内部サーバーエラーを返します。エラーを説明するメッセージ。
エラー発生時にローダーから返されるエラーおよびフィードメッセージのリストについては、[Neptune ローダーのエラーおよびフィードメッセージ](loader-message.md) を参照してください。
エラーが発生すると、JSON `errors` オブジェクトがレスポンスの `BODY` に次のフィールドと共に返されます。
+ **`startIndex`** - 最初に含まれたエラーのインデックス。
*タイプ:* *符号なし long*。
+ **`endIndex`** - 最後に含まれたエラーのインデックス。
*タイプ:* *符号なし long*。
+ **`loadId`** - ロードの ID。この ID を使用すると、`errors` パラメータを `TRUE` に設定してロードのエラーを出力できます。
*タイプ:* *文字列*。
+ **`errorLogs`** — エラーのリスト。
*タイプ:* *リスト*。
## Neptune Loader 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`** - エラーを説明するメッセージ。
これは、エラーコードに関連付けられた一般的なメッセージ、または詳細を含む特定のメッセージ (たとえば、From/To 頂点の欠落、解析エラーなど) です。
+ **`fileName`** — フィードの名前。
+ **`recordNum`** — 解析エラーの場合、これは解析できなかったレコードのファイル内のレコード番号です。レコード番号がエラーに適用されない場合、または特定できなかった場合は 0 に設定されます。
たとえば、RDF `nquads` ファイルで次のような障害のある行に遭遇した場合、バルクローダは解析エラーを生成します。
```
|http://base#predicate> .
```
ご覧のとおり、上の 2 番目の `http` 行の前には `|` ではなく `<` とがあります。ステータスレスポンスの `errorLogs` における結果のエラーオブジェクトは次のようになります。
```
{
"errorCode" : "PARSING_ERROR",
"errorMessage" : "Expected '<', found: |",
"fileName" : "s3://bucket/key",
"recordNum" : 12345
},
```
# Neptune Loader Get-Status の例
次の例は、Neptune ローダーの GET-Status API の使用方法を示しています。これにより、Amazon Neptune グラフデータベースへのデータロードのステータスに関する情報を取得できます。これらの例は、特定のロードのステータスの取得、使用可能なロード ID、特定のロードの詳細なステータス情報のリクエストという 3 つの主なシナリオを対象としています。
## ロードステータスのリクエスト例
以下は、`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
}
}
}
```
## loadId のリクエストの例
以下は、`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 Loader 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"`) を使用している場合、ローダーは既に正常にロードされたファイルをスキップし、中断が発生したときにまだロードされていなかったファイルのロードを再開します。
# Neptune Loader Cancel Job
ロードジョブをキャンセルします｡
ジョブをキャンセルするには、`DELETE` エンドポイントに、HTTP `https://your-neptune-endpoint:port/loader` リクエストを送信する必要があります。`loadId` は `/loader` URL パスに追加することも、URL に変数として含めることもできます。
## ジョブキャンセルリクエストの構文
```
DELETE https://your-neptune-endpoint:port/loader?loadId=loadId
```
```
DELETE https://your-neptune-endpoint:port/loader/loadId
```
## ジョブキャンセルリクエストのパラメータ
**loadId**
ロードジョブの ID。
## ジョブキャンセルレスポンスの構文
```
no response body
```
**200 OK**
ロードジョブが正常に削除されると `200` コードが返されます。
## ジョブキャンセルエラー
エラーが発生すると、JSON オブジェクトがレスポンスの `BODY` に返されます。`message` オブジェクトには、エラーの説明が含まれています。
**エラーカテゴリ**
+ **`Error 400`** - `loadId` が無効の場合、HTTP `400` 無効な要求エラーが返されます。エラーを説明するメッセージ。
+ **`Error 500`** - 処理できない有効なリクエストは、HTTP `500` 内部サーバーエラーを返します。エラーを説明するメッセージ。
## ジョブキャンセルエラーメッセージ
以下は、キャンセル API からエラーの説明とともに返される可能性があるエラーメッセージです。
+ `The load with id = load_id does not exist or not active` (HTTP 404) - ロードが見つかりませんでした。`id` パラメータの値を確認します。
+ `Load cancellation is not permitted on a read replica instance.` (HTTP 405) - ロードは書き込み操作です。読み取り/書き込みクラスターエンドポイントの再試行。
## ジョブキャンセルの例
**Example リクエスト**
以下は、`curl` コマンドを使用して HTTP `DELETE` 経由で送信されるリクエストです。
```
curl -X DELETE 'https://your-neptune-endpoint:port/loader/0a237328-afd5-4574-a0bc-c29ce5f54802'
```
# AWS Database Migration Service を使用して別のデータストアから Amazon Neptune にデータをロードする
AWS Database Migration Service (AWS DMS) は、[サポートされているソースデータベース](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Source.html)から Neptune にデータを迅速かつ安全にロードできます。移行中でもソースデータベースは完全に利用可能な状態に保たれ、それを利用するアプリケーションのダウンタイムを最小限に抑えられます。
の詳細については、 AWS DMS ユーザーガイドおよび [AWS Database Migration Service API リファレンス](https://docs.aws.amazon.com/dms/latest/APIReference/)を参照してください。 [AWS Database Migration Service](https://docs.aws.amazon.com/dms/latest/userguide/)特に、Neptune クラスターを移行のターゲットとして設定する方法については、[AWS Database Migration Serviceのターゲットとしての Amazon Neptune の使用」](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Target.Neptune.html)を参照してください。
AWS DMSを使用して Neptune にデータをインポートするための前提条件は次のとおりです。
+ ソースデータベースからデータを抽出する方法を定義するには、 AWS DMS テーブルマッピングオブジェクトを作成する必要があります (詳細については、 AWS DMS 「 ユーザーガイド[」の「JSON を使用したテーブルマッピングによるテーブルの選択と変換の指定](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Tasks.CustomizingTasks.TableMapping.html#CHAP_Tasks.CustomizingTasks.TableMapping.SelectionTransformation)」を参照してください）。このテーブルマッピング設定オブジェクトは、読み取る必要があるテーブル、その順序、および列の命名方法を指定します。また、コピーされる行をフィルタリングし、小文字への変換や四捨五入などの単純な値の変換を提供することもできます。
+ ソースデータベースから抽出されたデータを Neptune にロードする方法を指定するには、Neptune `GraphMappingConfig` を作成する必要があります。RDF データ (SPARQL を使用してクエリされる) の場合、`GraphMappingConfig` は W3 の標準 [R2RML](https://www.w3.org/TR/r2rml/) マッピング言語で記述されます。プロパティグラフデータ (Gremlin を使用してクエリされる) の場合、`GraphMappingConfig` は JSON オブジェクトです ([プロパティグラフ/Gremlin データの GraphMappingConfig レイアウト](dms-neptune-graph-mapping.md#dms-neptune-graph-mapping-gremlin) を参照)。
+ AWS DMS を使用して、Neptune DB クラスターと同じ VPC にレプリケーションインスタンスを作成し、データ転送を仲介する必要があります。
+ また、移行データをステージングするための中間ストレージとして使用する Amazon S3 バケットも必要です。
# Neptune GraphMappingConfig の作成
作成した `GraphMappingConfig` は、ソースデータストアから抽出されたデータを Neptune DB クラスターにロードする方法を指定します。形式は、目的が RDF データのロードか、プロパティグラフデータのロードかによって異なります。
RDF データの場合、W3 [R2RML](https://www.w3.org/TR/r2rml/) 言語を使用してリレーショナルデータを RDF にマッピングできます。
Gremlin を使用してクエリするプロパティグラフデータをロードする場合、`GraphMappingConfig` の JSON オブジェクトを作成します。
## RDF/SPARQL データの GraphMappingConfig レイアウト
SPARQL を使用して照会する RDF データをロードする場合は、[R2RML](https://www.w3.org/TR/r2rml/) に `GraphMappingConfig` を書き込みます。`R2RML` はリレーショナルデータを RDF にマッピングするための標準 W3 言語です。1 つの例を次に示します。
```
@prefix rr: .
@prefix ex: .
<#TriplesMap1>
rr:logicalTable [ rr:tableName "nodes" ];
rr:subjectMap [
rr:template "http://data.example.com/employee/{id}";
rr:class ex:Employee;
];
rr:predicateObjectMap [
rr:predicate ex:name;
rr:objectMap [ rr:column "label" ];
] .
```
次に、別の例を示します。
```
@prefix rr: .
@prefix ex: .
@prefix foaf: .
@prefix xsd: .
<#TriplesMap2>
rr:logicalTable [ rr:tableName "Student" ];
rr:subjectMap [ rr:template "http://example.com/{ID}{Name}";
rr:class foaf:Person ];
rr:predicateObjectMap [
rr:predicate ex:id ;
rr:objectMap [ rr:column "ID";
rr:datatype xsd:integer ]
];
rr:predicateObjectMap [
rr:predicate foaf:name ;
rr:objectMap [ rr:column "Name" ]
] .
```
「[R2RML: RDB to RDF Mapping Language](https://www.w3.org/TR/r2rml/)」にある「W3 Recommendation」には、言語の詳細が記載されています。
## プロパティグラフ/Gremlin データの GraphMappingConfig レイアウト
プロパティグラフデータの同等の `GraphMappingConfig` は、ソースデータから生成される各グラフエンティティのマッピングルールを提供する JSON オブジェクトです。次のテンプレートは、このオブジェクトの各ルールがどのようになるかを示しています。
```
{
"rules": [
{
"rule_id": "(an identifier for this rule)",
"rule_name": "(a name for this rule)",
"table_name": "(the name of the table or view being loaded)",
"vertex_definitions": [
{
"vertex_id_template": "{col1}",
"vertex_label": "(the vertex to create)",
"vertex_definition_id": "(an identifier for this vertex)",
"vertex_properties": [
{
"property_name": "(name of the property)",
"property_value_template": "{col2} or text",
"property_value_type": "(data type of the property)"
}
]
}
]
},
{
"rule_id": "(an identifier for this rule)",
"rule_name": "(a name for this rule)",
"table_name": "(the name of the table or view being loaded)",
"edge_definitions": [
{
"from_vertex": {
"vertex_id_template": "{col1}",
"vertex_definition_id": "(an identifier for the vertex referenced above)"
},
"to_vertex": {
"vertex_id_template": "{col3}",
"vertex_definition_id": "(an identifier for the vertex referenced above)"
},
"edge_id_template": {
"label": "(the edge label to add)",
"template": "{col1}_{col3}"
},
"edge_properties":[
{
"property_name": "(the property to add)",
"property_value_template": "{col4} or text",
"property_value_type": "(data type like String, int, double)"
}
]
}
]
}
]
}
```
頂点ラベルが存在する場合、頂点がここで作成されることを意味しますが、ない場合、頂点が別のソースによって作成されることを意味します。この定義は、頂点プロパティの追加のみです。
従業員レコードのサンプルルールを次に示します。
```
{
"rules": [
{
"rule_id": "1",
"rule_name": "vertex_mapping_rule_from_nodes",
"table_name": "nodes",
"vertex_definitions": [
{
"vertex_id_template": "{emp_id}",
"vertex_label": "employee",
"vertex_definition_id": "1",
"vertex_properties": [
{
"property_name": "name",
"property_value_template": "{emp_name}",
"property_value_type": "String"
}
]
}
]
},
{
"rule_id": "2",
"rule_name": "edge_mapping_rule_from_emp",
"table_name": "nodes",
"edge_definitions": [
{
"from_vertex": {
"vertex_id_template": "{emp_id}",
"vertex_definition_id": "1"
},
"to_vertex": {
"vertex_id_template": "{mgr_id}",
"vertex_definition_id": "1"
},
"edge_id_template": {
"label": "reportsTo",
"template": "{emp_id}_{mgr_id}"
},
"edge_properties":[
{
"property_name": "team",
"property_value_template": "{team}",
"property_value_type": "String"
}
]
}
]
}
]
}
```
# Neptune をターゲットとする AWS DMS レプリケーションタスクの作成
テーブルマッピングおよびグラフマッピング設定を作成したら、次のプロセスを使用してソースストアから Neptune にデータをロードします。問題の APIs の詳細については、 AWS DMS ドキュメントを参照してください。
## AWS DMS レプリケーションインスタンスを作成する
Neptune DB クラスターが実行されている VPC にレ AWS DMS プリケーションインスタンスを作成します (「 AWS DMS ユーザーガイド[」の AWS 「DMS レプリケーションインスタンス](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_ReplicationInstance.html)と [CreateReplicationInstance](https://docs.aws.amazon.com/dms/latest/APIReference/API_CreateReplicationInstance.html) の使用」を参照）。これを行うには、次のような AWS CLI コマンドを使用できます。
```
aws dms create-replication-instance \
--replication-instance-identifier (the replication instance identifier) \
--replication-instance-class (the size and capacity of the instance, like 'dms.t2.medium') \
--allocated-storage (the number of gigabytes to allocate for the instance initially) \
--engine-version (the DMS engine version that the instance should use) \
--vpc-security-group-ids (the security group to be used with the instance)
```
## ソースデータベースの AWS DMS エンドポイントを作成する
次のステップでは、ソースデータストアの AWS DMS エンドポイントを作成します。 AWS CLI 次のような で AWS DMS [CreateEndpoint](https://docs.aws.amazon.com/dms/latest/APIReference/API_CreateEndpoint.html) API を使用できます。
```
aws dms create-endpoint \
--endpoint-identifier (source endpoint identifier) \
--endpoint-type source \
--engine-name (name of source database engine) \
--username (user name for database login) \
--password (password for login) \
--server-name (name of the server) \
--port (port number) \
--database-name (database name)
```
## Neptune がステージングデータに使用する Amazon S3 バケットをセットアップする
ステージングデータに使用できる Amazon S3 バケットがない場合は、Amazon S3 入門ガイドの[バケットの作成](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CreatingABucket.html)、またはコンソールユーザーガイドの[S3 バケットを作成する方法](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket.html)の説明に従ってバケットを作成します。
バケットに `GetObject`、`PutObject`、`DeleteObject`、および、`ListObject` アクセス許可を付与する IAM ポリシーを作成する必要があります (まだない場合)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ListObjectsInBucket",
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket"
]
},
{
"Sid": "AllObjectActions",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
]
}
```
------
Neptune DB クラスターで IAM 認証が有効になっている場合、次のポリシーも含める必要があります。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "neptune-db:*",
"Resource": "arn:aws:neptune-db:us-east-1:111122223333:cluster-resource-id/*"
}
]
}
```
------
ポリシーをアタッチする信頼ドキュメントとして IAM ロールを作成します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "dms.amazonaws.com"
},
"Action": "sts:AssumeRole"
},
{
"Sid": "neptune",
"Effect": "Allow",
"Principal": {
"Service": "rds.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
ポリシーをロールにアタッチした後、ロールを Neptune DB クラスターにアタッチします。これにより、 AWS DMS はロードされるデータをステージングするために バケットを使用できます。
## Neptune VPC で Amazon S3 エンドポイントを作成する
ここでは、Neptune クラスターが配置されている VPC に、中間 Amazon S3 バケットの VPC ゲートウェイエンドポイントを作成します。 AWS マネジメントコンソール または を使用してこれ AWS CLI を行うことができます。詳細については、[「ゲートウェイエンドポイントの作成](https://docs.aws.amazon.com/vpc/latest/userguide/vpce-gateway.html#create-gateway-endpoint)」を参照してください。
## Neptune の AWS DMS ターゲットエンドポイントを作成する
ターゲット Neptune DB クラスターの AWS DMS エンドポイントを作成します。 AWS DMS [CreateEndpoint](https://docs.aws.amazon.com/dms/latest/APIReference/API_CreateEndpoint.html) API は、次のような `NeptuneSettings`パラメータで使用できます。
```
aws dms create-endpoint \
--endpoint-identifier (target endpoint identifier) \
--endpoint-type target \
--engine-name neptune \
--server-name (name of the server) \
--port (port number) \
--neptune-settings '{ \
"ServiceAccessRoleArn": "(ARN of the service access role)", \
"S3BucketName": "(name of S3 bucket to use for staging files when migrating)", \
"S3BucketFolder": "(name of the folder to use in that S3 bucket)", \
"ErrorRetryDuration": (number of milliseconds to wait between bulk-load retries), \
"MaxRetryCount": (the maximum number of times to retry a failing bulk-load job), \
"MaxFileSize": (maximum file size, in bytes, of the staging files written to S3), \
"IamAuthEnabled": (set to true if IAM authentication is enabled on the Neptune cluster) }'
```
`NeptuneSettings` パラメータで AWS DMS `CreateEndpoint` API に渡される JSON オブジェクトには、次のフィールドがあります。
****
+ **`ServiceAccessRoleArn`** – *(必須)* Neptune へのデータの移行をステージングするために使用される S3 バケットへのきめ細かなアクセスを許可する IIAM ロールの ARN。IAM 認可が有効になっている場合、このロールには Neptune DB クラスターにアクセスするアクセス許可も必要です。
+ **`S3BucketName`** – *(必須)*フルロード移行の場合、レプリケーションインスタンスはすべての RDS データを CSV、クワッドファイルに変換し、S3 のこのステージングバケットにアップロードし、それらを Neptune に一括ロードします。
+ **`S3BucketFolder`** – *(必須)* S3 ステージングバケットで使用するフォルダー。
+ **`ErrorRetryDuration`** – *(オプション)* Neptune リクエストが失敗してから再試行リクエストを行うまでに待機するミリ秒数。デフォルトは 250 です。
+ **`MaxRetryCount`** – *(オプション)* 再試行可能な失敗後に AWS DMS 行う再試行リクエストの最大数。デフォルトは 5 です。
+ **`MaxFileSize`** – *(オプション)* 移行中に S3 に保存された各ステージングファイルの最大サイズ (バイト単位)。デフォルトは 1,048,576 KB (1 GB) です。
+ **`IsIAMAuthEnabled`** – *(オプション)* IAM 認証が Neptune DB クラスターで有効になっている場合 `true` に、そうでない場合 `false` に設定します。デフォルトは `false` です。
## 新しいエンドポイントへの接続をテストする
これらの新しいエンドポイントへの接続は、 AWS DMS [TestConnection](https://docs.aws.amazon.com/dms/latest/APIReference/API_TestConnection.html) API を使用して次のようにテストできます。
```
aws dms test-connection \
--replication-instance-arn (the ARN of the replication instance) \
--endpoint-arn (the ARN of the endpoint you are testing)
```
## AWS DMS レプリケーションタスクを作成する
前の手順を正常に完了したら、ソースデータストアから Neptune にデータを移行するためのレプリケーションタスクを AWS DMS [CreateReplicationTask](https://docs.aws.amazon.com/dms/latest/APIReference/API_CreateReplicationTask.html.html) API を使用して作成します。
```
aws dms create-replication-task \
--replication-task-identifier (name for the replication task) \
--source-endpoint-arn (ARN of the source endpoint) \
--target-endpoint-arn (ARN of the target endpoint) \
--replication-instance-arn (ARN of the replication instance) \
--migration-type full-load \
--table-mappings (table-mapping JSON object or URI like 'file:///tmp/table-mappings,json') \
--task-data (a GraphMappingConfig object or URI like 'file:///tmp/graph-mapping-config.json')
```
`TaskData` パラメータは、コピーされたデータを Neptune に保存する方法を指定する [GraphMappingConfig](dms-neptune-graph-mapping.md) を提供します。
## AWS DMS レプリケーションタスクを開始する
ここでは、レプリケーションタスクを開始できます。
```
aws dms start-replication-task
--replication-task-arn (ARN of the replication task started in the previous step)
--start-replication-task-type start-replication
```
# クエリを使用して Amazon Neptune にデータをロードする
Neptune は、クエリ言語オペレーションによるデータの直接書き込みをサポートしています。openCypher `MERGE`では `CREATE`や 、SPARQL `INSERT`では 、Gremlin `mergeE()`では `mergeV()`や などの標準的な書き込みオペレーションを使用して、グラフ内のデータを追加または変更できます。これらのオペレーションは、増分更新とトランザクション書き込みに適しています。
Amazon S3 からデータをロードするには、最適化されたパフォーマンスを必要とする大規模なデータセット[Amazon Neptune 一括ローダーを使用したデータの取り込み](bulk-load.md)に を使用します。1 つまたは複数の Amazon S3 ファイル内の小さなデータセットの場合、クエリベースのロード関数を使用して、クエリ内でデータを直接読み取り、処理できます。
次のクエリベースのロード関数を使用できます。
## openCypher: neptune.read()
この`neptune.read()`関数は、`CALL`サブクエリ内の Amazon S3 から CSV ファイルまたは Parquet ファイルを読み取るため、クエリ時にデータを処理およびロードできます。
```
CALL neptune.read({
source: "s3://bucket/data.csv",
format: "csv"
})
YIELD row
CREATE (n:Person {id: row.id, name: row.name})
```
詳細なドキュメントについては、「」を参照してください[neptune.read()](access-graph-opencypher-21-extensions-s3-read.md)。
## SPARQL: LOAD と UNLOAD
SPARQL `LOAD`オペレーションは、URI から名前付きグラフに RDF データをインポートします。 は、グラフから Amazon S3 にデータを`UNLOAD`エクスポートします。
```
LOAD INTO GRAPH
```
詳細なドキュメントについては、「」を参照してください[SPARQL UPDATE LOAD を使用して Neptune にデータをインポートする](sparql-api-reference-update-load.md)。
## Gremlin: io() ステップ
Gremlin の `g.io(URL).read()` ステップを使用して、[GraphML](https://tinkerpop.apache.org/docs/current/dev/io/#graphml) (XML 形式）、[GraphSON](https://tinkerpop.apache.org/docs/current/dev/io/#graphson) (JSON 形式）、およびその他の形式のデータファイルを読み込むこともできます。
```
g.io("s3://bucket/data.graphml").read().iterate()
```
詳細については、[TinkerPop ドキュメント](https://tinkerpop.apache.org/docs/current/reference/#io-step)を参照してください。