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

從非 Spanner 資料庫匯入資料

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

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

事前準備

如要匯入 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 的大小。
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 資料庫的資料匯出至 Avro 檔案

匯入程序會從 Cloud Storage bucket 中的 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 bucket。如需詳細操作說明，請參閱「將物件上傳至 Cloud Storage」。

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

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

建立目標資料表，並定義 Spanner 資料庫的結構定義。
在 Cloud Storage bucket 中建立 spanner-export.json 檔案。
使用 Google Cloud 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 bucket 中建立名為 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}

如果省略 dialect 元素，方言預設為 GOOGLE_STANDARD_SQL。

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

如要啟動匯入工作，請按照操作說明，使用 gcloud CLI 執行 Avro 至 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% Write latency」(99% 寫入延遲時間)。如果顯示的值偏高 (數秒)，表示執行個體超載，導致寫入作業逾時並失敗。

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

如要指定 Dataflow worker 數量上限，請勿使用 Google Cloud 控制台中 Spanner 資料庫執行個體詳細資料頁面的「匯入/匯出」分頁，而是必須使用 Dataflow Cloud Storage Avro to Spanner 範本啟動匯入作業，並按照下列說明指定 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_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 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 會根據要完成的工作量，使用自動調度資源功能選擇工作站數量。不過，工作站數量會受限於 CPU、使用中 IP 位址和標準永久磁碟的配額。如果達到配額上限，Dataflow UI 會顯示警告圖示。在這種情況下，進度會變慢，但工作仍應完成。如果需要匯入大量資料，自動調度資源可能會導致 Spanner 超載，進而發生錯誤。
Spanner 現有負載：匯入工作會大幅增加 Spanner 執行個體的 CPU 負載。如果執行個體已有大量現有負載，工作執行速度就會變慢。
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。