Testar backup e restauração

Esta página mostra como acionar manualmente operações de backup e restauração com o Backup automático e o Backup de chave-valor para garantir que o app salve e restaure os dados corretamente.

Como o backup funciona

A seção descreve várias partes do framework de backup do Android e como elas interagem com apps compatíveis com o backup automático e o backup de chave-valor. Durante a fase de desenvolvimento do app, a maior parte do funcionamento interno do framework foi abstraída. Por isso, você não precisava dessas informações. No entanto, durante a fase de teste, é importante entender esses conceitos.

O diagrama a seguir ilustra como os dados fluem durante o backup e a restauração: Framework de backup

O Backup Manager Service é um serviço do sistema Android que orquestra e inicia operações de backup e restauração. O serviço pode ser acessado pela API BackupManager. Durante uma operação de backup, o serviço consulta seu app em busca de dados de backup e os entrega à transferência de backup, que arquiva os dados. Durante uma operação de restauração, o Backup Manager Service recupera os dados da transferência de backup e os restaura no dispositivo.

Os Backup Transports são componentes do Android responsáveis por armazenar e recuperar backups. Um dispositivo Android pode ter zero ou mais transferências de backup, mas só uma dessas transferências pode ser marcada como ativa. As transferências de backup disponíveis podem variar de acordo com o dispositivo devido a personalizações feitas por fabricantes e provedores de serviços, mas a maior parte dos dispositivos com o Google Play vem com as seguintes transferências:

  • Transferência do Google (padrão): transferência de backup ativa na maioria dos dispositivos, parte dos Serviços do Google Mobile. Esta documentação presume que os usuários estejam utilizando a transferência do Google. Essa transferência armazena dados de Backup automático em uma pasta particular na conta do Google Drive do usuário. Os dados de Backup de chave-valor são armazenados no Android Backup Service.
  • Transferência local: armazena dados de backup localmente no dispositivo. Essa transferência normalmente é usada para fins de desenvolvimento e depuração e não é útil em situações reais.

Se o dispositivo não tiver nenhuma transferência de backup, não será possível fazer o backup dos dados. Seu app não será afetado negativamente.

Cuidado: como a transferência de backup pode variar de acordo com o dispositivo, o Android não garante a segurança dos dados durante o uso do backup. Tenha cuidado ao usar o backup para armazenar dados confidenciais, como nomes de usuário e senhas.

Pré-requisitos

Para testar suas operações de backup e restauração, é necessário saber um pouco sobre as ferramentas a seguir.

  • adb: usado para executar comandos no dispositivo ou emulador
  • bmgr: usado para realizar várias operações de backup e restauração
  • logcat: usado para ver a saída das operações de backup e restauração

Preparar seu dispositivo ou emulador

Prepare seu dispositivo ou emulador para testes de backup trabalhando na seguinte lista de verificação:

  • Para o backup automático, verifique se você está usando um dispositivo ou emulador com o Android 6.0 (nível da API 23) ou mais recente.
  • Para o Backup de chave-valor, verifique se você está usando um dispositivo ou emulador com o Android 2.2 (nível da API 8) ou mais recente.
  • Verifique se o backup e a restauração estão ativados no dispositivo ou no emulador e se uma Conta do Google foi adicionada. Existem duas maneiras de verificar isso:
    • Dependendo da versão do dispositivo, você pode acessar Configurações > Backup e restauração ou apenas pesquisar Backup na barra de pesquisa na parte superior da tela.
    • No shell do adb, execute bmgr enabled

    Em dispositivos físicos, o backup e a restauração normalmente são ativados durante o assistente de configuração inicial. Os emuladores não executam o assistente de configuração. Portanto, não se esqueça de ativar o backup e especificar uma conta de backup nas configurações do dispositivo.

  • Verifique se a Transferência de backup do Google está disponível e ativa executando o comando: 
    adb shell bmgr list transports

    Em seguida, verifique se o resultado a seguir está no console: 

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

Dispositivos físicos sem o Google Play e emuladores sem APIs do Google podem não incluir a Transferência de backup do Google. Este artigo presume que você esteja usando a Transferência de backup do Google. Você pode testar o backup e a restauração com outras transferências de backup, mas o procedimento e a saída podem ser diferentes.

Testar o backup

Para iniciar um backup do app, execute o seguinte comando: 

adb shell bmgr backupnow <PACKAGE>

O comando backupnow está disponível em dispositivos e emuladores com o Android 7.0 ou mais recente. Ele executa um Backup de chave-valor ou um Backup automático, dependendo das declarações no manifesto do pacote. Verifique o logcat para ver o resultado do procedimento de backup. Exemplo: 

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>}

Se o comando backupnow não estiver disponível no dispositivo, siga as etapas abaixo para backups automáticos ou de chave-valor.

Para os backups automáticos, siga as seguintes etapas:

  1. Execute este comando: 
    adb shell bmgr backup @pm@ && adb shell bmgr run
  2. Aguarde até que o comando da etapa anterior termine, monitorando adb logcat para observar o seguinte resultado: 
    I/BackupManagerService: K/V backup pass finished.
  3. Execute este comando para fazer um backup completo: 
    adb shell bmgr fullbackup <PACKAGE>

Observação: o comando fullbackup força o app a fazer um backup completo, mesmo que o app implemente um backup de chave-valor. O sistema ignora a configuração de backup do app e age como se o atributo android:fullBackupOnly estivesse definido como verdadeiro.

Para Backups de chave-valor, programe e execute o backup com as seguintes etapas:

  1. Se o app não chamou BackupManager.dataChanged() desde o último backup, é possível incluir seu app na operação de backup para fins de teste. Para isso, execute o seguinte comando: 
    adb shell bmgr backup <PACKAGE>
  2. Então, você pode acionar um backup executando o seguinte comando: 
    adb shell bmgr run

bmgr backup adiciona seu app à fila do Backup Manager. bmgr run inicia a operação de backup, que força o Backup Manager a realizar todas as solicitações de backup que estão na fila.

Ao testar Backups de chave-valor, é necessário verificar se toda mudança de preferência programa um backup. Você pode verificar se um backup está programado usando um dos seguintes métodos:

  • Execute adb shell dumpsys backup e verifique se o app está listado no resultado do comando em Pending key/value backup.
  • Registre uma mensagem ao programar um backup. Em seguida, execute adb logcat e verifique o resultado do comando para saber se um backup foi programado.

Testar a restauração

Para iniciar uma restauração manualmente, execute o seguinte comando com um token de backup (veja como conseguir um abaixo):

adb shell bmgr restore <TOKEN> <PACKAGE>

Para procurar tokens de backup, execute adb shell dumpsys backup. O token é a string hexadecimal depois dos rótulos Ancestral: e Current:. O token ancestral se refere ao conjunto de dados de backup usado para restaurar o dispositivo quando ele foi configurado inicialmente (com o assistente de configuração do dispositivo). O token atual se refere ao conjunto de dados de backup atual do dispositivo (o conjunto de dados ao qual o dispositivo envia os dados de backup no momento).

Em seguida, verifique o logcat para ver o resultado do procedimento de restauração. Por exemplo: 

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

Você pode testar a restauração automática do app desinstalando e reinstalando o app com adb ou por meio do app Google Play Store.

Solução de problemas

Esta seção ajuda a resolver alguns problemas comuns.

Cota de transferências excedida

Se as seguintes mensagens forem exibidas no logcat: 

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

--- or ---

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

Seu app excedeu a cota. Reduza a quantidade de dados de backup e tente novamente. Por exemplo, verifique se você está armazenando dados em cache somente no diretório de cache do app. O diretório de cache não está incluído nos backups.

Não é possível fazer backup completo

Se a seguinte mensagem for exibida no logcat: 

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

A operação de backup completo falhou porque nenhuma operação de Backup de chave-valor ocorreu no dispositivo antes. Acione um Backup de chave-valor com o comando bmgr run e tente novamente.

Tempo limite atingido na espera pelo agente

Se a seguinte mensagem for exibida no 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

Seu app está levando mais de 10 segundos para iniciar o backup. Observe a diferença do carimbo de data/hora na saída do registro. Esse erro geralmente ocorre quando seu app usa uma configuração multidex sem o ProGuard.

Conta de backup não inicializada

Se as seguintes mensagens forem exibidas no 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

O backup foi cancelado porque o conjunto de dados não foi inicializado. Execute o gerenciador de backup com o comando adb shell bmgr run e tente executar o backup novamente.

Métodos não chamados do app

Como o backup automático inicia seu app com uma classe básica de Application, os métodos de configuração do app podem não ser chamados. O backup automático também não inicia nenhuma das atividades do app. Por isso, você poderá encontrar erros se o app for configurado em uma atividade. Para saber mais, leia Implementar o BackupAgent.

Por outro lado, o Backup de chave-valor inicia o app com qualquer subclasse Application declarada no arquivo de manifesto do app.