使用自動備份功能備份使用者資料

「應用程式自動備份」功能會自動針對在 Android 6.0 (API 級別 23) 及以上版本指定及執行的應用程式,備份使用者資料。Android 會將應用程式資料上傳到使用者的 Google 雲端硬碟,並妥善儲存在使用者的 Google 帳戶憑證中,藉此保留應用程式資料。在搭載 Android 9 以上版本的裝置上,系統會使用裝置的 PIN 碼、解鎖圖案或密碼,對備份資料進行端對端加密處理。每位使用者的資料量上限為 25 MB。系統不會針對儲存的備份資料收費。您的應用程式可以自訂備份程序,或透過停用備份功能來選擇退出。

如要更全面瞭解 Android 備份選項和應備份及還原的資料,請參閱「資料備份總覽」。

會進行備份的檔案

根據預設,自動備份功能包含大部分目錄中的檔案,這些目錄是由系統指派給應用程式:

自動備份功能會排除以下項目所傳回目錄中的檔案:getCacheDir()getCodeCacheDir()getNoBackupFilesDir()。儲存在這些位置的檔案只是暫時需要,因此會特意排除在備份作業之外。

您可以設定應用程式,納入及排除特定檔案。詳情請參閱「納入及排除檔案」一節。

備份位置

備份資料會儲存在使用者 Google 雲端硬碟帳戶的私人資料夾中,每個應用程式的資料量上限為 25 MB。已儲存的資料不會計入使用者的個人 Google 雲端硬碟配額。系統只會儲存最近的備份。進行備份時,先前的備份資料皆會刪除。使用者或裝置上的其他應用程式無法讀取備份資料。

使用者可以查看已在 Google 雲端硬碟 Android 應用程式中備份的應用程式清單。如果是 Android 裝置,使用者則可透過雲端硬碟應用程式的導覽匣,依序前往「設定」>「備份及重設」查看這份清單

每個裝置設定生命週期的備份資料都會儲存在不同的資料集,如以下範例所示:

  • 如果使用者擁有兩部裝置,則每部裝置都會有備份資料集。

  • 如果使用者將裝置恢復原廠設定,然後使用相同的帳戶設定裝置,系統會將備份儲存至新的資料集。過時資料集會在閒置一段時間後自動刪除。

備份時間表

系統會在符合下列所有條件時自動執行備份:

  • 使用者在裝置上啟用備份功能。在 Android 9 中,這項設定位於「設定」>「系統」>「備份」
  • 從上次備份到現在已經過了 24 小時。
  • 裝置處於閒置狀態。
  • 裝置已連接 Wi-Fi 網路 (如果裝置使用者未選擇啟用行動數據備份功能)。

實際上,這些條件幾乎每晚都會發生,但如果裝置從未連上網路,就可能完全不進行備份。為節省網路頻寬,除非應用程式資料已變更,上傳作業才會執行。

在自動備份期間,系統會關閉應用程式,以確保該應用程式不再寫入檔案系統。根據預設,備份系統會忽略在前景執行的應用程式,避免使用者體驗不佳。只要將 android:backupInForeground 屬性設為 true,即可覆寫預設行為。

為簡化測試流程,Android 提供手動備份應用程式的工具。詳情請參閱「測試備份與還原」的相關說明。

還原時間表

無論安裝作業是從 Play 商店執行、在裝置設定期間 (即系統安裝先前已安裝的應用程式),還是透過 adb 執行,系統一律會在應用程式安裝時還原資料。還原作業的執行時間會在 APK 安裝完成後,但在應用程式可供使用者啟動之前。

在初始裝置設定精靈中,系統會向使用者顯示可用備份資料集的清單,並詢問要從哪些資料集還原資料。只要選取任何備份資料集,就會成為該裝置的祖系資料集。裝置可以從本身的備份或祖系資料集還原。如果同時可以使用這兩個來源的備份資料,裝置會優先採用本身的備份資料。如果使用者未通過裝置設定精靈,則只能從自身備份還原。

為簡化測試流程,Android 提供手動還原應用程式的工具。詳情請參閱「測試備份與還原」的相關說明。

啟用及停用備份

以 Android 6.0 (API 級別 23) 或以上版本為目標的應用程式會自動加入「自動備份」功能。在應用程式資訊清單檔案中,將布林值 android:allowBackup 設為啟用或停用備份。預設值為 true,但建議在資訊清單中明確設定屬性,如下所示:

<manifest ... >
    ...
    <application android:allowBackup="true" ... >
        ...
    </application>
</manifest>

如要停用備份功能,請將 android:allowBackup 設為 false。如果應用程式可以透過其他機制重建狀態,或是應用程式會處理機密資訊,則建議停用備份功能。

納入並排除檔案

根據預設,系統會備份絕大多數的應用程式資料。詳情請參閱「會備份的檔案」一節。

本節說明如何定義自訂 XML 規則,控管要備份的內容。如果應用程式指定 Android 12 (API 級別 31) 以上版本,則必須按照本節說明指定其他 XML 備份規則組合,支援在搭載這些 Android 版本的裝置上推出的備份還原相關異動

在 Android 11 及以下版本中控管備份功能

請按照本節所述步驟,在搭載 Android 11 (API 級別 30) 以下版本的裝置上控管要備份的檔案。

  1. AndroidManifest.xml 檔案中,將 android:fullBackupContent 屬性加入 <application> 元素,如以下範例所示。這個屬性會指向包含備份規則的 XML 檔案。

    <application ...
     android:fullBackupContent="@xml/backup_rules">
    </application>
    
  2. res/xml/ 目錄中建立一個名為 @xml/backup_rules 的 XML 檔案。並在這個檔案中新增包含 <include><exclude> 元素的規則。以下範例會備份 device.xml 以外的所有共用偏好設定:

    <?xml version="1.0" encoding="utf-8"?>
    <full-backup-content>
     <include domain="sharedpref" path="."/>
     <exclude domain="sharedpref" path="device.xml"/>
    </full-backup-content>
    

定義備份所需的裝置條件

如果應用程式會將機密資訊儲存在裝置中,您可以指定在使用者資料備份中納入資料的條件。您可以在 Android 9 (API 級別 28) 或以上版本中新增以下條件:

如果您已將開發裝置升級至 Android 9,則必須在升級後停用,然後重新啟用資料備份功能。這是因為 Android 只會在透過「設定」或「設定精靈」通知使用者後,以用戶端密鑰加密備份資料。

如要宣告納入條件,請將 requireFlags 屬性設為備份規則集內 <include> 元素中的一或多個所需值:

backup_rules.xml

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <!-- App data isn't included in user's backup
         unless client-side encryption is enabled. -->
    <include domain="file" path="."
             requireFlags="clientSideEncryption" />
</full-backup-content>

如果應用程式實作鍵/值備份系統,或是自行實作 BackupAgent,您也可以針對 BackupDataOutput 物件組合的傳送標記組合和自訂備份代理程式的 FLAG_CLIENT_SIDE_ENCRYPTION_ENABLEDFLAG_DEVICE_TO_DEVICE_TRANSFER 標記進行位元比較,將這些條件要求套用至備份邏輯。

下列程式碼片段說明了這個方法的用法:

Kotlin

class CustomBackupAgent : BackupAgent() {
    override fun onBackup(oldState: ParcelFileDescriptor?,
            data: BackupDataOutput?, newState: ParcelFileDescriptor?) {
        if (data != null) {
            if ((data.transportFlags and
                    FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED) != 0) {
                // Client-side backup encryption is enabled.
            }

            if ((data.transportFlags and FLAG_DEVICE_TO_DEVICE_TRANSFER) != 0) {
                // Local device-to-device transfer is enabled.
            }
        }
    }

    // Implementation of onRestore() here.
}

Java

public class CustomBackupAgent extends BackupAgent {
    @Override
    public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
            ParcelFileDescriptor newState) throws IOException {
        if ((data.getTransportFlags() &
                FLAG_CLIENT_SIDE_ENCRYPTION_ENABLED) != 0) {
            // Client-side backup encryption is enabled.
        }

        if ((data.getTransportFlags() &
                FLAG_DEVICE_TO_DEVICE_TRANSFER) != 0) {
            // Local device-to-device transfer is enabled.
        }
    }

    // Implementation of onRestore() here.
}

在 Android 12 或以上版本中控制備份

如果您的應用程式指定 Android 12 (API 級別 31) 以上版本,請按照本節所述步驟,在搭載 Android 12 以上版本的裝置上控管要備份的檔案。

  1. AndroidManifest.xml 檔案中,將 android:dataExtractionRules 屬性加入 <application> 元素,如以下範例所示。這個屬性會指向包含備份規則的 XML 檔案。

    <application ...
     android:dataExtractionRules="backup_rules.xml">
    </application>
    
  2. res/xml/ 目錄中建立一個名為 backup_rules.xml 的 XML 檔案。並在這個檔案中新增包含 <include><exclude> 元素的規則。以下範例會備份 device.xml 以外的所有共用偏好設定:

    <?xml version="1.0" encoding="utf-8"?>
    <data-extraction-rules>
     <cloud-backup [disableIfNoEncryptionCapabilities="true|false"]>
       <include domain="sharedpref" path="."/>
       <exclude domain="sharedpref" path="device.xml"/>
     </cloud-backup>
    </data-extraction-rules>
    

XML 設定語法

設定檔的 XML 語法取決於應用程式指定及執行的 Android 版本。

Android 11 或以下版本

針對搭載 Android 11 或以下版本的裝置控管備份作業的設定檔,使用以下 XML 語法。

<full-backup-content>
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"
    requireFlags=["clientSideEncryption" | "deviceToDeviceTransfer"] />
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string" />
</full-backup-content>

搭載 Android 12 或以上版本

如果您的應用程式指定 Android 12 (API 級別 31) 或以上的版本,請針對搭載 Android 12 或以上版本的裝置控制設定檔,並使用以下 XML 語法。

<data-extraction-rules>
  <cloud-backup [disableIfNoEncryptionCapabilities="true|false"]>
    ...
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
  </cloud-backup>
  <device-transfer>
    ...
    <include domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
    <exclude domain=["file" | "database" | "sharedpref" | "external" |
                     "root" | "device_file" | "device_database" |
                     "device_sharedpref" | "device_root" ] path="string"/>
    ...
  </device-transfer>
</data-extraction-rules>

每部分的設定 (<cloud-backup><device-transfer>) 都包含僅適用於該傳輸類型的規則。舉例來說,您可以使用這個區隔方式,從 Google 雲端硬碟備份作業中排除檔案或目錄,但仍在裝置間 (D2D) 傳輸作業期間傳輸該檔案或目錄。檔案過大時,這項功能就非常實用。雖然無法將該檔案備份到雲端,但可以順利在裝置間傳輸。

如果沒有為特定備份模式設定規則 (例如缺少 <device-transfer> 區段),系統會針對 no-backupcache 目錄以外的所有內容全面啟用該模式,如「會備份的檔案」一節所述。

應用程式可在 <cloud-backup> 區段中設定 disableIfNoEncryptionCapabilities 旗標,確保備份只有在可加密的情況下 (例如在使用者設有螢幕鎖定時) 才會發生。設定這項限制後,如果使用者的裝置不支援加密功能,系統就不會將備份資料傳送至雲端,但由於 D2D 傳輸作業不會傳送至伺服器,因此即使裝置不支援加密功能,備份功能仍會繼續運作。

包含和排除元素的語法

<full-backup-content><cloud-backup><device-transfer> 標記內 (視裝置的 Android 版本和應用程式的 targetSDKVersion 而定),您可以定義 <include><exclude> 元素:

<include>

指定要備份的檔案或資料夾。根據預設,自動備份功能涵蓋幾乎所有的應用程式檔案。如果您指定 <include> 元素,系統就不會預設納入任何檔案,而是「僅備份指定的檔案」。如要納入多個檔案,請使用多個 <include> 元素。

Android 11 及以下版本,這個元素也可以包含 requireFlags 屬性,定義備份的條件要求一節會詳細說明實作方式。

系統一律會排除 getCacheDir()getCodeCacheDir()getNoBackupFilesDir() 所傳回目錄中的檔案,即使您納入這些檔案也一樣。

<exclude>

指定要在備份期間排除的檔案或資料夾。以下列舉一些常見的備份檔案:

  • 含有裝置專屬 ID 的檔案,這類 ID 是由伺服器核發或在裝置上產生。舉例來說,每當使用者在新裝置上安裝應用程式時,Firebase 雲端通訊 (FCM) 都必須產生註冊權杖。如果還原的是舊註冊權杖,應用程式可能會產生非預期的行為。

  • 與應用程式偵錯相關的檔案。

  • 導致應用程式超過 25 MB 備份配額的大型檔案。

每個 <include><exclude> 元素都必須包含下列兩個屬性:

domain

指定資源的所在位置。這個屬性的有效值包括:

  • root:儲存應用程式所有私人檔案的檔案系統目錄。
  • filegetFilesDir() 傳回的目錄。
  • databasegetDatabasePath() 傳回的目錄,使用 SQLiteOpenHelper 建立的資料庫會儲存在這裡。
  • sharedpref:儲存 SharedPreferences 的目錄。
  • externalgetExternalFilesDir() 傳回的目錄。
  • device_root:例如 root,但裝置保護的儲存空間。
  • device_file:例如 file,但裝置保護的儲存空間。
  • device_database:例如 database,但裝置保護的儲存空間。
  • device_sharedpref:例如 sharedpref,但裝置保護的儲存空間。
path

指定要納入或排除備份中的檔案或資料夾。請注意以下事項:

  • 這個屬性不支援萬用字元或規則運算式語法。
  • 您可以使用 ./ 參照目前的目錄,但基於安全考量,您無法參照父項目錄,比如使用 ..
  • 如果您指定目錄,規則就會套用至目錄和遞迴子目錄中的所有檔案。

實作 BackupAgent

實作自動備份功能的應用程式不需要實作 BackupAgent,不過,您也可以選擇實作自訂 BackupAgent。一般來說,這樣做的原因有 2 種:

  • 您想收到備份事件的通知,例如 onRestoreFinished()onQuotaExceeded(long, long)。即使應用程式並未執行,仍會執行這些回呼方法。

  • 您無法運用 XML 規則輕鬆表示要備份的檔案組合。在這種少數情況下,您可以實作會覆寫 onFullBackup(FullBackupDataOutput)BackupAgent,儲存所需的資料。如要保留系統的預設實作方式,請使用 super.onFullBackup() 對父類別呼叫相應的方法。

如果您實作 BackupAgent,根據預設,系統會預期應用程式執行鍵/值備份與還原作業。如要改用以檔案為基礎的自動備份功能,請在應用程式資訊清單中,將 android:fullBackupOnly 屬性設為 true

在自動備份和還原作業期間,系統會以受限模式啟動應用程式,防止應用程式存取可能導致衝突的檔案,並讓應用程式在 BackupAgent 中執行回呼方法。在這個限制模式下,系統不會自動啟動應用程式的主要活動,也不會初始化其內容供應器,且基礎類別 Application 會例項化,而非應用程式資訊清單中宣告的任何子類別。

您的 BackupAgent 必須實作抽象方法 onBackup()onRestore(),這兩種方法都用於鍵/值備份。如果不想執行鍵/值備份,請將這些方法的實作留空。

詳情請參閱延長 AgentAgent