本頁面說明如何使用自動備份和鍵/值備份功能手動觸發備份和還原作業,確保應用程式能正確儲存及還原資料。
備份功能的運作方式
本節說明 Android 備份架構中的各個環節,以及各個環節如何與支援自動備份和鍵/值備份的應用程式互動。在應用程式開發階段,這個架構的內部運作流程大部分經過簡化,此時您還不必知道這些資訊。不過在測試階段,瞭解這些概念還是相當重要。
下圖說明備份和還原期間的資料流動方式:
Backup Manager Service (備份管理員服務) 是一項 Android 系統服務,可自動化調度管理及啟動備份與還原作業。您可以透過 Backup Manager
API 存取這項服務。在備份作業期間,該服務會查詢您的應用程式是否有備份資料,並將資料交給「backup transport」(備份傳輸) 元件進行資料封存作業。在還原作業期間,備份管理員服務會從備份傳輸中擷取備份資料,並將資料還原至裝置。
「Backup Transports」(備份傳輸) 是負責儲存及擷取備份的 Android 元件。單一 Android 裝置可以有多個備份傳輸或沒有任何備份傳輸,但只有一個傳輸能夠標示為有效。可用的備份傳輸可能會因裝置而異 (基於裝置製造商和服務供應商的自訂項目),但大多數支援 Google Play 的裝置都會隨附下列傳輸機制:
- Google 傳輸 (預設):大多數裝置使用的備份傳輸,屬於 Google 行動服務的一部分。本說明文件假設使用者使用的是 Google 傳輸。此傳輸會在 Android Backup Service 當中儲存資料。
- 本機傳輸:將備份資料儲存在裝置本機。這種傳輸元件通常是用於進行開發/偵錯,不適合實際應用。
如果裝置沒有任何備份傳輸,就無法備份資料。您的應用程式不會受到負面影響。
必要條件
如要測試備份與還原作業,您必須先對下列工具有初步瞭解。
準備裝置或模擬器
如要準備裝置或模擬器以進行備份測試,請檢查下列事項:
- 針對自動備份,請確認您使用的裝置或模擬器搭載 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
指令,請根據您要測試的是自動備份或鍵/值備份,完成下方的對應步驟。
針對自動備份,請完成下列步驟:
執行下列指令:
adb shell bmgr backup @pm@ && adb shell bmgr run
等待前一步驟中的指令執行完畢,方法是監控
adb logcat
,檢查是否有以下輸出內容:I/BackupManagerService: K/V backup pass finished.
執行以下指令執行完整備份作業:
adb shell bmgr fullbackup <PACKAGE>
針對鍵/值備份,請按照下列步驟安排並實際執行備份作業:
如果應用程式自上次備份後並未呼叫
BackupManager.dataChanged()
,您可以執行以下指令,將應用程式加入備份作業中,以便進行測試:adb shell bmgr backup <PACKAGE>
接著,您可以執行以下指令來觸發備份作業:
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
子類別來啟動應用程式。
沒有可備份的資料
如果 logcat 中顯示下列其中一則訊息:
I Backup : [FullBackupSession] Package com.your.app.package doesn't have any backup data.
--- or ---
I Backup : [D2dTransport] Package com.your.app.package doesn't have any backup data.
應用程式沒有可備份的資料。如果您已自行實作 BackupAgent,這可能表示您尚未將任何資料或檔案新增至備份。