本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 將資料載入至 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/))。 + 對於一或多個 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 提供 `Loader` 命令，直接從外部檔案將資料載入至 Neptune 資料庫叢集。您可以使用此命令，而非執行大量 `INSERT` 陳述式、`addV` 和 `addE` 步驟，或其他 API 呼叫。 Neptune **Loader** 命令速度更快且負荷較低、已針對大型資料集進行最佳化，且同時支援 Gremlin 資料和 SPARQL 使用的 RDF (資源描述架構) 資料。 下圖顯示載入程序的概觀： ![\[圖表顯示將資料載入 Neptune 的各項基本步驟。\]](http://docs.aws.amazon.com/zh_tw/neptune/latest/userguide/images/load-diagram.png) 以下是載入程序的步驟： 1. 將資料檔案複製到 Amazon Simple Storage Service (Amazon S3) 儲存貯體。 1. 建立具有讀取和列出儲存貯體的存取權的 IAM 角色。 1. 建立 Amazon S3 VPC 端點。 1. 透過 HTTP 將請求傳送至 Neptune 資料庫執行個體，來啟動 Neptune 載入器。 1. Neptune 資料庫執行個體擔任 IAM 角色，從儲存貯體載入資料。 **注意** 您可以從 Amazon S3 載入加密的資料 (如果它是使用 Amazon S3 `SSE-S3` 或 `SSE-KMS` 模式加密的)，前提是您用於大量載入的角色可以存取 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 資料庫執行個體](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 載入加密的資料 (如果它是使用 Amazon S3 `SSE-S3` 模式加密的)。在這種情況下，Neptune 可以模擬您的憑證，並代表您發出 `s3:getObject` 呼叫。 您也可以從 Amazon S3 載入使用 `SSE-KMS` 模式加密的加密資料，只要您的 IAM 角色包含存取 AWS KMS的必要許可。如果沒有適當的 AWS KMS 許可，大量載入操作會失敗並傳回`LOAD_FAILED`回應。 Neptune 目前不支援載入使用 `SSE-C` 模式加密的 Amazon S3 資料。 以下章節說明如何使用受管 IAM 政策，建立 IAM 角色以存取 Amazon S3 資源，然後將該角色附加至您的 Neptune 叢集。 **Topics** + [建立 IAM 角色以允許 Amazon Neptune 存取 Amazon S3 資源](bulk-load-tutorial-IAM-CreateRole.md) + [將 IAM 角色新增至 Amazon Neptune 叢集](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 主控台要求使用者具有下列 IAM 許可，以將角色附加至 Neptune 叢集： ``` iam:GetAccountSummary on resource: * iam:ListAccountAliases on resource: * iam:PassRole on resource: * with iam:PassedToService restricted to rds.amazonaws.com ``` # 建立 IAM 角色以允許 Amazon Neptune 存取 Amazon S3 資源 使用 `AmazonS3ReadOnlyAccess` 受管 IAM 政策建立新的 IAM 角色，其會允許 Amazon Neptune 存取 Amazon S3 資源。 **建立允許 Neptune 存取 Amazon S3 的新 IAM 角色** 1. 在以下網址開啟 IAM 主控台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。 1. 在導覽窗格中，選擇**角色**。 1. 選擇 **Create Role** (建立角色)。 1. 在 **AWS 服務**下，選擇 **RDS**。 1. 選擇**下一步：許可**。 1. 使用篩選條件方塊來依照字詞 **S3** 篩選，並勾選 **AmazonS3ReadOnlyAccess** 旁的方塊。 **注意** 此政策授予對所有儲存貯體的 `s3:Get*` 和 `s3:List*` 許可。稍後的步驟會使用信任政策來限制角色的存取權。 載入器只需要載入來源儲存貯體的 `s3:Get*` 和 `s3:List*` 許可，因此您也可以按 Amazon S3 資源限制這些許可。 如果您的 S3 儲存貯體已加密，則必須添加 `kms:Decrypt` 許可 1. 選擇下**一步：檢閱**。 1. 將**角色名稱**設為您的 IAM 角色名稱，例如：`NeptuneLoadFromS3`。您也可以新增選用的**角色描述**值，例如：「允許 Neptune 代表您存取 Amazon S3 資源」。 1. 選擇**建立角色**。 1. 在導覽窗格中，選擇**角色**。 1. 在 **Search (搜尋)** 欄位中，輸入您建立的角色名稱，然後在該角色出現於清單時選擇它。 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. 完成「[將 IAM 角色新增至 Amazon Neptune 叢集](bulk-load-tutorial-IAM-add-role-cluster.md)」中的步驟。 # 將 IAM 角色新增至 Amazon Neptune 叢集 使用主控台將 IAM 角色新增至 Amazon Neptune 叢集。這會允許叢集中的任何 Neptune 資料庫執行個體擔任該角色，並從 Amazon S3 載入。 **注意** Amazon Neptune 主控台要求使用者具有下列 IAM 許可，以將角色附加至 Neptune 叢集： ``` iam:GetAccountSummary on resource: * iam:ListAccountAliases on resource: * iam:PassRole on resource: * with iam:PassedToService restricted to rds.amazonaws.com ``` **將 IAM 角色新增至 Amazon Neptune 叢集** 1. 登入 AWS 管理主控台，然後開啟位於 https：//[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：//[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/) 的 Amazon VPC 主控台。 1. 在導覽窗格中選擇**端點**。 1. 選擇**建立端點**。 1. 為閘道類型端點選擇**服務名稱** `com.amazonaws.region.s3`。 **注意** 如果此處的區域不正確，請務必確保主控台區域正確。 1. 選擇包含 Neptune 資料庫執行個體的 VPC (在 Neptune 主控台中，它是針對您的資料庫執行個體而列出的)。 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) 開始，如果該角色無法存取您需要的所有資源，您可以鏈結您的叢集可以擔任的一或多個其他角色，以取得其他資源的存取權。鏈結中的每個角色都會擔任鏈結中的下一個角色，直到您的叢集已擔任鏈結尾端的角色為止。 若要鏈結這些角色，請在它們之間建立信任關係。例如，若要將 `RoleB` 鏈接至 `RoleA`，`RoleA` 必須具有允許它擔任 `RoleB` 的許可政策，而且 `RoleB` 必須具有允許其將其許可傳回 `RoleA` 的信任政策。如需詳細資訊，請參閱[使用 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html)。 鏈結中的第一個角色必須附加至正在載入資料的叢集。 第一個角色以及擔任鏈結中隨後角色的每個後續角色必須具有： + 包含對 `sts:AssumeRole` 動作具有 `Allow` 效果之特定陳述式的政策。 + `Resource` 元素中下一個角色的 Amazon Resource Name (ARN)。 **注意** 目標 Amazon S3 儲存貯體必須與叢集位於相同的 AWS 區域。 ## 使用鏈結的角色進行跨帳戶存取 您可以鏈結屬於另一個帳戶的一個或多個角色來授與跨帳戶存取權。當您的叢集暫時擔任屬於另一個帳戶的角色時，它可以取得該處資源的存取權。 例如，假設**帳戶 A** 想要存取屬於帳戶 **B** 的 Amazon S3 儲存貯體中的資料： + **帳戶 A** 會為名為 的 Neptune 建立 AWS 服務角色，`RoleA`並將其連接至叢集。 + **帳戶 B** 會建立一個名為 `RoleB` 的角色，其獲授權可以存取**帳戶 B** 儲存貯體中的資料。 + **帳戶 A** 會將許可政策附加至 `RoleA`，允許其擔任 `RoleB`。 + **帳戶 B** 會將信任策略附加至 `RoleB`，允許其將其許可傳回 `RoleA`。 + 若要存取**帳戶 B** 儲存貯體中的資料，**帳戶 A** 會使用鏈結 `RoleA` 和 `RoleB` 的 `iamRoleArn` 參數執行載入器命令。在載入器操作期間，`RoleA` 接著會暫時擔任 `RoleB`，以存取**帳戶 B** 中的 Amazon S3 儲存貯體。 ![\[說明使用鏈結的角色進行跨帳戶存取的圖表\]](http://docs.aws.amazon.com/zh_tw/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` 還會有一個允許它擔任 `RoleB` 的許可政策，此角色是**帳戶 B** 擁有的： ------ #### [ 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 端點 當您透過私有 IP 地址將 IAM 角色鏈結至私有存取 AWS STS APIs AWS STS 時，Neptune 載入器需要 VPC 端點。您可以透過 VPC 端點 AWS STS ，以安全且可擴展的方式直接從 Amazon VPC 連線至 。當您使用介面 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 資料庫執行個體和 EC2 執行個體的 **VPC**。 1. 選取 EC2 執行個體所在子網路旁邊的核取方塊。您無法在相同的可用區域內選取多個子網路。 1. 針對 IP address type (IP 地址類型)，從下列選項中選擇： + **IPv4** - 將 IPv4 地址指派給您的端點網路介面。只有當所有選取的子網都具有 IPv4 地址範圍時，才支援此選項。 + **IPv6** - 將 IPv6 地址指派給您的端點網路介面。只有當所有選取的子網路都是僅限 IPv6 子網路，才支援此選項。 + **Dualstack** - 將 IPv4 和 IPv6 地址指派給您的端點網路介面。只有當所有選取的子網都具有 IPv4 和 IPv6 地址範圍時，才支援此選項。 1. 對於 **安全群組**，選取要與 VPC 端點的端點網路界面建立關聯的安全群組。您需要選取所有附加到 Neptune 資料庫執行個體和 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 清單。 儘管您大多只需要在鏈結中具有兩個角色，但當然可以同時鏈結三個以上的角色。例如，此載入器命令會鏈結三個角色： ``` 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) 資料，您可以使用下列其中一個標準格式，這些格式是由全球資訊網協會 (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/) 上的 [GraphML2CSV 專案](https://github.com/awslabs/amazon-neptune-tools/blob/master/graphml2csv/README.md)中取得。 ## 支援壓縮載入資料檔案 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 載入資料格式 若要使用 CSV 格式載入 Apache TinkerPop Gremlin 資料，您必須在單獨的檔案中指定點和邊。 載入器可在單一載入工作中，從多點和多邊檔案進行載入。 對於每個載入命令，要載入的檔案集在 Amazon S3 儲存貯體中必須位於同一資料夾，而且您會為 `source` 參數指定資料夾名稱。檔案名稱和副檔名不重要。 Amazon Neptune CSV 格式遵循 RFC 4180 CSV 規格。如需詳細資訊，請參閱 Internet Engineering Task Force (IETF) 網站上的 [Common Format and MIME Type for CSV Files](https://tools.ietf.org/html/rfc4180) (CSV 檔案的常見格式與 MIME 類型)。 **注意** 所有檔案都必須以 UTF-8 格式編碼。 每個檔案都有以逗號分隔的標頭資料列。此標頭資料列包含系統欄標題和屬性欄標頭。 ## 系統欄標題 頂點檔案和邊緣檔案的必要和允許的系統欄標頭是不同的。 每個系統欄只能在標頭中出現一次。 所有標籤皆區分大小寫。 **頂點標頭** + `~id` - **必要** 頂點的 ID。 + `~label` 頂點的標籤。允許多個標籤值，以分號 (`;`) 分隔。 如果 `~label` 不存在，TinkerPop 會提供值為 `vertex` 的標籤，因為每個頂點必須至少有一個標籤。 **邊緣標頭** + `~id` - **必要** 邊緣的 ID。 + `~from` - **必要** *從*頂點的頂點 ID。 + `~to` - **必要** *至*頂點的頂點 ID。 + `~label` 邊緣的標籤。邊緣只能有一個標籤。 如果 `~label` 不存在，TinkerPop 會提供值為 `edge` 的標籤，因為每個邊緣必須具有一個標籤。 ## 屬性欄標題 您可以使用以下語法指定屬性欄 (`:`)。類型名稱不區分大小寫。不過，請注意，如果屬性名稱內出現冒號，則必須在其前面加上反斜線來逸出冒號：`\:`。 ``` propertyname:type ``` **注意** 欄標頭中不允許空格、逗號、換行字元和換行字元，因此屬性名稱不能包含這些字元。 您可以透過將 `[]` 新增至類型，來為陣列類型指定一個欄： ``` propertyname:type[] ``` **注意** 邊緣屬性只能有一個值，如果指定了陣列類型或指定了第二個值，會導致錯誤。 以下範例顯示名為 `age` 的 `Int` 類型屬性的欄標頭。 ``` 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 資料類型 這是一個允許的屬性類型清單及每個類型的描述。 **布林 (或布林值)** 表示布林值欄位。允許的值：`false`、`true` **注意** 所有 `true` 以外的值會被視為 false。 **整數類型** 超出定義範圍的值將導致錯誤。 | | | Type | 範圍 | | --- |--- | | Byte | -128 to 127 | | Short | -32768 to 32767 | | Int | -2^31 to 2^31-1 | | Long | -2^63 to 2^63-1 | **小數類型** 支援小數符號或科學符號。此外，允許符號，例如 (\$1/-) Infinity 或 NaN。不支援 INF。 | | | Type | 範圍 | | --- |--- | | Float | 32-bit IEEE 754 floating point | | Double | 64-bit IEEE 754 floating point | 浮點數和雙精確度值過長，將四捨五入到最接近 24 位元 (float) 和 53 位元 (double) 精確度的值並載入。位元層級的剩餘數中段值將四捨五入為 0。 **String** 引號是選用的。逗號、新行及換行字元如果包含在由雙引號 (`"`) 包圍的字串中，將會自動逸出。*範例*：`"Hello, World"` 若要在引號字串中包含引號，您可以在同一列使用兩個引號以逸出引號，例如：**`"Hello ""World"""` 允許字串陣列，但陣列中的字串不能包含分號 (`;`) 字元，除非使用反斜線將其逸出 (像這樣：`\;`)。 如果您要使用引號包圍陣列中的字串，您必須以一組引號包圍整個陣列。*範例*：`"String one; String 2; String 3"` **Date** ISO-8601 格式的 Java 資料。支援下列格式：`yyyy-MM-dd`、`yyyy-MM-ddTHH:mm`、`yyyy-MM-ddTHH:mm:ss`、`yyyy-MM-ddTHH:mm:ssZ`。這些值會轉換為 epoch 時間並儲存。 **日期時間** ISO-8601 格式的 Java 資料。支援下列格式：`yyyy-MM-dd`、`yyyy-MM-ddTHH:mm`、`yyyy-MM-ddTHH:mm:ss`、`yyyy-MM-ddTHH:mm:ssZ`。這些值會轉換為 epoch 時間並儲存。 ## Gremlin 列格式 **分隔符號** 列中的欄位以逗號分隔。記錄以新行或新行後接換行符號加以分隔。 **空白欄位** 非必要欄允許使用空白欄位 (例如，使用者定義的屬性)。空白欄位仍然需要逗號分隔符號。必要資料欄上的空白欄位將導致剖析錯誤。空白字串值會解譯為 欄位的空白字串值，而不是空白欄位。下一節的範例在每個案例頂點中皆有空白欄位。 **頂點 ID** `~id` 值必須是每個頂點檔案的所有頂點中的唯一值。具有相同 `~id` 值的多個頂點列將套用至圖形中的單一頂點。空字串 (`""`) 是有效的 ID，而頂點是以空字串做為 ID 建立。 **邊緣 ID** 此外，`~id` 值必須是每個邊緣檔案的所有邊緣中的唯一值。具有相同 `~id` 值的多個邊緣列將套用至圖形中的單一邊緣。空字串 (`""`) 是有效的 ID，而邊緣是以空字串做為 ID 建立。 **標籤** 標籤區分大小寫，不能空白。的值`""`將導致錯誤。 **字串值** 引號是選用的。逗號、新行及換行字元如果包含在由雙引號 (`"`) 包圍的字串中，將會自動逸出。空白字串值`("")`會解譯為 欄位的空白字串值，而不是空白欄位。 ## CSV 格式規格 Neptune CSV 格式遵循 RFC 4180 CSV 規格，包括以下需求。 + 支援 Unix 和 Windows 樣式的行尾 (\$1n 或 \$1r\$1n)。 + 任何欄位皆可使用引號 (使用雙引號)。 + 內含分行符號、雙引號或逗號的欄位必須加上引號。(否則，將立即中止載入。) + 欄位中的雙引號字元 (`"`) 必須由兩個 (雙) 引號字元呈現。例如，`Hello "World"` 字串在資料中必須以 `"Hello ""World"""` 呈現。 + 分隔符號前後的空格將被忽略。如果資料列顯示為 `value1, value2`，則會將其儲存為 `"value1"`和 `"value2"`。 + 任何其他逸出字元將逐字儲存。例如，`"data1\tdata2"` 將儲存為 `"data1\tdata2"`。這些字元只要括在引號中，就不需要逸出。 + 允許空白欄位。空白欄位會視為空的值。 + 欄位中的多個值可在值之間使用分號 (`;`) 加以指定。 如需詳細資訊，請參閱 Internet Engineering Task Force (IETF) 網站上的 [Common Format and MIME Type for CSV Files](https://tools.ietf.org/html/rfc4180) (CSV 檔案的常見格式與 MIME 類型)。 ## Gremlin 範例 下圖顯示取自 TinkerPop Modern Graph 包含兩個頂點及一個邊緣的範例。 ![\[圖表描述兩個頂點及一個邊緣，包含 marko 29 歲及 lop 軟體與 lang:java。\]](http://docs.aws.amazon.com/zh_tw/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 資料庫執行個體](bulk-load-data.md)。 # openCypher 資料的載入格式 若要使用 OpenCypher CSV 格式載入 openCypher 資料，您必須在個別的檔案中指定節點和關係。載入器可以在單一載入工作中從其中多個節點檔案和關係檔案載入。 對於每個載入命令，要載入的檔案集必須在 Amazon Simple Storage Service 儲存貯體中具有相同的路徑字首。您可以在 source 參數中指定該字首。實際檔案名稱和副檔名並不重要。 在 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 資料載入檔案中的系統欄標頭 一個給定系統欄只能在每個檔案中出現一次。所有系統欄標頭標籤都會區分大小寫。 對於 OpenCypher 節點載入檔案和關係載入檔案，必要和允許的系統欄標頭有所不同： ### 節點檔案中的系統欄標頭 + **`:ID`**   –   (必要) 節點的 ID。 選用的 ID 空間可以新增至節點 `:ID` 欄標頭，如下所示：`:ID(ID Space)`。例如，`:ID(movies)`。 載入連線此檔案中節點的關係時，請在關係檔案 `:START_ID` 和/或 `:END_ID` 欄中使用相同的 ID 空間。 節點 `:ID` 欄可以選擇性地儲存為屬性，格式為 `property name:ID`。例如，`name:ID`。 在目前和先前載入的所有節點檔案中，節點 ID 應該是唯一的。如果使用 ID 空間，則在目前和之前載入中使用相同 ID 空間的所有節點檔案中，節點 ID 應該是唯一的。 + **`:LABEL`** – 節點的標籤。 對單一節點使用多個標籤值時，每個標籤應以分號 () 分隔`;`。 ### 關係檔案中的系統欄標頭 + **`: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 ``` 欄標頭中不允許空格、逗號、換行字元和換行字元，因此屬性名稱不能包含這些字元。以下是名為 `age` 且類型為 `Int` 之屬性的欄標頭範例： ``` 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"""`。 + **`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`** – 請參閱 [Neo4j Temporal Instants](https://neo4j.com/docs/cypher-manual/current/values-and-types/temporal/#cypher-temporal-instants)，以取得`date`、`localdate` 和 `localdatetime` 類型的說明。這些值會逐字載入為字串，無需驗證。 + **`Duration`** – 請參閱 [Neo4j Duration 格式](https://neo4j.com/docs/cypher-manual/current/values-and-types/temporal/#cypher-temporal-durations)。這些值會逐字載入為字串，無需驗證。 + **Point** – 用於儲存空間資料的點欄位。請參閱 [Spatial instants](https://neo4j.com/docs/cypher-manual/current/values-and-types/spatial/#spatial-values-spatial-instants)。這些值會逐字載入為字串，無需驗證。 ## openCypher 載入格式的範例 下圖取自 TinkerPop Modern Graph，其顯示兩個頂點及一個關係的範例。 ![\[兩個節點和它們之間關係的圖表。\]](http://docs.aws.amazon.com/zh_tw/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 ``` **第二個節點檔案：** ``` 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 載入資料格式 若要載入資源描述架構 (RDF) 資料，您可以使用以下其中一個標準格式，如全球資訊網協會 (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 資料庫執行個體](bulk-load-data.md)。 # 範例：將資料載入至 Neptune 資料庫執行個體 此範例說明如何將資料載入至 Amazon Neptune。除非另有說明，否則您必須在與 Neptune 資料庫執行個體相同的 Amazon Virtual Private Cloud (VPC) 中遵循這些來自 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體中的步驟。 ## 資料載入範例的先決條件 開始之前，您必須準備好以下項目： + Neptune 資料庫執行個體。 如需啟動 Neptune 資料庫執行個體的相關資訊，請參閱 [建立 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 可以使用逗號分隔值 (`CSV`) 格式載入資料，如 [Gremlin 載入資料格式](bulk-load-tutorial-format-gremlin.md) 中所述。 如果您使用 OpenCypher 來查詢您的圖形，Neptune 也可以載入 openCypher 特定 `CSV` 格式的資料，如 [openCypher 資料的載入格式](bulk-load-tutorial-format-opencypher.md) 中所述。 如果您使用的是 SPARQL，Neptune 可以使用多種 RDF 格式載入資料，如 [RDF 載入資料格式](bulk-load-tutorial-format-rdf.md) 中所述。 + Neptune 資料庫執行個體要擔任的 IAM 角色，其具有 IAM 政策，允許存取 S3 儲存貯體中的資料檔案。此政策必須授予讀取與列出許可。 如需建立可存取 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：//[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/) 的 Amazon VPC 主控台。 1. 在左側導覽窗格中選擇 **Endpoints** (端點)。 1. 選擇**建立端點**。 1. 選擇 **Service Name** (服務名稱) `com.amazonaws.region.s3`。 **注意** 如果此處的區域不正確，請務必確保主控台區域正確。 1. 選擇包含 Neptune 資料庫執行個體的 VPC。 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 資料庫執行個體** 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 儲存貯體。在 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 開啟 Amazon S3 主控台，然後選擇儲存貯體。在左上角，選擇 **Upload** (上傳) 以上傳檔案。 1. 從命令列視窗中，輸入以下命令，並使用端點、Amazon S3 路徑、格式和 IAM 角色 ARN 的正確值，來執行 Neptune 載入器。 `format` 參數可以是下列任何一個值：`csv` (適用於 Gremlin)、`opencypher` (適用於 openCypher) 或 `ntriples`、`nquads`、`turtle` 和 `rdfxml` (適用於 RDF)。如需有關其他參數的資訊，請參閱 [Neptune 載入器命令](load-api-reference-load.md)。 如需尋找 Neptune 資料庫執行個體主機名稱的相關資訊，請參閱 [連線至 Amazon Neptune 端點](feature-overview-endpoints.md) 一節。 區域參數必須符合叢集和 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"] }' ``` 如需建立 IAM 角色並將其與 Neptune 叢集建立關聯的相關資訊，請參閱 [必要條件：IAM 角色和 Amazon S3 存取](bulk-load-tutorial-IAM.md)。 **注意** 如需載入請求參數的詳細資訊，請參閱 [Neptune 載入器請求參數](load-api-reference-load.md#load-api-reference-load-parameters))。簡而言之： `source` 參數接受指向單一檔案或資料夾的 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` `format` 參數可為以下任一項： 用於 Gremlin 屬性圖的 Gremlin CSV 格式 (`csv`) 用於 openCypher 屬性圖的 openCypher CSV 格式 (`opencypher`) N -Triples (`ntriples`) 格式用於 RDF/SPARQL N-Quads (`nquads`) 格式用於 RDF/SPARQL RDF/XML (`rdfxml`) 格式用於 RDF/SPARQL Turtle (`turtle`) 格式用於 RDF/SPARQL 選用的 `parallelism` 參數可讓您限制大量載入程序所用的執行緒數目。它可以設定為 `LOW`、`MEDIUM`、`HIGH` 或 `OVERSUBSCRIBE`。 當 `updateSingleCardinalityProperties` 設為 `"FALSE"` 時，如果針對邊緣或單一基數頂點屬性所載入的來源檔案中提供了多個值，則載入器會傳回錯誤。 如果已有執行中的載入任務，則將 `queueRequest` 設為 `"TRUE"` 會造成載入請求置於佇列。 `dependencies` 參數會在已置於佇列的一或多個載入任務順利完成時執行載入請求。 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 載入器 Get-Status API](load-api-reference-status.md)。 1. (選用) 取消 `Load` 工作。 輸入以下命令，從**步驟 3** 中 `Delete` 具有工作 `id` 的載入器工作： ``` curl -X DELETE 'https://your-neptune-endpoint:port/loader/ef478d76-d9da-4d94-8ff1-08d9d4863aa5' ``` 成功取消時，`DELETE` 命令將傳回 HTTP 程式碼 `200 OK`。 來自已完成載入的載入工作的檔案資料不會還原。資料仍會保留在 Neptune 資料庫執行個體中。 # 最佳化 Amazon Neptune 大量載入 使用下列策略，讓 Neptune 大量載入保持最短的載入時間： + **清除您的資料：** + 載入之前，請務必將您的資料轉換為[支援的資料格式](bulk-load-tutorial-format.md)。 + 刪除任何重複內容或已知錯誤。 + 盡可能減少唯一述詞 (例如邊緣和頂點的屬性) 的數目。 + **最佳化您的檔案：** + 如果您從 Amazon S3 儲存貯體載入大型檔案 (例如 CSV 檔案)，載入器會透過將這些大型檔案剖析為其可以平行載入的區塊，來為您管理並行。使用大量小檔案可能會減慢此程序的速度。 + 如果您從 Amazon S3 字首載入多個檔案，載入器會自動先載入頂點檔案，之後再載入邊緣檔案。不過，如果您知道您只會載入邊緣檔案， `edgeOnlyLoad` 可以設定為`TRUE`略過掃描所有檔案以判斷其內容 （頂點或邊緣） 的第一道通道，以便在任何邊緣檔案之前載入找到的任何頂點檔案。這可以大幅加快載入時間，尤其是當涉及許多邊緣檔案時。如果某些頂點檔案也出現在相同的 Amazon S3 字首 (`source` 參數） 中，則會載入它們，但沒有相對於其他檔案的任何排序保證。此外，如果資料庫中不存在某些 `to` `from`或 頂點，邊緣插入可能會報告訊息 的錯誤`FROM_OR_TO_VERTEX_ARE_MISSING`。最佳實務是將節點和邊緣放在單獨的 Amazon S3 字首中。 + **檢查您的載入器設定：** + 如果您不需要在載入期間執行任何其他操作，請使用 [`OVERSUBSCRIBE``parallelism`](load-api-reference-load.md#load-api-reference-load-syntax) 參數。此參數設定會導致大量載入器在執行時使用所有可用的 CPU 資源。通常需要 60%-70% 的 CPU 容量，才能將操作的執行速度保持與 I/O 限制允許的速度一樣快。 **注意** 當 `parallelism` 設定為 `OVERSUBSCRIBE` 或 `HIGH` (預設設定) 時，載入 OpenCypher 資料時存在執行緒可能會遇到競爭條件和死結的風險，進而導致 `LOAD_DATA_DEADLOCK` 錯誤。在此情況下，請將 `parallelism` 設定為較低的設定，然後重試載入。 + 如果您的載入工作將包含多個載入請求，請使用 `queueRequest` 參數。將 `queueRequest` 設定為 `TRUE` 可讓 Neptune 將您的請求排入佇列，這樣您就不必等待一個請求完成後，再發出另一個請求。 + 如果您的載入請求正要排入佇列，您可以使用 `dependencies` 參數設定相依性層級，以便一個工作若失敗就會導致相依工作失敗。這樣可以防止載入的資料中出現不一致的情況。 + 如果載入工作將涉及更新先前載入的值，請務必將 `updateSingleCardinalityProperties` 參數設定為 `TRUE`。如果不這樣做，載入器會將嘗試更新現有的單一基數值視為錯誤。對於 Gremlin 資料，也會在屬性欄標頭中指定基數 (請參閱 [屬性欄標題](bulk-load-tutorial-format-gremlin.md#bulk-load-tutorial-format-gremlin-propheaders))。 **注意** 此`updateSingleCardinalityProperties`參數不適用於資源描述架構 (RDF) 資料。 + 您可以使用 `failOnError` 參數來決定發生錯誤時，大量載入操作應該失敗還是繼續。此外，您可以使用 `mode` 參數，來確定載入工作會從前一個工作失敗的那一點繼續載入，而不是重新載入已載入的資料。 + **縱向擴展** – 在大量載入之前，將資料庫叢集的寫入器執行個體設定為大小上限。請注意，如果這樣做，您必須同時縱向擴展資料庫叢集中的任何僅供讀取複本執行個體，或將其移除，直到完成載入資料為止。 當大量載入完成時，請務必再次縮減寫入器執行個體。 **重要** 如果您由於大量載入期間的複寫延遲而遭遇重複僅供讀取複本重新啟動的週期，則您的複本可能無法跟上資料庫叢集中的寫入器。將讀取器擴展為大於寫入器，或在大量載入期間暫時將其移除，然後在完成後重新建立這些讀取器。 如需設定載入器請求參數的詳細資訊，請參閱 [請求參數](load-api-reference-load.md#load-api-reference-load-parameters)。 # Neptune 載入器參考 本節描述適用於 Amazon Neptune 的 `Loader` API，其可從 Neptune 資料庫執行個體的 HTTP 端點取得。 **注意** 如需載入器在發生錯誤時傳回的錯誤和饋送訊息清單，請參閱 [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 載入器 Get-Status API](load-api-reference-status.md) + [Neptune 載入器 Get-Status 請求](load-api-reference-status-requests.md) + [載入器 Get-Status 請求語法](load-api-reference-status-requests.md#load-api-reference-status-request-syntax) + [Neptune 載入器 Get-Status 請求參數](load-api-reference-status-requests.md#load-api-reference-status-parameters) + [Neptune 載入器 Get-Status 回應](load-api-reference-status-response.md) + [Neptune 載入器 Get-Status 回應 JSON 配置](load-api-reference-status-response.md#load-api-reference-status-response-layout) + [Neptune 載入器 Get-Status `overallStatus` 和 `failedFeeds` 回應物件](load-api-reference-status-response.md#load-api-reference-status-response-objects) + [Neptune 載入器 Get-Status `errors` 回應物件](load-api-reference-status-response.md#load-api-reference-status-errors) + [Neptune 載入器 Get-Status `errorLogs` 回應物件](load-api-reference-status-response.md#load-api-reference-error-logs) + [Neptune 載入器 Get-Status 範例](load-api-reference-status-examples.md) + [載入狀態的請求範例](load-api-reference-status-examples.md#load-api-reference-status-examples-status-request) + [載入 ID 的請求範例](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 載入器 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 載入器取消工作](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 資料庫執行個體。 若要載入資料，您必須將 HTTP `POST` 請求傳送至 `https://your-neptune-endpoint:port/loader` 端點。您可以用 `POST` 本文或以 URL 編碼參數來傳送 `loader` 請求的參數。 **重要** MIME 類型必須是 `application/json`。 Amazon S3 儲存貯體必須與叢集位於相同的 AWS 區域。 **注意** 您可以從 Amazon S3 載入加密的資料 (如果它是使用 Amazon S3 `SSE-S3` 模式加密的)。在這種情況下，Neptune 可以模擬您的憑證，並代表您發出 `s3:getObject` 呼叫。 您也可以從 Amazon S3 載入使用 `SSE-KMS` 模式加密的加密資料，只要您的 IAM 角色包含存取 AWS KMS的必要許可。如果沒有適當的 AWS KMS 許可，大量載入操作會失敗並傳回`LOAD_FAILED`回應。 Neptune 目前不支援載入使用 `SSE-C` 模式加密的 Amazon S3 資料。 您不必等待一個載入工作完成，然後再啟動另一個工作。Neptune 最多可以一次將 64 個工作排入佇列，前提是其 `queueRequest` 參數全都設為 `"TRUE"`。工作的佇列順序將為先進先出 (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` 參數接受可識別單一檔案、多個檔案、一個資料夾或多個資料夾的 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 呼叫中的 [prefix](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html#API_ListObjects_RequestParameters) 參數。它會識別所指定 Amazon S3 儲存貯體中其名稱以該字首開頭的所有物件。這可以是單一檔案或資料夾，也可以是多個檔案和/或資料夾。 一個或多個指定的資料夾可以包含多個頂點檔案和多個邊緣檔案。 例如，如果您在名為 的 Amazon S3 儲存貯體中具有下列資料夾結構和檔案`bucket-name`： ``` s3://bucket-name/a/bc s3://bucket-name/ab/c s3://bucket-name/ade s3://bucket-name/bcd ``` 如果來源參數指定為 `s3://bucket-name/a`，則會載入前三個檔案。 ``` 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`** – Neptune 資料庫執行個體為了存取 S3 儲存貯體 而擔任之 IAM 角色的 Amazon Resource Name (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 資料庫執行個體和 Amazon S3 儲存貯體位於不同的 AWS 帳戶中，您也可以鏈結多個 IAM 角色。在此情況下，`iamRoleArn` 會包含逗號分隔的角色 ARN 清單，如 [在 Amazon Neptune 中鏈結 IAM 角色](bulk-load-tutorial-chain-roles.md) 中所述。例如： ``` 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` – 使用的執行緒數目是可用 vCPU 除以 8 後的數字。 + `MEDIUM` – 使用的執行緒數目是可用 vCPU 除以 2 後的數字。 + `HIGH` – 使用的執行緒數目與可用 vCPU 的數目相同。 + `OVERSUBSCRIBE` – 使用的執行緒數目是可用 vCPU 乘以 2 後的數字。如果使用此值，大量載入器會佔用所有可用的資源。 不過，這並不表示 `OVERSUBSCRIBE` 設定會產生 100% CPU 使用率。由於載入操作受 I/O 限制，因此預期的最高 CPU 使用率在 60％ 到 70％ 的範圍內。 *預設值*：`HIGH` 載入 OpenCypher 資料時，`parallelism` 設定有時可能會導致執行緒之間發生死結。發生這種情況時，Neptune 會傳回 `LOAD_DATA_DEADLOCK` 錯誤。通常，您可以透過將 `parallelism` 設定為較低的設定，並重試載入命令來修正此問題。 + **`parserConfiguration`** – 包含額外剖析器組態值的選用物件。也可選用每個子參數： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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"` 時，大量載入器會以新的值取代現有的值。如果在要載入的來源檔案中提供多個邊緣或單一基數頂點屬性值，則大量載入結尾的最終值可以是這些新值的其中之一。載入器只會保證現有的值已由其中一個新值取代。 + **`queueRequest`** – 此為選用標記參數，用以指示載入請求能否排入佇列。 您不必等到載入工作完成才能發出另一個載入工作，因為 Neptune 最多可以一次將 64 個工作排入佇列，前提是其 `queueRequest` 參數都設為 `"TRUE"`。工作的佇列順序將為先進先出 (FIFO)。 如果 `queueRequest` 參數遭省略或設為 `"FALSE"`，且已有其他執行中的載入任務，則此載入請求將失敗。 *允許的值*：`"TRUE"`、`"FALSE"`。 *預設值*：`"FALSE"`。 + **`dependencies`** – 這是選用參數，可在一或多個佇列中先前工作順利完成時，發出佇列載入請求。 Neptune 最多可以一次將 64 個載入請求排入佇列，前提是其 `queueRequest` 參數設為 `"TRUE"`。`dependencies` 參數可讓您在一或多個佇列中指定的先前請求順利完成時，執行這類佇列請求。 例如，如果載入 `Job-A` 和 `Job-B` 彼此獨立，但載入 `Job-C` 須先完成 `Job-A` 和 `Job-B` 才能開始，請依照指示執行： 1. 以任何順序一個接著一個提交 `load-job-A` 和 `load-job-B`，並儲存其載入 ID。 1. 使用兩任務其 `dependencies` 欄位中的載入 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`。 您可以使用這種方式設定多個相依性層級，如此一來，一項任務若失敗，將導致直間接仰賴該任務的所有請求遭取消。 + **`userProvidedEdgeIds`** – 只有在載入包含關係 ID 的 OpenCypher 資料時，才需要這個參數。在載入資料中明確提供 OpenCypher 關係 ID 時，必須包含它並設定為 `True` (建議使用)。 如果 `userProvidedEdgeIds` 不存在或設定為 `True`，則載入中的每個關係檔案中都必須存在一個 `:ID` 欄。 當 `userProvidedEdgeIds` 存在且設定為 `False` 時，載入中的關係檔案**不得**包含 `:ID` 欄。相反地，Neptune 載入器會自動為每個關係產生一個 ID。 明確提供關係 ID 很有用，如此一來，載入器就可以在 CSV 資料中的錯誤完成修正之後繼續載入，而不必重新載入任何已載入的關係。如果尚未明確指派關係 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 資料的特殊考量 + 以 CSV 格式載入 openCypher 資料時，必須將格式參數設定為 `opencypher`。 + 不支援 `updateSingleCardinalityProperties` 參數用於 openCypher 載入，因為所有 openCypher 屬性都有單一基數。OpenCypher 載入格式不支援陣列，而且如果 ID 值出現多次，則系統會將其視為重複或插入錯誤 (請參閱下文)。 + Neptune 載入器會處理它在 OpenCypher 資料中遇到的重複項目，如下所示： + 如果載入器遇到多個具有相同節點 ID 的資料列，則會使用下列規則合併它們： + 資料列行中的所有標籤現在會新增至節點。 + 對於每個屬性，只會載入其中一個屬性值。選取要載入哪一個是不具確定性的。 + 如果載入器遇到多個具有相同關係 ID 的資料列，則只會載入其中一個資料列。選取要載入哪一個是不具確定性的。 + 如果載入器遇到具有現有節點或關係 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 載入器錯誤 發生錯誤時，回應的 `BODY` 中會傳回 JSON 物件。`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 資料庫執行個體位於相同的 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 載入器範例 此範例示範如何使用 Gremlin CSV 格式，使用 Neptune 載入器將資料載入 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 載入器 Get-Status API 取得 `loader` 工作的狀態。 若要取得載入狀態，您必須將 HTTP `GET` 請求傳送至 `https://your-neptune-endpoint:port/loader` 端點。若要取得特定載入請求的狀態，您必須包含 `loadId` 做為 URL 參數，或將 `loadId` 連接到 URL 路徑。 Neptune 只會追蹤最近 1,024 個大量載入任務，並且只會存放每個任務的最後 10,000 個錯誤詳細資訊。 如需載入器在發生錯誤時傳回的錯誤和饋送訊息清單，請參閱 [Neptune 載入器的錯誤和饋送訊息](loader-message.md)。 **Contents** + [Neptune 載入器 Get-Status 請求](load-api-reference-status-requests.md) + [載入器 Get-Status 請求語法](load-api-reference-status-requests.md#load-api-reference-status-request-syntax) + [Neptune 載入器 Get-Status 請求參數](load-api-reference-status-requests.md#load-api-reference-status-parameters) + [Neptune 載入器 Get-Status 回應](load-api-reference-status-response.md) + [Neptune 載入器 Get-Status 回應 JSON 配置](load-api-reference-status-response.md#load-api-reference-status-response-layout) + [Neptune 載入器 Get-Status `overallStatus` 和 `failedFeeds` 回應物件](load-api-reference-status-response.md#load-api-reference-status-response-objects) + [Neptune 載入器 Get-Status `errors` 回應物件](load-api-reference-status-response.md#load-api-reference-status-errors) + [Neptune 載入器 Get-Status `errorLogs` 回應物件](load-api-reference-status-response.md#load-api-reference-error-logs) + [Neptune 載入器 Get-Status 範例](load-api-reference-status-examples.md) + [載入狀態的請求範例](load-api-reference-status-examples.md#load-api-reference-status-examples-status-request) + [載入 ID 的請求範例](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 載入器 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 載入器 Get-Status 請求 ## 載入器 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 載入器 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 數目。僅適用於藉由傳送 `GET` 請求且未指定 `loadId` 以請求載入 ID 清單時。 *允許值*：1 到 100 的正整數。 *預設值*：100。 + **`includeQueuedLoads`** – 請求載入 ID 清單時，選用參數可用來排除佇列中載入請求的載入 ID。 依預設，所有狀態為 `LOAD_IN_QUEUE` 的載入任務的載入 ID 都包含在這類清單中。它們會出現在其他任務的載入 ID 之前，依加入佇列的時間，從最近到最早進行排序。 *允許的值*：`TRUE`、`FALSE`。 *預設值*：`TRUE`。 # Neptune 載入器 Get-Status 回應 下列來自 Neptune Get-Status API 的範例回應說明回應的整體結構、說明各種欄位及其資料類型，以及錯誤處理和錯誤日誌詳細資訊。 ## Neptune 載入器 Get-Status 回應 JSON 配置 載入器狀態回應的一般配置如下： ``` { "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 載入器 Get-Status `overallStatus` 和 `failedFeeds` 回應物件 針對每個失敗饋送傳回的可能回應 (包括錯誤描述) 與 `Get-Status` 回應中的 `overallStatus` 物件相同。 以下欄位會出現在所有載入的 `overallStatus` 物件中，以及每個失敗饋送的 `failedFeeds` 物件中。 + **`fullUri`** – 要載入的一個或多個檔案的 URI。 *類型*：*字串* *格式*：`s3://bucket/key`。 + **`runNumber`** – 此載入或饋送的執行數量。它會在載入重新啟動時遞增。 *類型：**unsigned long*。 + **`retryNumber`** – 此載入或饋送的重試次數。它會在載入器自動重試饋送或載入時遞增。 *類型：**unsigned long*。 + **`status`** – 載入或饋送傳回的狀態。`LOAD_COMPLETED` 表示成功載入，沒有發生問題。如需其他 load-status 訊息的清單，請參閱 [Neptune 載入器的錯誤和饋送訊息](loader-message.md)。 *類型：**字串*。 + **`totalTimeSpent`** – 載入或饋送時用於剖析及插入資料的時間 (以秒為單位)。這不包含擷取原始檔案清單所花費的時間。 *類型：**unsigned long*。 + **`totalRecords`** – 已載入或嘗試載入的記錄總數。 *類型：**unsigned 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`** – 遇到的重複記錄數目。 *類型：**unsigned 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`** – 遇到的剖析錯誤數目。 *類型：**unsigned long*。 + **`datatypeMismatchErrors`** – 資料類型與給定資料不符的記錄數目。 *類型：**unsigned long*。 + **`insertErrors`** – 由於錯誤而無法插入的記錄數目。 *類型：**unsigned long*。 ## Neptune 載入器 Get-Status `errors` 回應物件 錯誤分為以下類別： + **`Error 400`** – 無效的 `loadId` 會傳回 HTTP `400` 錯誤的請求錯誤。描述錯誤的訊息。 + **`Error 500`** – 無法處理的有效請求會傳回 HTTP `500` 內部伺服器錯誤。描述錯誤的訊息。 如需載入器在發生錯誤時傳回的錯誤和饋送訊息清單，請參閱 [Neptune 載入器的錯誤和饋送訊息](loader-message.md)。 發生錯誤時，回應的 `BODY` 中會傳回 JSON `errors` 物件，具有下列欄位： + **`startIndex`** – 第一個包含的錯誤的索引。 *類型：**unsigned long*。 + **`endIndex`** – 最後一個包含的錯誤的索引。 *類型：**unsigned long*。 + **`loadId`** – 載入的 ID。您可以使用此 ID 並將 `errors` 參數設為 `TRUE` 以列印載入的錯誤。 *類型：**字串*。 + **`errorLogs`** – 錯誤清單。 *類型：**清單*。 ## Neptune 載入器 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`** – 描述錯誤的訊息。 這可以是與錯誤代碼相關聯的一般訊息，或包含詳細資訊的特定訊息，例如關於遺失來源/目標頂點或關於剖析錯誤。 + **`fileName`** – 饋送的名稱。 + **`recordNum`** – 在發生剖析錯誤的情況下，這是無法剖析的記錄在檔案中的記錄編號。如果記錄編號不適用於錯誤，或無法確定，則其設定為零。 例如，如果大量載入器在 RDF `nquads` 檔案中遇到如下的錯誤資料列，則會產生剖析錯誤： ``` |http://base#predicate> . ``` 如您所見，上面資料列中的第二個 `http` 應該在其前加上 `<` 而不是 `|`。狀態回應中 `errorLogs` 下產生的錯誤物件看起來像這樣： ``` { "errorCode" : "PARSING_ERROR", "errorMessage" : "Expected '<', found: |", "fileName" : "s3://bucket/key", "recordNum" : 12345 }, ``` # Neptune 載入器 Get-Status 範例 下列範例示範 Neptune 載入器 GET-Status API 的使用方式，可讓您擷取資料載入至 Amazon Neptune 圖形資料庫狀態的相關資訊。這些範例涵蓋三個主要案例：擷取特定負載的狀態、列出可用的負載 IDs，以及請求特定負載的詳細狀態資訊。 ## 載入狀態的請求範例 以下是使用 `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 } } } ``` ## 載入 ID 的請求範例 以下是使用 `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 載入器 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 載入器取消工作 取消載入工作。 若要取消工作，則必須傳送 HTTP `DELETE`請求至 `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` 程式碼。 ## 取消任務錯誤 發生錯誤時，回應的 `BODY` 中會傳回 JSON 物件。`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 Database Migration Service 使用者指南](https://docs.aws.amazon.com/dms/latest/userguide/)和 [AWS Database Migration Service API 參考](https://docs.aws.amazon.com/dms/latest/APIReference/) AWS DMS 中找到有關 的詳細資訊。尤其，您可以在[使用 Amazon Neptune 做為 AWS Database Migration Service的目標](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Target.Neptune.html)中了解如何將 Neptune 叢集設定為遷移目標。 以下是使用 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 `GraphMappingConfig`，以指定擷取自來源資料庫的資料應如何載入至 Neptune。對於 RDF 資料 (使用 SPARQL 查詢得來)，`GraphMappingConfig` 是採用 W3 的標準 [R2RML](https://www.w3.org/TR/r2rml/) 對應語言編寫。對於屬性圖資料 (使用 Gremlin 查詢得來)，`GraphMappingConfig` 是 [屬性圖形/Gremlin 資料的 GraphMappingConfig 配置](dms-neptune-graph-mapping.md#dms-neptune-graph-mapping-gremlin) 中所述的 JSON 物件。 + 您必須使用 AWS DMS 在與 Neptune 資料庫叢集相同的 VPC 中建立複寫執行個體，以調解資料傳輸。 + 您還需要一個 Amazon S3 儲存貯體做為暫存遷移資料的中繼儲存體。 # 建立 Neptune GraphMappingConfig 您建立的 `GraphMappingConfig` 指定應如何將擷取自來源資料存放區的資料載入至 Neptune 資料庫叢集。它的格式取決於它是用於載入 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 語言。以下是一個範例： ``` @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 建議中提供了語言的詳細資訊。 ## 屬性圖形/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 資料庫叢集的 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 DMS [CreateEndpoint](https://docs.aws.amazon.com/dms/latest/APIReference/API_CreateEndpoint.html) API， AWS CLI 如下所示： ``` 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) ``` ## 設定 Amazon S3 儲存貯體供 Neptune 用於預備資料 如果您沒有可用於暫存資料的 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)所述建立儲存貯體。 如果您還沒有 IAM 政策，您必須建立一個 IAM 政策，將 `GetObject`、`PutObject`、`DeleteObject` 和 `ListObject` 許可授與儲存貯體： ------ #### [ 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 資料庫叢集已啟用 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 資料庫叢集。這將允許 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 資料庫叢集建立 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`參數中 API 的 AWS DMS `CreateEndpoint` JSON 物件具有下列欄位： **** + **`ServiceAccessRoleArn`** – *(必要)* IAM 角色的 ARN，此角色允許精細存取 S3 儲存貯體，此儲存貯體用來暫存遷移至 Neptune 的資料。此角色也應具有存取 Neptune 資料庫叢集的許可 (如果該叢集已啟用 IAM 授權)。 + **`S3BucketName`** – *(必要)* 若是完整載入遷移，複寫執行個體會將所有 RDS 資料轉換為 CSV、四元組檔案，並將它們上傳到 S3 中的這個暫存儲存貯體，然後再大量載入至 Neptune。 + **`S3BucketFolder`** – *(必要)* 要在 S3 暫存儲存貯體中使用的資料夾。 + **`ErrorRetryDuration`** – *(選用)* Neptune 請求失敗後，再次提出重試請求之前要等待的毫秒數。預設值為 250。 + **`MaxRetryCount`**   – *（選用）* 在可重試失敗之後 AWS DMS ，應提出的重試請求數目上限。預設值為 5。 + **`MaxFileSize`** – *(選用)* 遷移期間儲存至 S3 的每個暫存檔案的大小上限 (以位元組為單位)。預設值為 1,048,576 KB (1 GB)。 + **`IsIAMAuthEnabled`** – *選用)* 如果已在 Neptune 資料庫叢集上啟用 IAM 驗證，則設為 `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 複寫任務 一旦成功完成了先前的步驟，請使用如下的 AWS DMS [CreateReplicationTask](https://docs.aws.amazon.com/dms/latest/APIReference/API_CreateReplicationTask.html.html) API 建立複寫工作，將資料從來源資料存放區遷移至 Neptune： ``` 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` 參數提供 [GraphMappingConfig](dms-neptune-graph-mapping.md)，其會指定所複製資料應該如何儲存在 Neptune 中。 ## 啟動 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、`INSERT`SPARQL 或 `mergeE()` Gremlin `CREATE``MERGE`中的 `mergeV()`和 等標準寫入操作來新增或修改圖形中的資料。這些操作適用於增量更新和交易寫入。 若要從 Amazon S3 載入資料，請[使用 Amazon Neptune 大量載入器擷取資料](bulk-load.md)針對需要最佳化效能的大型資料集使用 。對於一或多個 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`操作會將 RDF 資料從 URI 匯入具名圖形。 會將資料從圖形`UNLOAD`匯出至 Amazon S3。 ``` 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)。