Интеграция OneDrive в приложения Windows Store

OSzone.net » Microsoft » Разработка приложений » Windows (до Windows 10) » Интеграция OneDrive в приложения Windows Store
Автор: Тони Чэмпион
Иcточник: msdn.microsoft.com
Опубликована: 06.11.2014

Сегодня почти любые разговоры о разработке так или иначе касаются облака. Сегодня предлагаются самые разнообразные общедоступные, частные, локальные и другие облачные решения. Но, когда речь заходит о потребительских приложениях, имеющих дело с пользовательскими файлами, все шансы за то, что вы сосредоточитесь на таких предложениях, как Microsoft OneDrive.

Microsoft OneDrive предоставляет потребителям удобный способ хранения, обмена и доступа к личным файлам с любого устройства и в любой точке мира. OneDrive теперь полностью интегрирован во все платформы Microsoft и совместим с большинством других платформ, которые используются в настоящее время. Документами, снимками, видеороликами и многими другими типами файлов можно легко обмениваться, синхронизировать их или обращаться к ним с разных устройств. Поэтому, если вы создаете приложение, работающее с пользовательскими файлами, интеграция OneDrive в это приложение должна быть очень важна.

Если вы создаете приложения Windows Store, то автоматически получаете определенный уровень поддержки OneDrive. В Windows 8.1 вы найдете приложение Windows Store OneDrive, а также интеграцию рабочего стола в файловую систему, которая включает реализации контрактов File Open Picker и File Save Picker. То есть, если вы используете средства для выбора открываемого или сохраняемого файла, пользователь автоматически получит возможность открывать или сохранять документы под своей учетной записью в OneDrive. То же самое относится и диалогам открытия и сохранения файлов в настольных приложениях.

Но как быть, если вам требуется несколько больший контроль над тем, как работает эта интеграция? Что, если вы хотите отображать данные пользователя в другом формате или обрабатывать закачивание или скачивание нескольких файлов в фоне? Учитывая такие сценарии, Microsoft предоставляет API, к которому можно обращаться с любой платформы, и он позволяет разработчикам интегрировать OneDrive в их решения. В этой статье рассматривается как сам API, так и его применение в приложениях Windows Store.

Знакомство с Live SDK

Доступ к содержимому OneDrive облегчается с помощью Live SDK. По сути, Live SDK — это набор REST API на основе JSON, который можно использовать на любой платформе. Live SDK использует единый вход (single sign-on) для приложений Windows Store и Windows Phone Store и аутентификацию на основе OAuth 2.0 для других платформ. Чтобы разработчикам было проще создавать успешные приложения с применением OneDrive, Microsoft также выпустила SDK, специфичные для клиентов. В настоящее время имеются SDK для платформ Microsoft Windows и Windows Phone, а также SDK для Android и iOS. Ссылки на все эти SDK вы найдете на странице msdn.microsoft.com/onedrive/dn630256. Live SDK также можно добавить через NuGet (nuget.org/packages/LiveSDK).

Что касается OneDrive, основная роль Live SDK — обеспечить программный доступ к файлам и папкам по учетной записи пользователя. Вот базовые сервисы, предоставляемые этим SDK:

Я использую Visual Studio 2013 Update 2 и Live SDK версии 5.6, чтобы исследовать, как применять SDK в приложении Windows 8.1 Store, написанном на XAML. При наличии специфичных клиентских SDK для большинства платформ те же концепции можно легко перенести на ваши любимые язык и платформу.

Разработка приложений с применением Live SDK

Прежде чем начать разработку приложений с использованием Live SDK, нужно позаботиться о нескольких вещах. Так как Live SDK не является частью основного Windows SDK, вы должны скачать Live SDK, а затем добавить ссылку на него в приложении. Чтобы добавить ссылку, просто щелкните правой кнопкой мыши свое решение в Visual Studio 2013 и выберите Add Reference. Live SDK можно найти в разделе Windows 8.1 Extensions в Reference Manager, как показано на рис. 1.

*
Рис. 1. Добавление ссылки на Live SDK

По умолчанию в приложении Windows 8.1 Store включена поддержка Internet (Client) в его appxmanifest. Это обязательно для использования Live SDK, и в вашем проекте такая поддержка должна быть включена. Чтобы проверить или включить ее, откройте appxmanifest своего проекта в дизайнере и убедитесь, что на вкладке Capabilities параметр Internet (Client) помечен.

После добавления Live SDK в проект вы найдете весь этот SDK в пространстве имен Microsoft.Live. Однако попытка использования SDK на этом этапе приведет к ошибке из-за ссылки на null-объект. Дело в том, что вы должны зарегистрировать свое приложение в сервисах Live, прежде чем обращаться к OneDrive. Это можно сделать несколькими способами в зависимости от платформы, на которой вы ведете разработку. В случае приложения Windows Store вы связываете его с Windows Store. Самый простой способ решить эту задачу — использовать соответствующий мастер в Visual Studio.

Для запуска мастера щелкните правой кнопкой мыши проект Store в Solutions Explorer и выберите Store | Associate App with the Store. Откроется мастер с описанием того, что вам нужно проделать для того, чтобы продолжить работу. При выборе Next появляется предложение войти под учетной записью Microsoft, сопоставленной с Windows Store (если вы еще не вошли). Кроме того, возможно, вам понадобится пройти второй процесс верификации, например получить код авторизации в виде текстового сообщения на телефонный номер, указанный в вашей учетной записи. Закончив процесс входа, вы увидите список всех зарезервированных имен приложений, связанных с вашей учетной записью, как показано на рис. 2. Если это новое приложение, то на данном экране можно зарезервировать имя нового приложения. После сопоставления имени с вашим приложением выбор Next приведет к переходу на экран сводной информации (summary screen), и щелчок кнопки Associate завершит процесс.

*
Рис. 2. Сопоставление зарезервированного имени с приложением

Теперь ваше приложение настроено и готово к использованию Live SDK.

Доступ к данным пользователя

Первый шаг в интеграции OneDrive в ваше приложение — получение возможности доступа к информации пользователя. Как упоминалось ранее, Live SDK использует 0Auth 2.0 для авторизации. Однако, помимо простой аутентификации приложения, нужно принять во внимание несколько соображений.

Должное использование OneDrive Если вы знакомы с разработкой и развертыванием приложений Windows Store, то знаете о своде правил, детализирующих, что можно, а что нельзя делать в таких приложениях. OneDrive добавляет свой набор правил, которые тоже нужно учитывать.

Главная причина ограничений — уберечь вас от подрыва доверия пользователя к OneDrive. Когда пользователь располагает централизованным хранилищем личной информации, он должен доверять ему, а иначе он просто не станет им пользоваться. Обращаясь к OneDrive с помощью вашего приложения, пользователь распространяет это доверие и на ваше приложение. Поэтому, если ваше приложение станет удалять данные пользователя без его согласия или знания, вы подорвете доверие не только к своему приложению, но и к OneDrive. По этой причине вы должны соблюдать крайнюю осторожность в том, как ваше приложение взаимодействует с OneDrive, особенно при выполнении функций, которые обновляют или удаляют информацию пользователя. Описание этих правил см. по ссылке bit.ly/1rQ8iXK.

Использование единого входа При работе с Live SDK в приложении Windows Store Microsoft предлагает вам задействовать преимущества ее средств единого входа (single sign-on, SSO). Как и в случае Live SDK, добавление SSO в ваше приложение включает несколько дополнительных требований, например заявление о конфиденциальности и панель настройки учетной записи. Полное описание операций, позволяющих добавить в приложение необходимые компоненты, см. по ссылке bit.ly/TJvTxB.

После того как ваше приложение готово к работе с SSO, вход в учетную запись пользователя осуществляется с помощью экземпляра класса LiveAuthClient. В этом классе есть метод LoginAsync, и он будет использовать удостоверения учетной записи Microsoft, по которой был выполнен вход на устройство с Windows 8.1. Если вход прошел успешно, возвращенный объект LiveLoginResult будет содержать экземпляр LiveConnectSession, который будет использоваться для всех вызовов Live SDK. Следующий код обеспечит вход пользователя, а затем вернет объект Session:

LiveAuthClient authClient = new LiveAuthClient();
LiveLoginResult authResult =
  await authClient.LoginAsync(new List<string>() {
  "wl.signin",
  "wl.basic", "wl.skydrive", "wl.skydrive_update" });
if (authResult.Status == LiveConnectSessionStatus.Connected)
{
   // Добавьте код для обработки сеанса,
  // хранящегося в свойстве Session
}

Области Вероятно, вы заметили, что в предыдущем коде используются области вроде wl.signin. Когда ваше приложение входит под учетной записью пользователя, оно должно указать, какой тип доступа ему требуется. Если вы попытаетесь использовать те части API, к которым вы не запрашивали разрешение на доступ, ваши попытки провалятся. В случае приложений Windows Store это ничем не отличается от попыток использовать части Windows SDK, к которым вы не запрашивали разрешение на доступ в разделе capabilities пакета appxmanifest.

В примерах в этой статье будут использоваться только четыре области. Область wl.signin позволяет задействовать преимущества SSO, которые вы должны применять в приложениях Windows Store. Область wl.basic обеспечивает доступ к некоторой общей информации о пользователе.

В случае приложений OneDrive вы должны побеспокоиться лишь о двух дополнительных областях: wl.skydrive и wl.skydrive_update. Как и предполагают их названия, wl.skydrive нужна для чтения и перехода к учетной записи пользователя OneDrive. Если приложению требуется возможность закачивания файлов, создания или удаления папок либо изменения свойств каких-то объектов, вы используете область wl.skydrive_update. Эта область также выдает разрешение на чтение в OneDrive, поэтому включать в список доступа и wl.skydrive, и wl.skydrive_update не нужно.

Для поддержки обратной совместимости с приложениями, использующими предыдущий бренд (SkyDrive), имена областей OneDrive не изменились. Но я не удивлюсь, если в будущих версиях API появится пара дополнительных областей с именами, соответствующими уже новому бренду — OneDrive.

Поскольку Live SDK охватывает гораздо больше, чем только OneDrive, существует много других областей, но рассматривать их в этой статье я не буду. Полный список вы найдете по ссылке msdn.microsoft.com/library/dn631845.

Получение согласия пользователя При первом запуске приложения, запрашивающего доступ к учетной записи OneDrive, пользователю будет предложено выдать приложению разрешение на доступ к областям, указанным при входе. На рис. 3 показан пример такого запроса в приложении Windows Store. Как только пользователь выдает разрешение, этот запрос больше не появляется, если только список областей не изменится. Если обновленная версия приложения запрашивает дополнительные средства API, пользователю снова будет предложено выдать разрешение.

*
Рис. 3. Запрос у пользователя согласия на доступ к OneDrive

Объекты в OneDrive

В OneDrive API все считается объектом. Будь то папка, снимок или электронная таблица — все, что хранится в OneDrive, имеет набор схожих свойств и общих вызовов API. У каждого объекта есть набор свойств и может быть набор дочерних объектов. В этой статье я сосредоточусь на объектах следующих типов: Folder, File, Album и Photo. Полный список доступных объектов с описанием и примерами использования см. по ссылке msdn.microsoft.com/library/dn631843.

Как только ваше приложение получает экземпляр LiveConnectionSession от метода LoginAsync класса LiveAuthClient, этот экземпляр сеанса можно использовать для создания экземпляра класса LiveConnectClient, который содержит все API-вызовы для взаимодействия с OneDrive. В следующем примере показано создание экземпляра LiveConnectClient и запрос к OneDrive на получение объекта корневой папки пользователя, который можно извлечь, используя путь me/skydrive:

public async Task<object> GetRootFolder()
{
  LiveConnectClient client = new LiveConnectClient(_session);
  LiveOperationResult liveOpResult =
    await client.GetAsync("me/skydrive");
  dynamic dynResult = liveOpResult.Result;
  return dynResult;
}

В этом коде применяется ключевое слово dynamic, чтобы создать экземпляр нижележащей строки в формате JSON в период выполнения. Хотя такой способ быстр и прост, учитывайте, что вы можете столкнуться с некоторыми ограничениями, которые потребуют более формальной структуры класса.

Результаты, возвращенные методом GetAsync, будут содержать все свойства запрошенного объекта. На рис. 4 показан пример строки в формате JSON, возвращаемой для корневой папки пользователя.

Рис. 4. JSON, возвращаемый запросом объекта папки

{
  "id": "folder.abced3a35e6d1b",
  "from": {
    "name": null,
    "id": null
  },
  "name": "SkyDrive",
  "description": "",
  "parent_id": null,
  "size": 2957188732,
  "upload_location":
    "https://apis.live.net/v5.0/folder.abced3a35e6d1b/files/",
  "comments_count": 0,
  "comments_enabled": false,
  "is_embeddable": false,
  "count": 25,
  "link": "https://onedrive.live.com?cid=abced3a35e6d1b",
  "type": "folder",
  "shared_with": {
    "access": "Just me"
  },
  "created_time": null,
  "updated_time": "2014-06-13T18:00:54+0000",
  "client_updated_time": "2012-10-22T19:50:04+0000"
}

При запросах в рамках OneDrive может оказаться полезным создание более специфичного запроса. Скажем, следующий код вернет все дочерние объекты в корневом каталоге:

LiveOperationResult liveOpResult = await client.GetAsync("me/skydrive/files");

К ним относятся папки и файлы в корневом каталоге, и потенциально это может быть большой массив данных.

Как быть, если вам нужно просмотреть только список снимков в этом каталоге? Для этого используйте параметр filter запроса. Кроме него, OneDrive API поддерживает несколько других типов параметров запроса, таких как limit, offset и search. Параметры позволяют получать лишь нужные вам данные, и они не только ограничивают объем данных, которые вам приходится скачивать, но и количество кода, требуемого для обработки возвращаемых данных.

Например, следующий запрос возвращает только список снимков в корневом каталоге, избавляя вас от необходимости писать код для отделения снимков от папок:

LiveOperationResult liveOpResult =
  await client.GetAsync("me/skydrive/files?filter=photos");

Полный список параметров запросов и их применение см. по ссылке msdn.microsoft.com/library/dn631842.

Работа с папками

Если вы намерены работать с той или иной файловой системой, логично начать со структуры папок. При запросе папки можно использовать два типа идентификаторов: понятный человеку путь вроде me/skydrive или идентификатор папки, который выглядит наподобие folder.abcde86dfb3a35e6d1b.ABCDED3A35E6D1B!532. Если вы хотите запросить список дочерних объектов папки, то можете добавить «/files» к пути. Например, следующий код вернет список всех файлов, папок и альбомов для данного идентификатора папки:

LiveOperationResult liveOpResult =
  await client.GetAsync("folder.abcde86dfb3a35e6d1b.ABCDED3A35E6D1B!532/files");

OneDrive содержит два типа объектов folder: folder и album. Альбом можно рассматривать как папку особого типа, которая находится в корневом каталоге пользователя OneDrive. Альбомы могут содержать снимки и видеоролики, а также структуру папок и дополнительные файлы.

Важно понимать разницу между папкой и альбомом, так как следующий запрос вернет только папки в вашем корневом каталоге и проигнорирует все альбомы. Это может дать неожиданные результаты:

LiveOperationResult liveOpResult =
  await client.GetAsync("me/skydrive/files?filter=folders");

Чтобы получить и папки, и альбомы, используйте для filter значение «folders,albums».

Предыдущий запрос позволяет просмотреть всю структуру папок по учетной записи пользователя OneDrive, получая дочерние папки каждой папки. В исходном коде, сопутствующем этой статье, содержится приложение-пример MyPhotoAlbum — приложение Windows Store на XAML с двумя страницами. Первая страница, FolderPage, дает возможность просмотреть структуру каталогов и показывает результаты в GridView. Все вызовы Live SDK обернуты в класс OneDriveDataProvider.

На рис. 5 приведен метод, используемый для прохода по структуре папок. Он принимает идентификатор текущей папки и указывает для фильтра значение «folders,albums». Если идентификатора папки нет, метод возвращает корневой каталог.

Рис. 5. Метод GetFolderItems

public async Task<List<object>>
  GetFolderItems(string path, string filter)
{
  if (_session == null)
  {
    await InitProvider();
  }
  if (String.IsNullOrEmpty(path))
  {
    path = "me/skydrive";
  }
  if (!String.IsNullOrEmpty(filter))
  {
    filter = "?filter=" + filter;
  }
  LiveConnectClient client = new LiveConnectClient(_session);
  LiveOperationResult liveOpResult =
    await client.GetAsync(path + "/files" + filter);
  dynamic dynResult = liveOpResult.Result;
  return new List<object>(dynResult.data);
}

На рис. 6 показан пример результатов, возвращаемых в FolderPage. Выбрав дочернюю папку, вы перейдете на ту же страницу FolderPage, используя эту дочернюю папку как параметр. Это позволяет стеку навигации поддерживать функциональность возврата для перемещения обратно к структуре папок.

*
Рис. 6. Страница FolderPage

Если вы запросили доступ на обновление, используя область wl.skydrive_update, то можете также создавать и удалять папки через API. Папка содержит только три свойства, которые можно создавать или изменять: name, description и sort_by. При создании папки вы должны указать родительский каталог по пути или идентификатору и предоставить JSON-массив, как минимум, с каким-то именем. Вот пример JSON, необходимого для создания новой папки:

{
 "name": "My Favorite Photos",
 "description": "A folder full of my favorite photos."
}

SDK обрабатывает это методом PostAsync класса LiveConnectClient. Рис. 7 иллюстрирует метод, применяемый для создания новой папки.

Рис. 7. Метод CreateFolder

public async Task<bool> CreateFolder(string path, string name)
{
  try
  {
    var folderData = new Dictionary<string, object>();
    folderData.Add("name", name);
    LiveConnectClient liveClient = new LiveConnectClient(_session);
    LiveOperationResult operationResult =
      await liveClient.PostAsync(path, folderData);
    dynamic result = operationResult.Result;
    return true;
  }
  catch (LiveConnectException exception)
  {
    return false;
  }
}

Удаление папки выполняется методом DeleteAsync, который позволяет удалять и файлы. Важно помнить о поддержании целостности OneDrive и с осторожностью использовать любую функцию удаления:

LiveOperationResult operationResult = await liveClient.DeleteAsync(path);

Работа с файлами

Хотя метод GetAsync возвращает свойства файла, он не возвращает сам файл. Единственный способ получить файл от OneDrive — скачать его. С этой целью Live SDK для приложений Windows Store создает фоновую задачу скачивания, которая асинхронно обрабатывает процесс скачивания, не блокируя устройство. Для скачивания файла из OneDrive можно использовать следующий код:

try
{
  LiveConnectClient liveClient = new LiveConnectClient(_session);
  LiveDownloadOperation op =
    await liveClient.CreateBackgroundDownloadAsync(filePath);
  var result = await op.StartAsync();
  // Обрабатываем результат
}
catch
{
 // Обрабатываем ошибки
}

Как только фоновая операция скачивания возвращается, ее нужно начать вызовом метода StartAsync экземпляра LiveDownloadOperation.

Аналогично скачиванию файла единственный способ добавить или обновить файл в OneDrive — закачать его. Чтобы закачать файл, ваше приложение должно запросить права доступа для записи, используя область wl.skydrive_update. Метод CreateBackgroundUploadAsync принимает путь к папке, имя файла, поток данных, содержащих файл, и флаг перезаписи. Если файл уже существует, флаг перезаписи позволяет либо перезаписать оригинальный файл, либо сохранить оригинальный файл и переименовать новый файл, который вы закачиваете. Как и в случае функций обновления, будьте осторожны с этой функциональностью, чтобы случайно не повредить файлы. Ниже дан пример того, как закачать файл:

try
{
  LiveConnectClient liveClient = new LiveConnectClient(_session);
  LiveUploadOperation op = await liveClient.CreateBackgroundUploadAsync(
    path, filename, fileStream, OverwriteOption.Rename);
  var result = await op.StartAsync();
  // Обрабатываем результат
}
catch
{
  // Обрабатываем ошибки
}

Перед закачкой файла важно убедиться в наличии достаточного места под новый файл. Вы можете проверить объем доступного пространства, указав путь «me/skydrive/quota» в методе GetObjectAsync. В этом случае он вернет два свойства — quota и available, которые позволят вычислить количество байтов, свободных для пользователя с данной учетной записью.

При работе с файлами в API есть два удобных дополнительных средства. Если вы хотите создать копию файла, то могли бы скачать этот файл, а потом закачать его уже под другим именем. Однако это потребовало бы слишком много сетевого трафика для столь простой операции. Более того, а что делать, если вы хотите скопировать всю папку или переместить дочернюю папку в другую родительскую? Код и сетевой трафик для выполнения этих задач с использованием скачивания и закачивания превратил бы такие операции в сущий кошмар. Чтобы избежать этой проблемы, в OneDrive API есть команды перемещения и копирования: MoveAsync и CopyAsync. Оба метода принимают два параметра: объект (файл или папку) для перемещения и путь назначения. На рис. 8 показан метод, используемый для копирования файла.

Рис. 8. Копирование файла

public async Task<bool> CopyObject(string path, string destination)
{
  if (_session == null)
  {
    await InitProvider();
  }
  try
  {
    LiveConnectClient liveClient = new LiveConnectClient(_session);
    LiveOperationResult operationResult =
      await liveClient.CopyAsync(path, destination);
    return true;
  }
  catch (LiveConnectException exception)
  {
    return false;
  }
}

Заключение

В одной статье описать все возможности API невозможно. Live SDK включает много других средств, особенно для операций со снимками и видеороликами. Если вы подумываете об интеграции OneDrive в свое решение, вам стоит исследовать эти дополнительные средства. Microsoft создала OneDrive Development Center (dev.onedrive.com), который предоставляет вам единую точку доступа для всего, что связано с OneDrive API.

Создаете вы приложения для Windows Store, Windows Phone Store или любой другой платформы, где нужен доступ к файлам пользователя, добавление OneDrive — отличный способ интегрировать ваше приложение в повседневную деятельность пользователя, предоставив ему доступ к наиболее важным для него файлам. Так что, придумывая собственную пользовательскую среду, не забудьте включить в нее OneDrive.


Ссылка: http://www.oszone.net/25402/OneDrive