本頁面由 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：

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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 檢視者 (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 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 值區。

步驟 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 to Spanner 範本執行工作。

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

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

選擇匯入工作使用的區域

根據 Cloud Storage 值區的位置，選擇不同的地區。如要避免產生輸出資料移轉費用，請選擇與 Cloud Storage 值區位置相符的地區。

如果 Cloud Storage 值區位置是地區，只要為匯入工作選擇相同地區 (假設該地區可用)，即可享有免費網路用量。
如果您的 Cloud Storage bucket 位於雙區域，只要其中一個區域可用，您就可以為匯入工作選擇構成雙區域的其中一個區域，以利用免費網路用量。

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

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

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

查看 Dataflow 工作詳細資料

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

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

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

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

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

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

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

查看工作的 Dataflow 記錄檔

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

如有工作失敗，請在記錄檔中尋找錯誤。如果有錯誤，[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 console 中，查看 Spanner 資料庫「Monitoring」(監控)分頁的「99% Read/Write latency」(99% 讀取/寫入延遲)。如果顯示的值偏高 (超過數秒)，表示執行個體負載過重，導致讀取/寫入作業逾時並失敗。

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

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

主控台

如果您使用 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 會假設您打算使用名為「default」的自動模式虛擬私有雲網路，這個網路位於 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%，則會拖慢工作的執行速度。

調整工作人員，提升匯入效能

啟動 Spanner 匯入作業時，必須將 Dataflow 工作站設為最佳值，才能發揮出色效能。工作站數量過多會導致 Spanner 負載過重，而工作站數量過少則會導致匯入效能不佳。

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

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

舉例來說，如果使用 n1-standard-2 工作站，且 Spanner 執行個體有 10 個節點，則可將工作站數量上限設為 25，提供 50 個 vCPU。