Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

匯入及匯出 CSV 格式的資料

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

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

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

事前準備

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

啟用 API 所需的角色

如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

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

配額需求

匯入或匯出工作的配額規定如下：

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

必要的角色

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

Cloud Spanner 檢視者 (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 to Cloud Storage Text」(Spanner 到 Cloud Storage 文字) 範本工作。

您也可以參考本頁面中有關最佳化緩慢工作和影響工作效能的因素的資訊。

將 CSV 檔案中的資料匯入 Spanner

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

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

步驟 1：將非 Spanner 資料庫中的資料匯出為 CSV 檔案

匯入程序會從 Cloud Storage bucket 中的 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 bucket。

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

您也必須建立資訊清單檔案，其中包含要匯入檔案的 JSON 說明，並將其放在儲存 CSV 檔案的同一個 Cloud Storage bucket 中。這個資訊清單檔案包含 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 匯入工作

如要啟動匯入工作，請按照操作說明，使用 gcloud CLI 執行 Cloud Storage Text to Spanner 範本工作。

啟動匯入工作後，您可以在 Google Cloud 控制台中查看工作詳細資料。

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

選擇匯入工作使用的區域

建議您根據 Cloud Storage bucket 的位置選擇其他區域。為避免產生傳出資料移轉費用，請選擇與 Cloud Storage bucket 位置相符的區域。

如果 Cloud Storage bucket 位置是區域，您可以選擇相同區域執行匯入工作，享有免費網路用量 (假設該區域可用)。
如果 Cloud Storage bucket 位置是雙區域，您可以選擇雙區域中的其中一個區域做為匯入工作的位置，即可享有免費網路用量 (假設其中一個區域可用)。

如果匯入工作沒有可用的共置區域，或 Cloud Storage bucket 位於多區域，則須支付傳出資料移轉費用。請參閱 Cloud Storage 資料移轉定價，選擇資料移轉費用最低的區域。

在 Dataflow UI 中查看或排解工作問題

啟動匯入或匯出工作後，您可以在 Google Cloud 控制台的 Dataflow 專區查看工作詳細資料，包括記錄。

查看 Dataflow 工作詳細資料

如要查看過去一週內執行的匯入或匯出工作詳細資料 (包括目前執行的工作)，請按照下列步驟操作：

前往資料庫的「Database overview」(資料庫總覽) 頁面。
按一下左側窗格選單中的「匯入/匯出」。資料庫的「Import/Export」(匯入/匯出) 頁面會顯示近期工作清單。
在資料庫的「Import/Export」(匯入/匯出) 頁面中，按一下「Dataflow job name」(Dataflow 工作名稱) 欄中的工作名稱：

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

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

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

前往工作
在清單中找出您的工作，然後按一下工作名稱。

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

查看工作的 Dataflow 記錄

如要查看 Dataflow 工作的記錄，請前往工作的詳細資料頁面，然後按一下工作名稱右側的「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」(99% 讀取/寫入延遲時間)。如果顯示的值很高 (數秒)，表示執行個體超載，導致讀取/寫入逾時並失敗。

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

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

控制台

如果您使用的是 Dataflow 控制台，則「Max workers」(工作站數量上限) 參數位於「Create job from template」(依據範本建立工作) 頁面的「Optional parameters」(選用參數) 區段中。

前往 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 bucket 所在的相同區域執行 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 worker 數量：必須有最佳 Dataflow worker，才能確保良好效能。Dataflow 會使用自動調度資源功能，根據需要完成的工作量，選擇工作站數量。不過，worker 數量會受限於 CPU、使用中 IP 位址和標準永久磁碟的配額。如果達到配額上限，Dataflow UI 會顯示警告圖示。在這種情況下，進度會變慢，但工作仍應完成。如果需要匯入大量資料，自動調度資源可能會導致 Spanner 超載，進而發生錯誤。
Spanner 現有負載：匯入工作會大幅增加 Spanner 執行個體的 CPU 負載。匯出工作通常會對 Spanner 執行個體增加輕微負載。如果執行個體已有大量現有負載，工作執行速度就會變慢。
Spanner 運算資源量：如果執行個體的 CPU 使用率超過 65%，工作執行速度就會變慢。

調整 worker 以提升匯入效能

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

工作站數量上限主要取決於資料大小，但理想情況下，Spanner CPU 總使用率應介於 70% 到 90% 之間。這能兼顧 Spanner 效率和工作順利完成。

如要在多數結構定義和情境中達到該使用率目標，建議將 worker vCPU 數量上限設為 Spanner 節點數量的 4 到 6 倍。

舉例來說，如果是 10 個節點的 Spanner 執行個體，使用 n1-standard-2 worker 時，應將 worker 數量上限設為 25，提供 50 個 vCPU。