測試備份與還原

本頁面說明如何測試應用程式的雲端備份功能和裝置間 (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、將 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，這可能表示您尚未將任何資料或檔案新增至備份。