測試備份與還原

本頁面說明如何測試應用程式的雲端備份功能和裝置間 (D2D) 的傳輸程序。請務必對應用程式的每個主要版本執行這兩項測試,確保使用者能繼續在新裝置上使用您的應用程式。雖然備份和傳輸相似,但 Android 12 (API 級別 31) 以上版本在這兩者之間存在重大差異,最值得注意的是,相較於雲端備份的 25 MB,傳輸功能可提供更大的 2 GB 資料大小上限。

本指南說明如何在開發週期內有效測試雲端備份與還原以及 D2D 傳輸程序。

測試備份的運作方式

本節說明 Android 備份架構中的各個環節,以及各個環節如何與支援自動備份和鍵/值備份的應用程式互動。在應用程式開發階段,這個架構的內部運作流程多半會經過簡化,因此就算不知道此資訊也無妨。不過在測試階段,瞭解這些概念就顯得益發重要。

下圖說明雲端備份與還原期間的資料流動方式:為了執行測試,您可以使用同一部裝置進行雲端備份與還原:

備份架構資料流程

下圖說明 D2D 傳輸期間的資料流動方式:

傳輸架構資料流

和雲端備份與還原測試的差異是,D2D 測試需要來源裝置和目標裝置,才能複製資料。

「備份管理員服務」是一項 Android 系統服務,可自動化調度管理及啟動備份與還原作業。您可以透過 Backup Manager API 存取這項服務。

在備份作業期間,該服務會查詢您的應用程式是否有備份資料,並將資料交給「備份傳輸」元件封存至雲端。在還原作業期間,備份管理員服務會從備份傳輸中擷取備份資料,並將資料還原至裝置。如果是 D2D 傳輸,備份管理員服務會查詢您的應用程式是否有備份資料,並將資料直接傳送到新裝置的備份管理員服務,該服務會將資料載入至您的應用程式。

「備份傳輸」是負責儲存及擷取應用程式資料的 Android 元件。單一 Android 裝置可以有多個備份傳輸或沒有任何備份傳輸,但只有一個傳輸能夠標示為有效。由於裝置製造商和服務供應商的自訂項目不同,可用的備份傳輸也會因裝置而有所差異,不過大多數支援 Google Play 的裝置仍都搭載以下傳輸機制:

  • GMS 傳輸:此為大多數裝置使用的雲端備份傳輸,屬於 Google 行動服務的一環。這項傳輸機制會在 Android Backup Service 當中儲存資料。
  • D2D 傳輸:在 D2D 遷移作業中使用這項傳輸機制,將資料直接從一部裝置轉移到另一部裝置。

工具

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

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

測試雲端備份

請按照本節的步驟,使用單一裝置執行雲端備份和還原作業。

準備用於雲端備份的裝置或模擬器

如要準備用於備份測試的裝置或模擬器,請檢查下列事項:

  1. 針對自動備份,請確認您使用的裝置或模擬器搭載 Android 6.0 (API 級別 23) 以上版本。
  2. 針對鍵/值備份,請確認您使用的裝置或模擬器搭載 Android 2.2 (API 級別 8) 以上版本。
  3. 您必須連上網際網路才能測試雲端備份。
  4. 使用 Google 帳戶登入裝置,然後依序點選「設定」->「Google」->「備份」將帳戶設為備用帳戶。

如要測試雲端備份,請觸發雲端備份,然後解除安裝應用程式再重新安裝。如果希望之後能重複執行這些步驟,建議您使用 test_cloud_backup.sh 這個指令碼來備份應用程式,並在本機下載 APK、將其解除安裝,然後重新安裝:

#!/bin/bash -eu
: "${1?"Usage: $0 package name"}"

# Initialize and create a backup
adb shell bmgr enable true
adb shell bmgr transport com.android.localtransport/.LocalTransport | grep -q "Selected transport" || (echo "Error: error selecting local transport"; exit 1)
adb shell settings put secure backup_local_transport_parameters 'is_encrypted=true'
adb shell bmgr backupnow "$1" | grep -F "Package $1 with result: Success" || (echo "Backup failed"; exit 1)

# Uninstall and reinstall the app to clear the data and trigger a restore
apk_path_list=$(adb shell pm path "$1")
OIFS=$IFS
IFS=$'\n'
apk_number=0
for apk_line in $apk_path_list
do
    (( ++apk_number ))
    apk_path=${apk_line:8:1000}
    adb pull "$apk_path" "myapk${apk_number}.apk"
done
IFS=$OIFS
adb shell pm uninstall --user 0 "$1"
apks=$(seq -f 'myapk%.f.apk' 1 $apk_number)
adb install-multiple -t --user 0 $apks

# Clean up
adb shell bmgr transport com.google.android.gms/.backup.BackupTransportService
rm $apks

echo "Done"

測試步驟

  1. 開啟應用程式,登入帳戶並修改所有設定。
  2. 執行指令碼並傳入套件名稱,例如 test_cloud_backup.sh com.example.myapp
  3. 重新開啟應用程式,驗證其是否能保留所有資料並正常運作。

理想的狀況是使用者不需登入,且他們的所有設定、進度和應用程式資料都必須與之前相同。如果測試結果不符合這些條件,請確認備份設定正確且不會省略重要資料;從備份內容中排除快取資料後,務必也要處理這些資料的重建作業。針對每次測試疊代重複執行步驟 1 到 3。

測試 D2D 傳輸

測試 D2D 傳輸最完整的方式,是將整個手機內容傳輸到已恢復原廠設定的新裝置上,並確認該裝置是否能正常運作。然而,如果您需要多次重複執行這項程序,可能就會相當不便且耗時。下列步驟說明如何在單一裝置上模擬傳輸作業,但不需重複將裝置恢復原廠設定。

為裝置進行 D2D 測試的準備工作

如要在單一裝置上測試 D2D 傳輸,請按照下列說明進行準備工作:

  1. 裝置必須搭載 Android 12 (API 級別 31) 以上版本。
  2. 如要測試最新版本的 D2D,請在應用程式中指定 Android 12 (API 級別 31) 以上版本為目標。
  3. 建立 test_d2d.sh 這個指令碼,以便重複執行測試:
#!/bin/bash -eu
: "${1?"Usage: $0 package name"}"

# Initialize and create a backup
adb shell bmgr enable true
adb shell settings put secure backup_enable_d2d_test_mode 1
adb shell bmgr transport com.google.android.gms/.backup.migrate.service.D2dTransport
adb shell bmgr init com.google.android.gms/.backup.migrate.service.D2dTransport
adb shell bmgr list transports | grep -q -F "  * com.google.android.gms/.backup.migrate.service.D2dTransport" || (echo "Failed to select and initialize backup transport"; exit 1)
adb shell bmgr backupnow "$1" | grep -F "Package $1 with result: Success" || (echo "Backup failed"; exit 1)

# Uninstall and reinstall the app to clear the data and trigger a restore
apk_path_list=$(adb shell pm path "$1")
OIFS=$IFS
IFS=$'\n'
apk_number=0
for apk_line in $apk_path_list
do
    (( ++apk_number ))
    apk_path=${apk_line:8:1000}
    adb pull "$apk_path" "myapk${apk_number}.apk"
done
IFS=$OIFS
adb shell pm uninstall --user 0 "$1"
adb shell bmgr transport com.google.android.gms/.backup.BackupTransportService
apks=$(seq -f 'myapk%.f.apk' 1 $apk_number)
adb install-multiple -t --user 0 $apks

# Clean up
adb shell bmgr init com.google.android.gms/.backup.migrate.service.D2dTransport
adb shell settings put secure backup_enable_d2d_test_mode 0
adb shell bmgr transport com.google.android.gms/.backup.BackupTransportService
rm $apks

echo "Done"

測試步驟

  1. 在裝置上安裝要測試的應用程式。
  2. 開啟應用程式,登入帳戶並修改應用程式設定。
  3. 在裝置上執行指令碼並傳入套件名稱,例如 test_d2d.sh com.example.myapp
  4. 指令碼執行完畢後,請在裝置上開啟應用程式,驗證其是否能保留所有資料並正常運作。

理想的狀況是使用者不需登入,且他們的所有設定、進度和應用程式資料都必須與執行指令碼之前相同。如果測試結果不符合這些條件,請確認傳輸設定正確且不會省略重要資料;從傳輸內容中排除快取資料後,務必也要處理這些資料的重建作業。針對每次測試疊代重複執行步驟 2 到 4。

排解備份與還原問題

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

超過傳輸配額

如果 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 中顯示以下訊息,表示應用程式啟動備份作業所需的時間超過 10 秒:

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

您可以看到記錄輸出內容中的時間戳記差異。之所以發生這個錯誤,通常是因為應用程式在沒有 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,這可能表示您尚未將任何資料或檔案新增至備份。