本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 將 Gremlin 查詢結果匯出至 Amazon S3
<a name="exporting-gremlin"></a>

 從引擎 1.4.3.0 版開始，Amazon Neptune 支援將 Gremlin 查詢結果直接匯出至 Amazon S3。此功能可讓您有效率地處理大型查詢結果，方法是將結果匯出至 Amazon S3 儲存貯體，而不是將其做為查詢回應傳回。

 若要將查詢結果匯出至 Amazon S3，請使用 `call()` 步驟搭配`neptune.query.exportToS3`服務名稱做為 Gremlin 查詢中的最後一個步驟。[使用 Bytecode 的 Tinkerpop 驅動程式](https://tinkerpop.apache.org/docs/current/reference/#terminal-steps)中的終端機`call()`步驟可以在步驟之後新增。匯出參數必須以字串值提供。

**注意**  
 如果未使用 做為最終`call()`步驟，則具有 之步驟的查詢`neptune.query.exportToS3`將會失敗。使用位元組碼的 Gremlin 用戶端可以使用終端機步驟。如需詳細資訊，請參閱 Amazon Neptune 文件中的 [ Gremlin 最佳實務](https://docs.aws.amazon.com//neptune/latest/userguide/best-practices-gremlin-java-bytecode.html)。

```
g.V()
  ...
  .call('neptune.query.exportToS3', [
    'destination': 's3://your-bucket/path/result.json',
    'format': 'GraphSONv3',
    'kmskeyArn': 'optional-kms-key-arn'
  ])
```

**Parameters**
+  `destination`：必要 - 寫入結果的 Amazon S3 URI。
+  `format`：必要 - 輸出格式，目前僅支援 '[GraphSONv3](https://tinkerpop.apache.org/docs/3.7.3/dev/io/#graphson-3d0)'。
+  `keyArn`：選用 - Amazon S3 [ 伺服器端加密](https://docs.aws.amazon.com//AmazonS3/latest/userguide/serv-side-encryption.html)AWS KMS金鑰的 ARN。

## 範例
<a name="exporting-gremlin-examples"></a>

 **查詢範例** 

```
g.V().
    hasLabel('Comment').
    valueMap().
    call('neptune.query.exportToS3', [
    'destination': 's3://your-bucket/path/result.json',
    'format': 'GraphSONv3',
    'keyArn': 'optional-kms-key-arn'
  ])
```

 **查詢回應範例** 

```
{
    "destination":"s3://your-bucket/path/result.json,
    "exportedResults": 100,
    "exportedBytes": 102400
}
```

## 先決條件
<a name="exporting-gremlin-prerequisites"></a>
+  您的 Neptune 資料庫執行個體必須透過類型閘道的 VPC 端點存取 Amazon S3。
+  若要在查詢中使用自訂AWS KMS加密，AWS KMS需要 的界面類型 VPC 端點，才能允許 Neptune 與 通訊AWS KMS。
+  您必須在 Neptune 上啟用 IAM 驗證，並具有寫入目標 Amazon S3 儲存貯體的適當 IAM 許可。否則會導致 400 個錯誤的請求錯誤「叢集必須針對 S3 匯出啟用 IAM 身分驗證」。
+  目標 Amazon S3 儲存貯體：
  +  目標 Amazon S3 儲存貯體不得為公有。 `Block public access` 必須啟用 。
  +  目標 Amazon S3 目的地必須為空。
  +  目標 Amazon S3 儲存貯體必須在具有 `Delete expired object delete markers or incomplete multipart uploads`的 上具有生命週期規則`Delete incomplete multipart uploads`。如需詳細資訊[，請參閱 Amazon S3 生命週期管理更新 - 支援分段上傳和刪除標記](https://aws.amazon.com/blogs/aws/s3-lifecycle-management-update-support-for-multipart-uploads-and-delete-markers/)。  
![\[顯示生命週期規則動作的影像。\]](http://docs.aws.amazon.com/zh_tw/neptune/latest/userguide/images/lifecycleRuleActions.png)
  +  目標 Amazon S3 儲存貯體必須在 上設定生命週期規則，`Delete expired object delete markers or incomplete multipart uploads`並將 `Delete incomplete multipart uploads` 設為高於查詢評估所需的值 （例如 7 天）。如果 Neptune 無法完成或中止上傳 （例如，由於執行個體/引擎故障），則刪除不完整的上傳 （不直接顯示但會產生成本） 需要此項目。如需詳細資訊[，請參閱 Amazon S3 生命週期管理更新 - 支援分段上傳和刪除標記](https://aws.amazon.com/blogs/aws/s3-lifecycle-management-update-support-for-multipart-uploads-and-delete-markers/)。  
![\[顯示生命週期規則動作，以及刪除過期物件刪除標記的影像。\]](http://docs.aws.amazon.com/zh_tw/neptune/latest/userguide/images/lifecycleRuleActionsDelete.png)

**重要考量**
+  匯出步驟必須是 Gremlin 查詢中的最後一個步驟。
+  如果物件已存在於指定的 Amazon S3 位置，查詢將會失敗。
+  匯出查詢的查詢執行時間上限為 11 小時 50 分鐘。此功能使用[轉送存取工作階段](https://docs.aws.amazon.com//IAM/latest/UserGuide/access_forward_access_sessions.html)。目前限制為 11 小時 50 分鐘，以避免權杖過期問題。
**注意**  
 匯出查詢仍會遵守查詢逾時。對於大型匯出，您應該使用適當的查詢逾時。
+  所有上傳至 Amazon S3 的新物件都會自動加密。
+  為了避免在發生錯誤或當機時未完成分段上傳造成的儲存成本，建議您在 Amazon S3 儲存貯體`Delete incomplete multipart uploads`上使用 設定生命週期規則。

## 回應格式
<a name="exporting-gremlin-response"></a>

 查詢不會直接傳回查詢結果，而是傳回有關匯出操作的中繼資料，包括狀態和匯出詳細資訊。Amazon S3 中的查詢結果將採用 [GraphSONv3](https://tinkerpop.apache.org/docs/3.7.3/dev/io/#graphson-3d0) 格式。

```
{
  "data": {
    "@type": "g:List",
    "@value": [
      {
        "@type": "g:Map",
        "@value": [
          "browserUsed",
          {
            "@type": "g:List",
            "@value": [
              "Safari"
            ]
          },
          "length",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Int32",
                "@value": 7
              }
            ]
          },
          "locationIP",
          {
            "@type": "g:List",
            "@value": [
              "192.0.2.0/24"
            ]
          },
          "creationDate",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Date",
                "@value": 1348341961000
              }
            ]
          },
          "content",
          {
            "@type": "g:List",
            "@value": [
              "no way!"
            ]
          }
        ]
      },
      {
        "@type": "g:Map",
        "@value": [
          "browserUsed",
          {
            "@type": "g:List",
            "@value": [
              "Firefox"
            ]
          },
          "length",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Int32",
                "@value": 2
              }
            ]
          },
          "locationIP",
          {
            "@type": "g:List",
            "@value": [
              "203.0.113.0/24"
            ]
          },
          "creationDate",
          {
            "@type": "g:List",
            "@value": [
              {
                "@type": "g:Date",
                "@value": 1348352960000
              }
            ]
          },
          "content",
          {
            "@type": "g:List",
            "@value": [
              "ok"
            ]
          }
        ]
      },
      
      
      ...
      
      
    ]
  }
}
```

**安全**
+  傳輸至 Amazon S3 的所有資料都會使用 SSL 在傳輸中加密。
+  您可以為匯出的資料指定伺服器端加密的AWS KMS金鑰。根據預設，Amazon S3 會加密新資料。如果儲存貯體設定為使用特定AWS KMS金鑰，則會使用該金鑰。
+  Neptune 會在開始匯出之前驗證目標儲存貯體是否為公有。
+  不支援跨帳戶和跨區域匯出。

**錯誤處理**
+  目標 Amazon S3 儲存貯體為公有。
+  指定的物件已存在。
+  您沒有足夠的許可來寫入 Amazon S3 儲存貯體。
+  查詢執行超過時間限制上限。

**最佳實務**
+  使用 Amazon S3 儲存貯體生命週期規則來清除未完成的分段上傳。
+  使用 Neptune 日誌和指標監控匯出操作。您可以檢查 [Gremlin 狀態端點](https://docs.aws.amazon.com//neptune/latest/userguide/gremlin-api-status.html)，查看查詢目前是否正在執行。只要用戶端未收到回應，就會假設查詢正在執行。

# 授予 Gremlin Amazon S3 匯出功能的存取權
<a name="granting-access-gremlin"></a>

 **必要的 IAM 政策** 

1.  **Neptune 查詢讀取存取** 

   ```
   {
     "Sid": "NeptuneQueryRead",
     "Effect": "Allow",
     "Action": ["neptune-db:Read*"],
     "Resource": "arn:aws:neptune-db:us-east-1:123456789012:cluster-ABCD12/*"
   }
   ```

    **為什麼需要：**此許可允許從 Neptune 資料庫讀取資料，這對於執行將匯出的 Gremlin 查詢是必要的。上一個範例允許讀取查詢。對於讀取/寫入查詢，需要寫入/刪除許可。

1.  **Amazon S3 匯出許可** 

   ```
   {
     "Sid": "NeptuneS3Export",
     "Effect": "Allow",
     "Action": [
       "s3:ListBucket",
       "s3:PutObject",
       "s3:AbortMultipartUpload",
       "s3:GetBucketPublicAccessBlock"
     ],
     "Resource": "arn:aws:s3:::neptune-export-bucket/*"
   }
   ```

    **為什麼需要每個許可：**
   +  `s3:ListBucket`：驗證儲存貯體是否存在並列出內容時需要。
   +  `s3:PutObject`：將匯出的資料寫入 Amazon S3 時需要。
   +  `s3:AbortMultipartUpload`：在匯出失敗時清除未完成的分段上傳時需要。
   +  `s3:GetBucketPublicAccessBlock`：作為安全措施的必要項目，以在匯出資料之前驗證儲存貯體不是公有的。

1.  **AWS KMS許可 **- 選用。只有在使用自訂AWS KMS加密時才需要。

   ```
   {
     "Sid": "NeptuneS3ExportKMS",
     "Effect": "Allow",
     "Action": [
       "kms:Decrypt",
       "kms:GenerateDataKey",
       "kms:DescribeKey"
     ],
     "Resource": "arn:aws:kms:<REGION>:<AWS_ACCOUNT_ID>:key/mrk-48971c37"
       "Condition": {
       "StringEquals": {
         "kms:ViaService": [
           "s3.<REGION>.amazonaws.com",
           "rds.<REGION>.amazonaws.com"
         ]
       }
     }
   }
   ```

    **為什麼需要每個許可：**
   +  `kms:Decrypt`：解密資料加密的AWS KMS金鑰時需要。
   +  `kms:GenerateDataKey`：產生用於加密匯出資料的資料金鑰時需要。
   +  `kms:DescribeKey`：驗證和擷取AWS KMS金鑰的相關資訊時需要。
   +  `kms:ViaService`：強制此角色不可將此金鑰用於任何其他 AWS服務，以提高安全性。

**重要先決條件**
+  **IAM 身分驗證：**必須在 Neptune 叢集上啟用，才能強制執行這些許可。
+  **VPC 端點：**
  +  需要 Amazon S3 的閘道類型 VPC 端點，才能允許 Neptune 與 Amazon S3 通訊。
  +  若要在查詢中使用自訂AWS KMS加密，AWS KMS需要 的界面類型 VPC 端點，才能允許 Neptune 與 通訊AWS KMS。
+  **Amazon S3 儲存貯體組態：**
  +  不得為公有。
  +  應該有生命週期規則來清除未完成的分段上傳。
  +  將自動加密新物件。

 這些許可和先決條件可確保安全可靠的 Gremlin 查詢結果匯出，同時維持適當的存取控制和資料保護措施。