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

以 CSV 格式匯入及匯出資料

本頁面說明如何將資料從 Spanner 匯出至 CSV 檔案，或將資料從 CSV 檔案匯入 Spanner GoogleSQL 方言資料庫或 PostgreSQL 方言資料庫。

如要匯入先前匯出至 Cloud Storage 的 Avro 檔案的 Spanner 資料庫，請參閱「匯入 Spanner Avro 檔案」。
如要從非 Spanner 資料庫匯入 Avro 檔案，請參閱「從非 Spanner 資料庫匯入資料」。

這個程序會使用 Dataflow。您可以將資料從 Spanner 匯出至 Cloud Storage 值區，也可以從包含 JSON 資訊清單檔案和一組 CSV 檔案的 Cloud Storage 值區，將資料匯入 Spanner。

事前準備

如要匯入或匯出 Spanner 資料庫，您必須先啟用 Spanner、Cloud Storage、Compute Engine 和 Dataflow API：

Enable the APIs

此外，您也需要足夠的配額和必要的 IAM 權限。

配額需求

匯入或匯出工作配額需求如下：

Spanner：您必須具備足夠的運算能力，才能支援匯入的資料量。匯入或匯出資料庫本身不需額外運算資源，不過您可能需要新增更多運算資源，以便在合理的時間內完成工作。詳情請參閱「工作最佳化」一節。
Cloud Storage：如要匯入，您必須要有一個包含先前匯出檔案的值區。如要匯出，您必須為匯出檔案建立值區 (如果尚未建立)。如要執行這項操作，您可以前往 Google Cloud 控制台的 Cloud Storage 頁面，或者透過 Spanner 頁面建立匯出工作。您不需要為值區設定大小。
Dataflow：匯入或匯出工作在 CPU、磁碟使用率和 IP 位址方面的 Compute Engine 配額限制與其他 Dataflow 工作相同。
Compute Engine：執行匯入或匯出工作前，您必須先為 Dataflow 使用的 Compute Engine 設定初始配額。這些配額代表您允許 Dataflow 為工作使用的「上限」資源數量。我們建議的起始值如下：
- CPU：200
- 使用中的 IP 位址：200
- 標準永久磁碟：50 TB
一般來說，您不必再進行其他調整。Dataflow 會自動調度資源，因此您只要針對匯入或匯出過程中實際用到的資源支付費用。如果您的工作可能會使用更多資源，Dataflow UI 將出現警告圖示，在此情況下工作仍可順利完成。

必要的角色

如要取得匯出資料庫所需的權限，請要求管理員在 Dataflow 工作站服務帳戶上授予下列 IAM 角色：

Cloud Spanner Viewer (roles/spanner.viewer)
Dataflow 工作者 (roles/dataflow.worker)
儲存空間管理員 (roles/storage.admin)
Spanner 資料庫讀取者 (roles/spanner.databaseReader)
資料庫管理員 (roles/spanner.databaseAdmin)

將 Spanner 資料匯出為 CSV 檔案

如要將資料從 Spanner 匯出至 Cloud Storage 中的 CSV 檔案，請按照使用 Google Cloud CLI 執行 Spanner 到 Cloud Storage 文字範本的工作說明操作。

您也可以參考本頁中的資訊，瞭解如何改善執行速度緩慢的工作，以及影響工作成效的因素。

將 CSV 檔案中的資料匯入 Spanner

從 CSV 檔案匯入資料的程序包括下列步驟：

將資料匯出為 CSV 檔案，並儲存在 Cloud Storage 中。請勿加入標頭行。
建立 JSON 資訊清單檔案，並與 CSV 檔案一併儲存。
在 Spanner 資料庫中建立空白目標資料表或確保 CSV 檔案中資料欄的資料類型與現有資料表中的任何對應資料欄相符。
執行匯入工作。

步驟 1：將資料從非 Spanner 資料庫匯出至 CSV 檔案

匯入程序可從位於 Cloud Storage 值區的 CSV 檔案匯入資料。您可以從任何來源以 CSV 格式匯出資料。

匯出資料時請注意下列幾點：

要匯入的文字檔案必須採用 CSV 格式。
資料必須符合下列其中一種類型：

GoogleSQL

BOOL
INT64
FLOAT64
NUMERIC
STRING
DATE
TIMESTAMP
BYTES
JSON

PostgreSQL

boolean
bigint
double precision
numeric
character varying, text
date
timestamp with time zone
bytea

匯出 CSV 檔案時無須納入或產生任何中繼資料。
無須遵循任何檔案的特殊命名慣例。

如果您未將檔案直接匯出至 Cloud Storage，則必須上傳 CSV 檔案至 Cloud Storage 值區。

步驟 2：建立 JSON 資訊清單檔案

您也必須建立資訊清單檔案，其中包含要匯入檔案的 JSON 說明，並將該檔案放在儲存 CSV 檔案的 Cloud Storage 值區中。這個資訊清單檔案包含 tables 陣列，會列出每個資料表的名稱和資料檔案位置。該檔案也會指定接收資料庫方言。如果省略方言，系統會預設為 GoogleSQL。

資訊清單檔案的格式會對應到下列訊息類型，如通訊協定緩衝區格式中所示：

message ImportManifest {
  // The per-table import manifest.
  message TableManifest {
    // Required. The name of the destination table.
    string table_name = 1;
    // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
    repeated string file_patterns = 2;
    // The schema for a table column.
    message Column {
      // Required for each Column that you specify. The name of the column in the
      // destination table.
      string column_name = 1;
      // Required for each Column that you specify. The type of the column.
      string type_name = 2;
    }
    // Optional. The schema for the table columns.
    repeated Column columns = 3;
  }
  // Required. The TableManifest of the tables to be imported.
  repeated TableManifest tables = 1;

  enum ProtoDialect {
    GOOGLE_STANDARD_SQL = 0;
    POSTGRESQL = 1;
  }
  // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
  ProtoDialect dialect = 2;
}

以下範例顯示匯入資料表 Albums 和 Singers 至 GoogleSQL 方言資料庫的資訊清單檔案。Albums 資料表使用工作擷取自資料庫的資料欄結構定義，而 Singers 資料表使用資訊清單檔案所指定的結構定義：

{
  "tables": [
    {
      "table_name": "Albums",
      "file_patterns": [
        "gs://bucket1/Albums_1.csv",
        "gs://bucket1/Albums_2.csv"
      ]
    },
    {
      "table_name": "Singers",
      "file_patterns": [
        "gs://bucket1/Singers*.csv"
      ],
      "columns": [
        {"column_name": "SingerId", "type_name": "INT64"},
        {"column_name": "FirstName", "type_name": "STRING"},
        {"column_name": "LastName", "type_name": "STRING"}
      ]
    }
  ]
}

步驟 3：建立 Spanner 資料庫的資料表

執行匯入作業前，您必須在 Spanner 資料庫中建立目標資料表。如果目標 Spanner 資料表已有結構定義，在資訊清單檔案中指定的任何資料欄都必須具有與目標資料表結構定義中對應資料欄相同的資料類型。

建議您在將資料匯入 Spanner 後，再建立次要索引、外鍵和變更串流，而不是在初始建立資料表時就建立。如果資料表已包含這些結構，建議您在匯入資料後將其刪除並重新建立。

步驟 4：使用 gcloud 執行 Dataflow 匯入工作

如要開始匯入工作，請依照 Google Cloud CLI 的操作說明，使用 Cloud Storage Text 到 Spanner 範本來執行工作。

開始匯入工作後，您可以在 Google Cloud 主控台查看工作的詳細資料。

完成匯入工作之後，新增必要的次要索引、外鍵和變更串流。

選擇匯入工作使用的區域

您可以根據 Cloud Storage 值區的位置，選擇其他地區。如要避免產生傳出資料移轉費用，請選擇與 Cloud Storage 值區位置相符的區域。

如果您的 Cloud Storage 值區位置採用地區設定，請為匯入工作選擇相同地區，以利用免費網路用量 (假設該地區可用)。
如果您的 Cloud Storage 值區位置採用雙區域設定，您可以選擇匯入工作所屬雙區域的其中一個區域，假設其中一個區域可用，即可利用免費網路用量。
如果匯入工作無法使用同地點區域，或是 Cloud Storage 值區位置是多地區，系統會向您收取資料輸出費用。請參閱 Cloud Storage 資料移轉定價資訊，選擇資料移轉費用最低的地區。

在 Dataflow UI 中查看或排解工作

開始匯入或匯出工作後，您可以在 Google Cloud 主控台的「Dataflow」區段中查看工作詳細資料，包括記錄檔。

查看 Dataflow 工作詳細資料

如要查看過去一週內執行的所有匯入或匯出工作詳細資料，包括目前正在執行的任何工作：

前往資料庫的「資料庫總覽」頁面。
按一下左側窗格中的「Import/Export」選單項目。「Import/Export」頁面會顯示最近的工作清單。
在資料庫「Import/Export」頁面中，按一下「Dataflow job name」欄中的作業名稱：

Google Cloud 控制台會顯示 Dataflow 工作的詳細資料。

如何查看超過一週前執行的工作：

前往 Google Cloud 控制台的 Dataflow 工作頁面。

前往「Jobs」(工作) 頁面
在清單中找出您的工作，然後按一下工作名稱。

Google Cloud 控制台會顯示 Dataflow 工作的詳細資料。

查看工作的 Dataflow 記錄檔

如要查看 Dataflow 工作記錄檔，請前往工作的詳細資料頁面，然後按一下工作名稱右側的「Logs」。

如有工作失敗，請在記錄檔中尋找錯誤。如果有錯誤，[Logs] (記錄) 旁邊會顯示錯誤計數：

「Logs」(記錄) 按鈕旁邊的錯誤計數範例

如何查看工作錯誤：

按一下「Logs」旁的錯誤計數。

Google Cloud 控制台會顯示工作的記錄。您可能需要捲動畫面才能看到錯誤。
找出帶有錯誤圖示的項目。
按一下個別記錄項目，即可展開內容。

如要進一步瞭解如何排解 Dataflow 工作問題，請參閱「排解管道問題」。

排解匯入或匯出工作失敗的問題

如果工作記錄中顯示以下錯誤：

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

在Google Cloud 主控台的 Spanner 資料庫「Monitoring」分頁中，查看「99% Read/Write latency」。如果顯示的值偏高 (多秒)，表示執行個體超載，導致讀取/寫入作業逾時並失敗。

延遲時間過長的原因之一，是 Dataflow 工作執行時使用過多工作站，導致 Spanner 執行個體負載過高。

如要指定 Dataflow 工作站數量上限，請按照下列步驟操作：

主控台

如果您使用的是 Dataflow 主控台，「Create job from template」(利用範本建立工作) 頁面的「Optional parameters」(選用參數) 部分會顯示「Max workers」參數。

前往 Dataflow

gcloud

執行 gcloud dataflow jobs run 指令，並指定 max-workers 引數。例如：

  gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Text_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10 \
    --network=network-123

排解網路錯誤

匯出 Spanner 資料庫時，可能會發生下列錯誤：

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

發生這個錯誤的原因是，Spanner 會假設您打算在與 Dataflow 工作相同的專案中使用名為 default 的自動模式虛擬私有雲網路。如果專案中沒有預設的虛擬私有雲網路，或是虛擬私有雲網路採用的是自訂模式，您就必須建立 Dataflow 工作，並指定替代網路或子網路。

對速度緩慢的匯入或匯出工作進行最佳化

如果您已按照初始設定的建議操作，通常不需要再進行其他調整。如果工作執行速度緩慢，您可嘗試下列其他最佳化處理做法：

為工作和資料選擇最佳位置：在 Spanner 執行個體和 Cloud Storage 值區所在位置的地區執行 Dataflow 工作。
確保有足夠的 Dataflow 資源：如果相關的 Compute Engine 配額限制了 Dataflow 工作的資源，該工作在 Google Cloud 主控台的 Dataflow 頁面會顯示警告圖示和記錄訊息：

在這種情況下，增加 CPU、使用中的 IP 位址和標準永久磁碟的配額，雖然可能縮短工作執行時間，但您可能會產生更多 Compute Engine 費用。
檢查 Spanner CPU 使用率：如果您發現執行個體的 CPU 使用率超過 65%，則可增加該執行個體中的運算資源。容量會增加更多 Spanner 資源，並加快工作執行速度，不過 Spanner 費用也會隨之提高。

影響匯入或匯出工作效能的因素

下列幾個因素會影響匯入或匯出工作完成所需的時間。

Spanner 資料庫大小：處理更多資料的同時也需要較多時間和資源。
Spanner 資料庫結構定義，包括：
- 資料表數量
- 資料列的大小
- 次要索引的數量
- 外鍵數量
- 變更串流數量

資料位置：資料會透過 Dataflow 在 Spanner 和 Cloud Storage 之間轉移，比較理想的情況是這三個元件都位在同個地區。如果這些元件位在不同地區，在各地區間移動資料將拖慢工作的執行速度。
Dataflow 工作站數量：為了獲得良好的效能，您必須使用最佳的 Dataflow 工作站。透過自動調度資源功能，Dataflow 可根據需要處理的工作量選擇工作站數量。不過，工作站數量會以 CPU、使用中的 IP 位址和標準永久磁碟的配額做為上限。當工作站數量達到配額上限時，Dataflow UI 會出現警告圖示，在這種情況下，進度會較為緩慢，但工作仍可順利完成。當有大量資料需要匯入時，自動調度資源功能可能會導致 Spanner 超載，進而導致錯誤。
Spanner 的現有負載：匯入工作會大幅加重 Spanner 執行個體上 CPU 的負載。匯出工作通常只會對 Spanner 例項增添少量負載。如果該執行個體原本已有大量負載，則會拖慢作業的執行速度。
Spanner 運算容量的用量：如果執行個體的 CPU 使用率超過 65%，會拖慢工作的執行速度。

調整 worker 以提升匯入效能

啟動 Spanner 匯入作業時，必須將 Dataflow 工作站設為最佳值，才能發揮良好效能。工作站過多會導致 Spanner 超載，而工作站太少則會導致匯入效能不佳。

工作站數量上限會大幅取決於資料大小，但理想情況下，Spanner 的 CPU 總使用率應介於 70% 至 90% 之間。這可在 Spanner 效率和無錯誤的工作完成作業之間取得良好平衡。

為了在大多數結構定義和情境中達到使用率目標，我們建議工作站 vCPU 數量上限為 Spanner 節點數量的 4 到 6 倍。

舉例來說，如果是 10 個節點的 Spanner 例項，使用 n1-standard-2 工作站，您會將最多工作站設為 25，提供 50 個 vCPU。