翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # 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` コードが返されます。