測試備份與還原

本頁面說明如何使用自動備份鍵/值備份功能手動觸發備份和還原作業,確保應用程式能正確儲存及還原資料。

備份功能的運作方式

本節說明 Android 備份架構中的各個環節,以及各個環節如何與支援自動備份和鍵/值備份的應用程式互動。在應用程式開發階段,這個架構的內部運作流程大部分經過簡化,因此您不必知道這些資訊。不過在測試階段,瞭解這些概念還是相當重要。

下圖說明備份和還原期間的資料流動方式:

備份架構資料流程

Backup Manager Service (備份管理員服務) 是一項 Android 系統服務,可自動化調度管理及啟動備份與還原作業。您可以透過 Backup Manager API 存取這項服務。在備份作業期間,該服務會查詢您的應用程式是否有備份資料,並將資料交給「backup transport」(備份傳輸) 元件進行資料封存作業。在還原作業期間,備份管理員服務會從備份傳輸中擷取備份資料,並將資料還原至裝置。

「Backup Transports」(備份傳輸) 是負責儲存及擷取備份的 Android 元件。單一 Android 裝置可以有多個備份傳輸或沒有任何備份傳輸,但只有一個傳輸能夠標示為有效。可用的備份傳輸可能會因裝置而異 (基於裝置製造商和服務供應商的自訂項目),但大多數支援 Google Play 的裝置都會隨附下列傳輸機制:

  • Google 傳輸 (預設):大多數裝置使用的備份傳輸,屬於 Google 行動服務的一部分。本說明文件假設使用者使用的是 Google 傳輸。此傳輸會在 Android Backup Service 當中儲存資料。
  • 本機傳輸:將備份資料儲存在裝置本機。這種傳輸元件通常是用於進行開發/偵錯,不適合實際應用。

如果裝置沒有任何備份傳輸,就無法備份資料。您的應用程式不會受到負面影響。

必要條件

如要測試備份與還原作業,您必須先對下列工具有初步瞭解。

  • ADB - 在裝置上或模擬器中執行指令
  • bmgr - 執行各種備份與還原作業
  • logcat:查看備份和還原作業的輸出內容

準備裝置或模擬器

如要準備裝置或模擬器以進行備份測試,請檢查下列事項:

  • 針對自動備份,請確認您使用的裝置或模擬器搭載 Android 6.0 (API 級別 23) 以上版本。
  • 針對鍵/值備份,請確認您使用的裝置或模擬器搭載 Android 2.2 (API 級別 8) 以上版本。
  • 確認裝置或模擬器已啟用備份和還原功能,並已新增 Google 帳戶。檢查方法有兩種:

    • 視裝置版本而定,您可以依序前往「Settings」(設定) >「Backup & Restore」(備份與還原) ,或直接在畫面頂端的搜尋列中搜尋「Backup」(備份)
    • 透過 ADB 殼層執行 bmgr enabled

    在實體裝置上,備份和還原功能通常是在初始設定精靈中啟用。模擬器不會執行設定精靈,因此別忘了啟用備份功能,並在裝置設定中指定備份帳戶。

  • 執行以下指令,確認 Google 備份傳輸能夠使用且正在運作中:

    adb shell bmgr list transports
    

    接著檢查主控台是否有以下輸出內容:

    android/com.android.internal.backup.LocalTransport
    * com.google.android.gms/.backup.BackupTransportService
    

沒有 Google Play 的實體裝置和沒有 Google API 的模擬器可能不含 Google 備份傳輸。本文假設您使用的是 Google 備份傳輸。您可以使用其他備份傳輸測試備份和還原作業,但相關程序和輸出內容可能會有所不同。

測試備份作業

如要啟動應用程式備份作業,請執行下列指令:

adb shell bmgr backupnow <PACKAGE>

backupnow 指令適用於搭載 Android 7.0 以上版本的裝置和模擬器。系統會根據套件資訊清單的宣告內容執行鍵/值備份或自動備份。請檢查 logcat 來查看備份程序的輸出內容。例如:

D/BackupManagerService: fullTransportBackup()
I/GmsBackupTransport: Attempt to do full backup on <PACKAGE>

---- or ----

V/BackupManagerService: Scheduling immediate backup pass
D/PerformBackupTask: starting key/value Backup of BackupRequest{pkg=<PACKAGE>}

如果裝置不支援 backupnow 指令,請根據您要測試的是自動備份或鍵/值備份,完成下方的對應步驟。

針對自動備份,請完成下列步驟:

  1. 執行下列指令:

    adb shell bmgr backup @pm@ && adb shell bmgr run
    
  2. 等待前一步驟中的指令執行完畢,方法是監控 adb logcat,檢查是否有以下輸出內容:

    I/BackupManagerService: K/V backup pass finished.
    
  3. 執行以下指令執行完整備份作業:

    adb shell bmgr fullbackup <PACKAGE>
    

針對鍵/值備份,請按照下列步驟安排並實際執行備份作業:

  1. 如果應用程式自上次備份後並未呼叫 BackupManager.dataChanged(),您可以執行以下指令,將應用程式加入備份作業中,以便進行測試:

    adb shell bmgr backup <PACKAGE>
    
  2. 接著,您可以執行以下指令來觸發備份作業:

    adb shell bmgr run
    

bmgr backup 會將應用程式新增至備份管理員的佇列中。 bmgr run 會啟動備份作業,強制讓備份管理員執行佇列中的所有備份要求。

測試鍵/值備份時,您必須確認每次偏好設定變更時,系統都會安排一次備份作業。如要確認是否已排定執行備份作業,您可以使用下列其中一種方法:

  • 執行 adb shell dumpsys backup,並檢查應用程式是否列在 Pending key/value backup 的指令輸出內容中。

  • 安排執行備份作業時,記錄一則訊息。接著執行 adb logcat 並檢查指令輸出內容,確認是否已安排執行備份作業。

測試還原作業

如要手動啟動還原作業,請使用備份符記 (取得方式請見下方說明) 執行以下指令:

adb shell bmgr restore <TOKEN> <PACKAGE>

如要查詢備份權杖,請執行 adb shell dumpsys backup。這個權杖是 Ancestral:Current: 標籤後面的十六進位字串。「ancestral」權杖是指透過裝置設定精靈進行裝置初始設定時,用來還原裝置的備份資料集。「current」權杖是指裝置目前的備份資料集 (裝置目前正在將備份資料傳送至這個資料集)。

接著檢查 logcat,查看還原程序的輸出內容。例如:

V/BackupManagerService: beginRestoreSession: pkg=<PACKAGE> transport=null
V/RestoreSession: restorePackage pkg=<PACKAGE> token=368abb4465c5c683
...
I/BackupManagerService: Restore complete.

如要測試應用程式的自動還原功能,您可以透過 adb 或 Google Play 商店應用程式解除安裝應用程式再重新安裝。

疑難排解

本節旨在協助您排解某些常見問題。

超過傳輸配額

如果 logcat 中顯示以下訊息:

I/PFTBT: Transport rejected backup of <PACKAGE>, skipping

--- or ---

I/PFTBT: Transport quota exceeded for package: <PACKAGE>

這表示應用程式已超過配額上限。請減少備份資料量,然後再試一次。舉例來說,請確認您只將資料快取至應用程式的快取目錄。快取目錄不在備份範圍內。

無法進行完整備份作業

如果 logcat 中顯示以下訊息:

I/BackupManagerService: Full backup not currently possible -- key/value backup not yet run?

這表示裝置上尚未發生鍵/值備份作業,導致完整備份作業失敗。請使用 bmgr run 指令觸發鍵/值備份作業,然後再試一次。

等待代理程式逾時

如果 logcat 中顯示以下訊息:

12-05 18:59:02.033  1910  2251 D BackupManagerService:
    awaiting agent for ApplicationInfo{5c7cde0 com.your.app.package}
12-05 18:59:12.117  1910  2251 W BackupManagerService:
    Timeout waiting for agent ApplicationInfo{5c7cde0 com.your.app.package}
12-05 18:59:12.117  1910  2251 W BackupManagerService:
    Can't find backup agent for com.your.app.package

這表示應用程式啟動備份作業的所需時間超過 10 秒。您可以看到記錄輸出內容中的時間戳記差異。之所以發生這個錯誤,通常是因為應用程式在沒有 ProGuard 的情況下使用 multidex 設定。

未初始化的備份帳戶

如果 logcat 中顯示以下訊息:

01-31 14:32:45.698 17280 17292 I Backup: [GmsBackupTransport] Try to backup for an uninitialized backup account.
01-31 14:32:45.699  1043 18255 W PFTBT: Transport failed; aborting backup: -1001
01-31 14:32:45.699  1043 18255 I PFTBT: Full backup completed with status: -1000

這表示備份資料集尚未初始化,因此備份作業已取消。 請使用 adb shell bmgr run 指令執行備份管理員,然後再次嘗試執行備份作業。

未呼叫應用程式方法

自動備份會以 Application 的基礎類別啟動應用程式,因此可能不會呼叫應用程式的設定方法。自動備份也不會啟動應用程式的任何活動,因此如果您的應用程式在活動中進行設定,系統可能會顯示錯誤訊息。詳情請參閱「實作 BackupAgent」一節。

相對地,鍵/值備份會透過應用程式資訊清單檔案中宣告的任何 Application 子類別來啟動應用程式。