本頁面說明如何使用Google Cloud 控制台匯出 Spanner 資料庫。
如要使用 REST API 或 Google Cloud CLI 匯出 Spanner 資料庫，請完成本頁「事前準備」一節中的步驟，然後參閱 Dataflow 說明文件中的「Spanner 到 Cloud Storage Avro」詳細操作說明。匯出程序會使用 Dataflow，並將資料寫入 Cloud Storage bucket 中的資料夾。產生的資料夾包含一組 Avro 檔案和 JSON 資訊清單檔案。
事前準備
如要匯出 Spanner 資料庫，請先啟用 Spanner、Cloud Storage、Compute Engine 和 Dataflow API：
啟用 API 所需的角色
您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
此外，您也需要足夠的配額和必要的 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 Data Boost 的獨立運算資源，您也需要 spanner.databases.useDataBoost Identity and Access Management (IAM) 權限。詳情請參閱「Data Boost 總覽」。
匯出資料庫
滿足上述配額和 IAM 規定後，即可匯出現有的 Spanner 資料庫。
如要將 Spanner 資料庫匯出至 Cloud Storage bucket，請按照下列步驟操作：
前往 Spanner 的「Instances」(執行個體) 頁面。
按一下包含資料庫的執行個體名稱。
按一下左側窗格中的「Import/Export」(匯入/匯出) 選單項目，然後點選「Export」(匯出) 按鈕。
在「選擇匯出項目的儲存位置」下方，點選「瀏覽」。
如果尚未建立用於匯出的 Cloud Storage bucket，請按照下列步驟操作：
- 按一下「新增值區」圖示
。 - 輸入 bucket 的名稱。Cloud Storage 中的 bucket 名稱不得重複。
- 選取預設的儲存空間級別和位置，然後按一下 [Create] (建立)。
- 按一下值區即可加以選取。
如果您已有 bucket，請從初始清單中選取 bucket，或按一下「Search」(搜尋)
來篩選清單，然後點選要選取的 bucket。- 按一下「新增值區」圖示
按一下「選取」。
在「Choose a database to export」(選擇要匯出的資料庫) 下拉式選單中選取您要匯出的資料庫。
選用：如要匯出過去時間點的資料庫，請勾選方塊並輸入時間戳記。
在「Choose a region for the export job」(選取匯出工作使用的區域) 下拉式選單中選取區域。
選用：如要使用客戶自行管理的加密金鑰加密 Dataflow 管道狀態，請按照下列步驟操作：
- 按一下「顯示加密選項」。
- 選取「使用客戶自行管理的加密金鑰 (CMEK)」。
- 從下拉式選單中選取金鑰。
這個選項不會影響目的地 Cloud Storage bucket 層級的加密。如要為 Cloud Storage bucket 啟用 CMEK，請參閱「搭配使用 CMEK 與 Cloud Storage」。
選用：如要使用 Data Boost 匯出，請勾選「Use Spanner Data Boost」(使用 Spanner Data Boost) 核取方塊。詳情請參閱「Data Boost 總覽」。
勾選「Confirm charges」(確認費用) 下方的核取方塊，確認除了現有 Spanner 執行個體產生的費用外，還會產生其他費用。
按一下 [匯出]。
Google Cloud 控制台會顯示「Database Import/Export」(資料庫匯入/匯出) 頁面，其中「Import/Export jobs」(匯入/匯出工作) 清單會顯示匯出工作的明細項目，包括工作經過時間：
工作完成或終止時，匯入/匯出清單中的狀態會更新。如果工作成功，系統會顯示「Succeeded」(成功) 狀態：
如果工作失敗，狀態會顯示為「失敗」：
如要查看工作的 Dataflow 作業詳細資料，請按一下「Dataflow job name」(Dataflow 工作名稱) 欄中的工作名稱。
如果工作失敗，請查看工作的 Dataflow 記錄，瞭解錯誤詳情。
為了避免 Cloud Storage 對失敗的匯出工作所建立的檔案收費，請刪除資料夾和其中的檔案。如要瞭解如何找到資料夾，請參閱「查看匯出資料」。
匯出生成資料欄和變更串流的注意事項
儲存的生成資料欄中的值不會匯出。資料欄定義會匯出至 Avro 結構定義，做為空值類型的記錄欄位，並以資料欄定義做為欄位的自訂屬性。在新產生的資料欄完成補充作業前，系統會忽略該資料欄，就像結構定義中不存在該資料欄一樣。
匯出為 Avro 檔案的變更串流只會包含變更串流的結構定義，不含任何資料變更記錄。
匯出序列的注意事項
GoogleSQL 和 PostgreSQL 的序列是結構定義物件，可用來產生不重複的整數值。Spanner 會將每個結構定義物件匯出至 Avro 結構定義，做為記錄欄位，並將其序列種類、略過範圍和計數器做為欄位的屬性。請注意，為避免匯入後序列重設並產生重複值，在結構定義匯出期間，GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL、PostgreSQL) 函式會擷取序列計數器。Spanner 會在計數器中加入 1000 的緩衝區，並將新的計數器值寫入記錄欄位。這種做法可避免匯入後可能發生的重複值錯誤。如果在資料匯出期間，來源資料庫有更多寫入作業，請使用 ALTER SEQUENCE (GoogleSQL、PostgreSQL) 陳述式調整實際序列計數器。
匯入時，序列會從這個新計數器開始，而不是從結構定義中的計數器開始。或者，您也可以使用 ALTER SEQUENCE (GoogleSQL、PostgreSQL) 陳述式，以新的計數器更新序列。
在 Cloud Storage 查看匯出內容
如要在Google Cloud 控制台中查看包含匯出資料庫的資料夾，請前往 Cloud Storage 瀏覽器，並選擇先前選取的 bucket：
前往「Storage browser」(Storage 瀏覽器)
您匯出的資料庫位於該值區現有的資料夾中。該資料夾的名稱是以執行個體 ID 開頭，後面接上資料庫名稱和匯出工作的時間戳記。其中包含：
spanner-export.json檔案- 匯出的資料庫中，每個資料表都有一個
TableName-manifest.json檔案。 一或多個
TableName.avro-#####-of-#####檔案。副檔名.avro-#####-of-#####中的第一個數字代表 Avro 檔案的索引 (從零開始)，第二個數字則代表為每個資料表產生的 Avro 檔案數量。舉例來說，
Songs.avro-00001-of-00002是包含Songs資料表資料的兩個檔案中的第二個檔案。匯出的資料庫中，每個變更串流都有一個
ChangeStreamName-manifest.json檔案。每個變更串流都有一個
ChangeStreamName.avro-00000-of-00001檔案。這個檔案包含空白資料，只有變更串流的 Avro 結構定義。
選擇匯入工作使用的區域
您可以根據 Cloud Storage bucket 的位置，選擇其他區域。為避免產生傳出資料移轉費用，請選擇與 Cloud Storage bucket 位置相符的區域。
如果 Cloud Storage bucket 位置是區域，您可以選擇相同區域執行匯入工作，享有免費網路用量 (前提是該區域可用)。
如果 Cloud Storage bucket 位置是雙區域，您可以選擇雙區域中的其中一個區域做為匯入工作的位置，即可享有免費網路用量 (前提是該區域可用)。
匯出一部分資料表
如果只想匯出特定資料表的資料，而非整個資料庫，可以在匯出時指定這些資料表。在這種情況下，Spanner 會匯出資料庫的完整結構定義，包括您指定的資料表資料，並在匯出檔案中保留所有其他資料表，但內容為空白。
您可以使用 Google Cloud 控制台中的 Dataflow 頁面或 gcloud CLI，指定要匯出的資料表子集。(Spanner 頁面不提供這項操作)。
如果匯出某個資料表的資料，而該資料表是另一個資料表的子項，則應一併匯出父項資料表的資料。如果未匯出父項，匯出工作就會失敗。
如要匯出部分資料表，請使用 Dataflow 的 Spanner to Cloud Storage Avro 範本啟動匯出作業，並透過 Google Cloud 控制台的 Dataflow 頁面或 gcloud CLI 指定資料表，如下所示：
控制台
如果您使用 Google Cloud 控制台的 Dataflow 頁面，可以在「Create job from template」(依據範本建立工作) 頁面的「Optional parameters」(選用參數) 區段找到「Cloud Spanner Table name(s)」(Cloud Spanner 資料表名稱) 參數。您可以指定多個資料表，並以半形逗號分隔。
gcloud
執行 gcloud dataflow jobs run 指令，並指定 tableNames 引數。例如：
gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=table1,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123
如要在 gcloud 中指定多個資料表，必須逸出字典類型的引數。以下範例使用「|」做為逸出字元：
gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123
shouldExportRelatedTables 參數是便利的選項，可自動匯出所選資料表的所有父項資料表。舉例來說，在這個包含 Singers、Albums 和 Songs 資料表的結構定義階層中，您只需要指定 Songs。shouldExportRelatedTables 選項也會匯出 Singers 和 Albums，因為 Songs 是兩者的子系。
gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123
在 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] (記錄) 旁邊會顯示錯誤計數：
如何查看工作錯誤：
按一下「記錄」旁的錯誤計數。
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 latency」(99% 讀取延遲時間)。如果顯示的值很高 (數秒)，表示執行個體超載，導致讀取作業逾時並失敗。
延遲時間過長的原因之一，是 Dataflow 工作使用過多 worker 執行，導致 Spanner 執行個體負載過高。
如要指定 Dataflow worker 數量上限，請勿使用 Google Cloud 控制台 Spanner 資料庫執行個體詳細資料頁面中的「匯入/匯出」分頁，而是必須使用 Dataflow 的 Spanner to Cloud Storage Avro 範本啟動匯出作業，並按照下列說明指定 worker 數量上限：控制台
如果您使用 Dataflow 控制台，可以在「Create job from template」(依據範本建立工作) 頁面的「Optional parameters」(選用參數) 區段找到「Max workers」(工作站數量上限) 參數。
gcloud
執行 gcloud dataflow jobs run 指令，並指定 max-workers 引數。例如：
gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,outputDir=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 工作的專案。如果專案中沒有預設虛擬私有雲網路，或是虛擬私有雲網路採用自訂模式，您就必須建立 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 使用率超過 65%，工作執行速度就會變慢。