匯出 CSV 檔案

如要擷取資料表或查詢資料，以便在外部工具和環境中使用，您可以將 AlloyDB for PostgreSQL 叢集的資料，以 CSV 格式匯出至 Cloud Storage bucket。

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

您可以取消從 AlloyDB for PostgreSQL 叢集匯出資料。詳情請參閱「取消匯出作業」。

事前準備

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

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

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

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

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

如需 IAM 角色相關協助，請參閱「Identity and Access Management」。

將資料匯出為 CSV 檔案

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

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

gcloud

  1. 建立 Cloud Storage bucket。

  2. 使用 gcloud storage buckets add-iam-policy-binding，將 bucket 的 storage.objectAdmin IAM 角色授予 AlloyDB 服務帳戶。服務帳戶的格式如下：

    service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com

    如需設定 IAM 權限的相關說明，請參閱「使用 IAM 權限」。

  3. 將資料庫匯出至 Cloud Storage bucket。

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

    以下清單說明以 CSV 格式匯出資料的選項：

    • --select-query (必要)：用於擷取資料的選取查詢。
    • --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

  4. 如果不需要保留先前設定的 IAM 角色，請撤銷該角色。

REST v1

  1. 建立匯出作業的 bucket：

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

  2. 使用 gcloud storage buckets add-iam-policy-binding，將 bucket 的 storage.objectAdmin IAM 角色授予 AlloyDB 服務帳戶。服務帳戶的格式如下：

    service-PROJECT_NUMBER@gcp-sa-alloydb.iam.gserviceaccount.com

    如需設定 IAM 權限的相關說明，請參閱「使用 IAM 權限」。

  3. 匯出資料庫。

    請使用下列 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 bucket 名稱。
    • 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 資源 說明
Esc 鍵 預設值與 QUOTE 值相同。 --escape-character escape_character 出現在需要逸出的資料字元之前的字元。
引述 "22"
雙引號的 ASCII 十六進位代碼。		 --quote-character quote_character 指定引用資料值時要使用的引用字元。
欄位分隔符號 "2C"
逗號的 ASCII 十六進位碼。		 --field-delimiter field_delimiter 用於分割資料欄值的字元。

請使用下列 gcloud CLI 和 REST API 範例，自訂 CSV 匯出檔案格式：

gcloud

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 v1

對等的 REST API 要求主體大致如下：

{
  "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');

後續步驟