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

從非 Spanner 資料庫匯入資料

本頁面說明如何準備從非 Spanner 資料庫匯出的 Avro 檔案，然後將這些檔案匯入 Spanner。這些程序包含 GoogleSQL 方言資料庫和 PostgreSQL 方言資料庫的相關資訊。如要匯入先前匯出的 Spanner 資料庫，請參閱「匯入 Spanner Avro 檔案」。

這個程序會使用 Dataflow，從包含一組 Avro 檔案和 JSON 資訊清單檔案的 Cloud Storage 值區匯入資料，該檔案會指定填入每個資料表的目的地資料表和 Avro 檔案。

事前準備

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

Enable the APIs

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

配額需求

匯入工作的配額需求如下：

Spanner：您必須具備足夠的運算能力，才能支援匯入的資料量。匯入資料庫本身不需額外運算資源，不過您可能需要新增更多運算資源，以便在合理的時間內完成工作。詳情請參閱「工作最佳化」一節。
Cloud Storage：如要匯入，您必須要有一個包含先前匯出檔案的值區。您不需要為值區設定大小。
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 資料庫匯出至 Avro 檔案

匯入程序可從位於 Cloud Storage 值區的 Avro 檔案匯入資料。您可以從任何來源以 Avro 格式匯出資料，並使用任何可用的方法來執行此操作。

如要將資料從非 Spanner 資料庫匯出至 Avro 檔案，請按照下列步驟操作：

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

您可以使用任何 Avro 原始類型以及陣列複合類型進行匯出。
Avro 檔案中的每個資料欄都必須使用下列其中一種資料欄類型：
- ARRAY
- BOOL
- BYTES^*
- DOUBLE
- FLOAT
- INT
- LONG^†
- STRING^‡
^* 使用 BYTES 類型的資料欄匯入 Spanner NUMERIC；詳情請參閱下文的「建議對應」一節。

^†,‡您可以匯入儲存時間戳記的 LONG 或 STRING 做為 Spanner TIMESTAMP；詳情請參閱下文的建議對應一節。
匯出 Avro 檔案時無須納入或產生任何中繼資料。
無須遵循任何檔案的特殊命名慣例。

如未將檔案直接匯出至 Cloud Storage，您必須將 Avro 檔案上傳到 Cloud Storage 值區。如需詳細的操作說明，請參閱如何上傳物件至 Cloud Storage。

將 Avro 檔案從非 Spanner 資料庫匯入 Spanner

如要將 Avro 檔案從非 Spanner 資料庫匯入 Spanner，請按照下列步驟操作：

建立目標資料表，並為 Spanner 資料庫定義結構定義。
在 Cloud Storage 值區中建立 spanner-export.json 檔案。
使用 gcloud CLI 執行 Dataflow 匯入工作。

步驟 1：建立 Spanner 資料庫的結構定義

執行匯入作業前，您必須在 Spanner 中建立目標資料表並定義其結構定義。

針對 Avro 檔案中每個資料欄，您必須使用適當資料欄類型的結構定義。

建議對應

GoogleSQL

Avro 資料欄類型	Spanner 資料欄類型
`ARRAY`	`ARRAY`
`BOOL`	`BOOL`
`BYTES`	`BYTES` `NUMERIC` (當資料欄類型為 `BYTES` 和 `logicalType=decimal`、`precision=38` 和 `scale=9` 時)。如果省略這些確切規格，系統會將該欄位視為 Spanner `BYTES` 值。如需更多資訊，請參閱 Avro 十進位邏輯類型文件。
`DOUBLE`	`FLOAT64`
`FLOAT`	`FLOAT64`
`INT`	`INT64`
`LONG`	`INT64` `TIMESTAMP` (當 `LONG` 表示自 1970-01-01 00:00:00 UTC 起的微秒數時間戳記)
`STRING`	`STRING` `TIMESTAMP` (當 `STRING` 表示 SQL 查詢的標準格式中的時間戳記)

PostgreSQL

Avro 資料欄類型	Spanner 資料欄類型
`ARRAY`	`ARRAY`
`BOOL`	`BOOLEAN`
`BYTES`	`BYTEA` `NUMERIC` (當資料欄類型為 `BYTEA` 和 `logicalType=decimal`、`precision=147455` 和 `scale=16383` 時)。如果省略這些確切規格，系統會將欄位視為 `BYTEA` 值。如需更多資訊，請參閱 Avro 十進位邏輯類型文件。
`DOUBLE`	`DOUBLE PRECISION`
`FLOAT`	`DOUBLE PRECISION`
`INT`	`BIGINT`
`LONG`	`BIGINT` `TIMESTAMP` (當 `LONG` 表示自 1970-01-01 00:00:00 UTC 起的微秒數時間戳記)
`STRING`	`CHARACTER VARYING` `TIMESTAMP` (當 `STRING` 表示 SQL 查詢的標準格式中的時間戳記，例如「2022-05-28T07:08:21.123456789Z」或「2021-12-19T16:39:57-08:00」)。

步驟 2：建立 spanner-export.json 檔案

您也必須在 Cloud Storage 值區建立名稱為 spanner-export.json 的檔案。這個檔案會指定資料庫方言，並包含 tables 陣列，列出每個資料表的名稱和資料檔案位置。

檔案內容有以下格式：

{
  "tables": [
   {
    "name": "TABLE1",
    "dataFiles": [
      "RELATIVE/PATH/TO/TABLE1_FILE1",
      "RELATIVE/PATH/TO/TABLE1_FILE2"
    ]
   },
   {
    "name": "TABLE2",
    "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"]
   }
  ],
  "dialect":"DATABASE_DIALECT"
}

DATABASE_DIALECT = {GOOGLE_STANDARD_SQL | POSTGRESQL}

如果省略方言元素，系統會預設為 GOOGLE_STANDARD_SQL。

。

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

如要開始匯入工作，請依照 Google Cloud CLI 的操作說明，使用從 Avro 到 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% Write latency」。如果顯示的值偏高 (多秒)，則表示執行個體超載，導致寫入作業逾時並失敗。

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

如要指定 Dataflow 工作站數量限制，請使用 Dataflow Cloud Storage Avro 到 Spanner 範本開始匯入作業，而非使用 Google Cloud 主控台中 Spanner 資料庫執行個體詳細資料頁面的「匯入/匯出」分頁，並按照以下說明指定工作站的最大數量：

主控台

如果您使用的是 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_Avro_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 運算容量的用量：如果執行個體的 CPU 使用率超過 65%，則會拖慢工作的執行速度。

調整 worker 以提升匯入效能

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

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

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

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