本頁面由 Cloud Translation API 翻譯而成。

匯出 CSV 檔案

本頁面說明如何將 AlloyDB for PostgreSQL 叢集的資料匯出至 Cloud Storage 值區，並以 CSV 格式儲存，供其他工具和環境使用。

如要瞭解如何將整個資料庫從支援的資料庫伺服器遷移至新的 AlloyDB 執行個體，請參閱「使用資料庫遷移服務，將資料庫遷移至 AlloyDB」。如果您是為了從匯出檔案建立新執行個體而匯出，請考慮從儲存的備份還原叢集。

您可以取消匯出 PostgreSQL 適用的 AlloyDB 叢集資料。詳情請參閱「取消匯出資料」。

事前準備

開始匯出作業前，請注意匯出作業會使用資料庫資源，但除非執行個體資源不足，否則不會干擾標準資料庫作業。
SELECT_QUERY 可以包含註解或開頭和結尾的空白字元。系統會忽略註解並修剪空白字元，然後執行匯出查詢。
如果目標 bucket 與來源叢集位於不同區域，則需支付跨區域資料移轉費用。詳情請參閱 PostgreSQL 適用的 AlloyDB 定價。
多個匯出作業可以平行執行。
如果物件名稱結尾為 .gz 擴充功能，系統就會啟用壓縮功能。接著，系統會以 .gz 格式將物件匯出至 Cloud Storage。
在 CSV 選項 (例如 field_delimiter、quote_character 和 escape_character) 中，字元值只能是十六進位代碼中的 ASCII 字元 (可有或沒有 0x 前置字元)。

從 AlloyDB 匯出資料所需的角色和權限

如要將 AlloyDB 資料匯出至 Cloud Storage，發起匯出的使用者必須具備下列其中一個 Identity and Access Management (IAM) 角色：

Cloud AlloyDB 管理員 (roles/alloydb.admin) 角色
自訂角色，包括下列權限：
- alloydb.clusters.get
- alloydb.clusters.export

此外，AlloyDB 叢集的服務帳戶必須具備下列其中一個角色：

storage.objectAdmin IAM 角色
自訂角色，包括下列權限：
- storage.objects.create

如需 IAM 角色相關說明，請參閱身分與存取權管理。

將資料匯出為 CSV 檔案

匯出 CSV 檔案時，您可以指定要匯出的結構定義。資料庫層級的所有結構定義都符合匯出資格。

您可以使用 gcloud CLI 或 REST API 自訂 CSV 檔案格式。

gcloud

建立 Cloud Storage 值區。
授予服務帳戶 Cloud Storage 值區的權限，以進行匯出作業。使用服務帳戶格式，找出要匯出資料的專案所用服務帳戶。服務帳戶的格式如下：
```
service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
使用 gcloud storage buckets add-iam-policy-binding 將 storage.objectAdmin 身分與存取權管理角色授予服務帳戶。如需設定 IAM 權限的說明，請參閱「使用 IAM 權限」。

注意： 如果現有物件的名稱與要匯出至 Cloud Storage 值區的物件相同，則授予服務帳戶 objectAdmin 角色會導致舊物件遭到取代。為避免發生這種情況，您可以授予服務帳戶權限較低的 storage.objectCreator 權限，這項權限無法取代現有物件。
將資料庫匯出至 Cloud Storage bucket。

執行匯出 CSV 指令： gcloud alloydb clusters export。

下表列出以 CSV 格式匯出資料的選項：
- --select-query (必要)：用於擷取資料的 SELECT 查詢。
注意： 在傳輸期間，查詢可能會在目標執行個體位置以外的中間位置處理。
- --async (選用)：立即傳回，不必等待進行中的作業完成。
- --field-delimiter (選用)：指定檔案中每列 (行) 的欄分隔字元。預設值為半形逗號。這個引數的值必須是十六進位 ASCII 碼中的字元。
- --quote-character (選用)：指定在引用資料值時使用的引號字元。預設為雙引號。這個引數的值必須是十六進制 ASCII 碼中的字元。
- --escape-character (選用)：指定必須出現在需要逸出資料字元之前的字元。預設值與 --quote-character 相同。這個引數的值必須是十六進位 ASCII 程式碼中的字元。
如要使用這些功能，請在 gcloud CLI 指令中加入這些選項。

否則，請從下列指令中移除這些參數：
```
gcloud alloydb clusters export CLUSTER_NAME
  --region=REGION
  --database=DATABASE_NAME
  --gcs-uri="gs://BUCKET_NAME/OBJECT_NAME"
  --select-query=SELECT_QUERY
  --field-delimiter=FIELD_DELIMITER
  --quote-character=QUOTE_CHARACTER
  --escape-character=ESCAPE_CHARACTER
  --csv
```
如果您不需要保留先前設定的身分與存取權管理角色，請立即撤銷該角色。

REST v1

建立匯出的值區：

gcloud storage buckets create gs://BUCKET_NAME --location=LOCATION_NAME --project=PROJECT_NAME>

使用服務帳戶格式，找出要匯出專案的服務帳戶。

服務帳戶的格式如下：
```
 service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com
```
必須授予這個帳戶 Cloud Storage 值區的權限，才能執行匯出作業。
使用 gcloud storage buckets add-iam-policy-binding 將 storage.objectAdmin 身分與存取權管理角色授予服務帳戶。如需設定 IAM 權限的說明，請參閱「使用 IAM 權限」。

注意： 如果 Cloud Storage 值區中已存在與匯出物件同名的物件，授予服務帳戶 objectAdmin 角色會導致舊物件遭到取代。為避免發生這種情況，您可以將權限較低的 storage.objectCreator 授予服務帳戶，這樣服務帳戶就無法取代現有物件。
匯出資料庫。

請使用下列 HTTP 方法和網址：
```
POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export
```
使用任何要求資料之前，請先替換以下項目：
- PROJECT_ID：專案 ID。
- REGION：部署 AlloyDB 叢集的區域。
- CLUSTER_ID：叢集 ID。
- BUCKET_NAME：Cloud Storage 值區名稱。
- PATH_TO_CSV_FILE：CSV 檔案的路徑。
- DATABASE_NAME：AlloyDB 叢集內的資料庫名稱。
- SELECT_QUERY：用於匯出的 SQL 查詢。
  
  注意： 在傳輸期間，查詢可能會在目標執行個體位置以外的中間位置處理。
- ESCAPE_CHARACTER (選用)：必須出現在需要逸出資料字元之前的字元。這個引數的值必須是十六進位 ASCII 碼中的字元。舉例來說，22 代表雙引號。
- QUOTE_CHARACTER (選用)：用來括住字串資料類型資料欄值的字元。這個引數的值必須是十六進位 ASCII 碼中的字元。例如，22 代表雙引號。
- FIELD_DELIMITER (選用)：用來分隔資料欄值的字元。這個引數的值必須是十六進位 ASCII 碼中的字元。例如，2C 代表逗號。
JSON 要求內文：
```
{
  "gcs_destination": {
    "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE"
  },
  "database": "DATABASE_NAME",
  "csv_export_options": {
    "select_query": "SELECT_QUERY",
    "escape_character": "ESCAPE_CHARACTER",
    "quote_character": "QUOTE_CHARACTER",
    "field_delimiter": "FIELD_DELIMITER"
  }
}
```
如要傳送要求，請選擇以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

       curl -X POST \
             -H "Authorization: Bearer $(gcloud auth print-access-token)" \
             -H "Content-Type: application/json; charset=utf-8" \
             -d @request.json \
             "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"

PowerShell (Windows)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
      -Method POST `
      -Headers $headers `
      -ContentType: "application/json; charset=utf-8" `
      -InFile request.json `
      -Uri "https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/clusters/CLUSTER_ID:export"| Select-Object -Expand Content

您會收到類似以下的 JSON 回應：

回應

    {
     "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
     "metadata": {
      "@type": "type.googleapis.com/google.cloud.alloydb.v1.OperationMetadata",
      "createTime": "2024-09-17T06:05:31.244428646Z",
      "target": "projects/PROJECT_ID/locations/REGION/clusters/TARGET_CLUSTER",
      "verb": "export",
      "requestedCancellation": false,
      "apiVersion": "v1"
     },
     "done": false
    }

如果您不需要保留先前設定的 IAM 權限，請立即予以移除。

如需要求的完整參數清單，請參閱 clusters:export。

自訂 CSV 匯出檔案的格式

您可以使用 gcloud CLI 或 REST API 自訂 CSV 檔案格式。匯出時，您可以指定下列格式選項：

CSV 選項	預設值	gcloud 旗標	REST API 屬性	說明
Escape	預設值與 `QUOTE` 值相同。	`--escape-character`	`escape_character`	需要逸出的資料字元前顯示的字元。
報價	`"22"` 雙引號的 ASCII 十六進位碼。	`--quote-character`	`quote_character`	指定資料值加上引號時要使用的引號字元。
欄位分隔符號	`"2C"` 逗號的 ASCII 十六進位碼。	`--field-delimiter`	`field_delimiter`	用於拆分資料欄值的字元。

舉例來說，使用所有這些引數的 gcloud CLI 指令可能類似於下列指令：

gcloud alloydb clusters export CLUSTER_NAME \
--region=REGION \
--database=DATABASE_NAME \
--gcs-uri='gs://BUCKET_NAME/PATH_TO_CSV_FILE' \
--select-query=SELECT_QUERY \
--field-delimiter='2C' \
--quote-character='22' \
--escape-character='5C'
--csv

對等的 REST API 要求主體如下所示：

{
 "exportContext":
   {
      "gcs_destination": {
        "uri": "gs://BUCKET_NAME/PATH_TO_CSV_FILE",
      },
      "database": "DATABASE_NAME",
      "csv_export_options":
       {
           "select_query": "SELECT_QUERY",
           "escape_character": "5C",
           "quote_character": "22",
           "field_delimiter": "2C",
       }
   }
}

根據預設，CSV 匯出作業會建立標準 CSV 輸出內容。如果需要 AlloyDB 提供的選項以外的選項，可以在 psql 用戶端中使用下列陳述式：

     \copy `TABLE_NAME` TO `CSV_FILE_NAME.csv' WITH
          (FORMAT csv, ESCAPE 'ESCAPE_CHARACTER', QUOTE 'QUOTE_CHARACTER',
          DELIMITER 'DELIMITER_CHARACTER', ENCODING 'UTF8', NULL 'NULL_MARKER_STRING');

後續步驟

瞭解如何匯出 SQL 傾印檔案。
取消匯出作業。