preview/backup/index.jd

page.title=Автоматическое резервное копирование для приложений
page.tags=backup, previewresources, androidm
page.keywords=резервное копирование, автоматическое резервное копирование, предварительная версия
page.image=images/cards/card-auto-backup_2x.png
@jd:body

<div id="qv-wrapper">
  <div id="qv">
    <h2>Содержание документа</h2>
      <ol>
        <li><a href="#overview">Обзор</a></li>
        <li><a href="#configuring">Настройка резервного копирования данных</a></li>
        <li><a href="#testing">Тестирование конфигурации резервного копирования</a></li>
        <li><a href="#issues">Известные проблемы</a></li>
      </ol>
  </div>
</div>

<p>
  Пользователи зачастую тратят очень много времени и усилий на создание данных и настройку параметров в приложениях.
 Поэтому одна из важнейших задач при разработке платформы — сделать так, чтобы пользователь не терял свои данные, если его устройство вышло из строя или он решил перейти на новое.
 Устройства под управлением Android M Preview
отлично справляются с этой задачей, автоматически выполняя резервное копирование данных
приложения в Google Drive. Если пользователь перейдет на новое устройство, данные приложений будут автоматически перенесены
на него.
</p>

<p>
  Автоматическое резервное копирование предусмотрено для всех приложений, установленных на устройствах под управлением Android M Preview. При этом
вам не нужно добавлять в приложение дополнительный код. Система сама предложит пользователю возможность включить или отключить
автоматическое резервное копирование данных. Вы также можете указать, для каких данных приложения следует создавать резервные копии, а для каких — нет.
</p>

<p>
  В этой статье описывается новое поведение системы и порядок указания данных приложения,
подлежащих резервному копированию.
</p>

<h2 id="overview">Обзор</h2>

<p>
  При автоматическом резервном копировании данные, создаваемые в вашем приложении на устройстве пользователя, отпраляются в
Google Drive пользователя и происходит их шифрование, что позволяет предотварить потерю данных. Хранилище для ваших данных предоставляется совершенно
бесплатно. Более того, данные резервного копирования засчитываются вне личной квоты пользователя на использование ресурсов Google Drive. В период использования M Developer Preview
пользователи могут хранить в облаке до 25 МБ данных для каждого приложения Android.
</p>

<p>
  Автоматическое резервное копирование выполняется каждые 24 часа, когда устройство не используется, находится в режиме зарядки и подключено к сети
Wi-Fi. При соблюдении необходимых условий служба диспетчера резервного копирования отправляет все доступные резервные копии данных
в облако. Когда пользователь переходит на использование нового устройства или удаляет и заново устанавливает
приложение, для которого имеется резервная копия, выполняется операция восстановления и резервные копии данных переносятся в каталог
переустановленного приложения.
</p>

<p class="note">
  <strong>Примечание.</strong> Если ваше приложение использует устаревшую
<a href="{@docRoot}google/backup/index.html">службу резервного копирования Android</a>, то
вместо нового поведения системы будет применяться существующий механизм резервного копирования.
</p>


<h3 id="auto-exclude">Автоматически исключаемые файлы данных</h3>

<p>
  Не все данные приложения подлежат резервному копированию. В частности, временные файлы и кэш сохранять не нужно. Поэтому служба
автоматического резервного копирования по умолчанию исключает из этого процесса определенные файлы данных:
</p>

<ul>
  <li>файлы в каталогах, на которые ссылаются методы {@link android.content.Context#getCacheDir
getCacheDir()} и {@link android.content.ContextWrapper#getCodeCacheDir getCodeCacheDir()};

  </li>

  <li>файлы во внешнем хранилище, кроме файлов, находящихся в каталогах, на которые ссылается метод
{@link android.content.Context#getExternalFilesDir getExternalFilesDir()};

  </li>

  <li>файлы в каталоге, на который ссылается метод
{@link android.content.Context#getNoBackupFilesDir getNoBackupFilesDir()}.
  </li>
</ul>

<h2 id="configuring">Настройка резервного копирования данных</h2>

<p>
  Резервные копии создаются для данных, создаваемых любым приложением, которое установлено на устройстве под управлением M Preview, исключение составляют только
файлы, обозначенные в предыдущем разделе. Если вы хотите самостоятельно определить,
какие данные вашего приложения подлежат резервному копированию, а какие нет, это можно сделать с помощью соответствующих настроек в манифесте приложения.
</p>

<h3 id="include-exclude">Включение или исключение данных</h3>

<p>
  В зависимости о того, какие данные требуются вашему приложению и как вы их сохраняете, вам может потребоваться задать определенные правила
для включения или исключения определенных файлов или каталогов. Служба автоматического резервного копирования
поддерживает настройку таких правил посредством XML-файла конфигурации и
манифеста приложения. В манифесте приложения можно указать файл конфигурации схемы резервного копирования, как показано в примере
ниже.
</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.my.appexample"&gt;
    &lt;uses-sdk android:minSdkVersion="MNC"/&gt;
    &lt;uses-sdk android:targetSdkVersion="MNC"/&gt;
    &lt;app ...
<strong>        android:fullBackupContent="&#64;xml/mybackupscheme"&gt;</strong>
    &lt;/app&gt;
    ...
&lt;/manifest&gt;
</pre>

<p>
  В этом примере кода атрибут <code>android:fullBackupContent</code> задает XML-файл,
расположенный в каталоге <code>res/xml/</code> проекта приложения, который называется
<code>mybackupscheme.xml</code>. В этом файле конфигурации содержатся правила резервного
копирования файлов. В следующем примере кода демонстрируется файл конфигурации, в котором из процесса резервного копирования исключается определенный
файл:
</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;full-backup-content&gt;
    &lt;exclude domain="database" path="device_info.db"/&gt;
&lt;/full-backup-content&gt;
</pre>

<p>
  В этом примере конфигурации резервного копирования из операции исключается только определенный файл базы данных.
  Для всех остальных файлов будут создаваться резервные копии.
</p>

<h4>Синтаксис конфигурации резервного копирования</h4>

<p>
  Служба резервного копирования предоставляет вам возможность указать, какие файлы следует включить в процесс резервного копирования или
исключить из него. Синтаксис XML-файла конфигурации резервного копирования данных следующий:
</p>

<pre>
&lt;full-backup-content&gt;
    &lt;include domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" /&gt;
    &lt;exclude domain=["file" | "database" | "sharedpref" | "external" | "root"] path="string" /&gt;
&lt;/full-backup-content&gt;
</pre>

<p>
  С помощью перечисленных ниже элементов и атрибутов можно указать файлы, которые вы хотите включить в процесс резервного копирования или исключить из
него:
</p>

<ul>
  <li>
  <code>&lt;include&gt;</code>: используйте этот элемент, если хотите, чтобы система не создавала резервные копии всех данных в вашем приложении, как это происходит по умолчанию, а копировала только определенный набор данных.
 Если указан тег
<code>&lt;include&gt;</code>, система создает резервные копии <em>только для ресурсов</em>
с этим элементом.
  </li>

  <li>
  <code>&lt;exclude&gt;</code>: используйте этот элемент, чтобы указать набор ресурсов, которые
следует исключить из процесса резервного копирования. В таком случае система будет создавать резервные копии всех данных в приложении, кроме ресурсов с этим
элементом;
  </li>

  <li>
  <code>domain.</code>: тип ресурса, который необходимо включить в резервное копирование или исключить из него. Допустимые
значения для этого атрибута могут быть следующие:
  </li>

  <li style="list-style: none">
  <ul>
    <li>
    <code>root</code>: указывает на то, что ресурс находится в корневом каталоге приложения;
    </li>

    <li>
    <code>file</code>: соответствует ресурсу в каталоге, возвращаемом методом
{@link android.content.Context#getFilesDir getFilesDir()};
    </li>

    <li>
    <code>database</code>: соответствует базе данных, возвращаемой методом
{@link android.content.Context#getDatabasePath getDatabasePath()} или классом
{@link android.database.sqlite.SQLiteOpenHelper};
    </li>

    <li>
    <code>sharedpref</code>: соответствует объекту {@link android.content.SharedPreferences},
возвращаемому методом
{@link android.content.Context#getSharedPreferences getSharedPreferences()};
    </li>

    <li>
    <code>external</code>: указывает на то, что ресурс находится во внешнем хранилище, и соответствует
файлу в каталоге, возвращаемом методом
{@link android.content.Context#getExternalFilesDir getExternalFilesDir()};
    </li>

    <li>
    <code>path</code>: путь к ресурсу, который необходимо включить в резервное копирование или исключить
из него.
    </li>
  </ul>
  </li>
</ul>


<h3 id="prohibit">Запрет резервного копирования данных</h3>

<p>
  Можно запретить автоматическое резервное копирование любых данных приложения. Для этого в манифесте в элементе приложения задайте для атрибута
<code>android:allowBackup</code> значение<code>false</code>.
 Как это делается, видно в примере кода ниже:
</p>

<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        package="com.my.appexample"&gt;
    &lt;uses-sdk android:minSdkVersion="MNC"/&gt;
    &lt;uses-sdk android:targetSdkVersion="MNC"/&gt;
    &lt;app ...
<strong>        android:allowBackup="false"&gt;</strong>
    &lt;/app&gt;
    ...
&lt;/manifest&gt;
</pre>


<h2 id="testing">Тестирование конфигурации резервного копирования</h2>

<p>
  После создания конфигурации резервного копирования необходимо ее протестировать и убедиться, что ваше приложение сохраняет данные и впоследствии
они могут быть должным образом восстановлены.
</p>


<h4>Включение журнала резервного копирования</h4>

<p>
  Чтобы упростить для себя анализ обработки вашего XML-файла функцией резервного копирования, прежде чем приступать к тестированию,
включите ведение журнала:
</p>

<pre class="noprettyprint">
$ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE
</pre>

<h4>Тестирование резервного копирования</h4>

<p>Чтобы вручную запустить процесс резервного копирования, сначала активируйте диспетчер резервного копирования, выполнив следующую
команду:
</p>

<pre class="noprettyprint">
$ adb shell bmgr run
</pre>

<p>
  Затем вручную выполните резервное копирование вашего приложения с помощью следующей команды, указав название
пакета в виде параметра <code>&lt;PACKAGE&gt;</code>:
</p>

<pre class="noprettyprint">
$ adb shell bmgr fullbackup &lt;PACKAGE&gt;</pre>


<h4>Тестирование восстановления</h4>

<p>
  Чтобы вручную запустить процесс восстановления после резервного копирования данных приложения, выполните следующую команду, указав название
пакета в виде параметра <code>&lt;PACKAGE&gt;</code>:
</p>

<pre class="noprettyprint">
$ adb shell bmgr restore &lt;PACKAGE&gt;
</pre>

<p class="warning">
  <b>Предупреждение.</b> При выполнении этого действия перед операцией
восстановления работа приложения будет остановлена и все его данные удалены.
</p>

<p>
  Чтобы запустить процесс восстановления, удалите ваше приложение и снова установите его. Данные
приложения будут автоматически восстановлены из облака сразу по завершении установки.
</p>


<h4>Устранение неполадок резервного копирования</h4>

<p>
  При возникновении проблем можно стереть резервные копии данных и все связанные с ними метаданные. Для этого
отключите и повторного включите резервное копирование в разделе <strong>Настройки &gt; Резервное копирование</strong>, восстановите заводские настройки устройства или выполните
следующую команду:
</p>

<pre>$ adb shell bmgr wipe &lt;TRANSPORT&gt; &lt;PACKAGE&gt;</pre>

<p>
  Перед значением <code>&lt;TRANSPORT&gt;</code> должен быть префикс <code>com.google.android.gms</code>.
  Чтобы получить список транспорта, выполните следующую команду:
</p>

<pre>$ adb shell bmgr list transports</pre>

<h2 id="issues">Известные проблемы</h2>

<p>Ниже перечислены известные проблемы в работе службы автоматического резервного копирования.</p>

<ul>
  <li><strong>Google Cloud Messaging</strong>
– существует проблема с приложениями, использующими Google Cloud Messaging для отправки push-уведомлений. Она связана с тем,
что при резервном копировании кода регистрации, возвращаемого Google Cloud Messaging, может нарушиться отправка
push-уведомлений для восстановленного приложения. Важно запросить у API-интерфейса новый код
регистрации после установки приложения на новое устройство, что не выполняется в случае резервного копирования
старого кода регистрации. Чтобы избежать этого, исключите код регистрации из списка файлов
для резервного копирования.
  </li>
</ul>