Поделиться через

Сохранение файлов с помощью пакета SDK 7.2 средства выбора файлов в OneDrive для JavaScript

  • Статья

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

1. Регистрация приложения

Чтобы использовать средство выбора OneDrive, необходимо зарегистрировать приложение на странице регистрации приложение Azure и получить идентификатор приложения. Также необходимо добавить допустимый URI перенаправления для веб-приложения с помощью средства выбора. Это может быть страница, на которой размещен пакет SDK средства выбора, или заданный вами пользовательский URL-адрес. Дополнительные сведения см. в разделе Настройка.

2. Добавление ссылки на пакет SDK

Внедрите пакет SDK на JavaScript для OneDrive в свою страницу.

<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>

3. Запуск средства выбора файла

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

В рамках метода OneDrive.save(...) укажите параметры, определяющие поведение средства выбора и то, каким образом средство выбора будет совершать обратные вызовы в ваш код, а также объект options.

<script type="text/javascript">
  function launchSaveToOneDrive(){
    var odOptions = { /* ... specify the desired options ... */ };
    OneDrive.save(odOptions);
  }
</script>

<input id="fileUploadControl" name="fileUploadControl" type="file" />
<button onclick="launchSaveToOneDrive">Save to OneDrive</button>

Параметры средства выбора

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

Пример параметров средства выбора файлов

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "save",
  sourceInputElementId: "fileUploadControl",
  sourceUri: "",
  fileName: "file.txt",
  openInNewWindow: true,
  advanced: {},
  success: function(files) { /* success handler */ },
  progress: function(percent) { /* progress handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

Параметры

Имя параметра Описание
clientId Идентификатор приложения, созданный консолью регистрации приложения для вашей интеграции.
action Тип действия, выполняемого над выбранными файлами. Вы можете указать значение save, чтобы сохранять файлы непосредственно в OneDrive, либо значение query, чтобы возвращать идентификаторы, которые можно использовать с API Microsoft Graph или API OneDrive для сохранения файлов в выбранную папку.
sourceInputElementId Идентификатор элемента ввода формы (type=file) для файла, который необходимо отправить.
sourceUri HTTP, HTTPS или URI данных для файла, который необходимо отправить. OneDrive для бизнеса и SharePoint поддерживают только значения URI данных.
fileName Обязательный, если параметр sourceUri представляет собой URI данных. Если значение этого свойства не указано, имя файла будет получено из атрибута имени элемента ввода.
openInNewWindow По умолчанию используется значение true. Если указано это значение, интерфейс средства выбора в OneDrive откроется во всплывающем окне. Если указано значение false, интерфейс средства выбора в OneDrive откроется в том же окне.
viewType Тип элемента, который можно выбрать. Значение по умолчанию — files. Можно указать параметр folders, чтобы ограничить выбор только папками, или указать параметр all, позволяющий выбрать одновременно файлы и папки.
accountSwitchEnabled По умолчанию задано значение true, которое приводит к отображению пользовательского интерфейса смены учетной записи на размещенной странице средства выбора файлов.
advanced Коллекция дополнительных свойств, с помощью которых можно более глубоко настроить поведение средства выбора. Эти свойства не нужны в большинстве сценариев. Дополнительные сведения см. в разделе, посвященном расширенным сценариям сохранения.
nameConflictBehavior Необязательный параметр, передаваемый в ситуации, когда имя отправляемого файла конфликтует с именем файла, уже имеющегося в папке назначения. Дополнительные сведения см. в разделе, посвященном определению этого параметра.
success Вызывается после завершения отправки файла на сервер. Параметр files — это коллекция метаданных, возвращаемых службой для отправленного файла.
progress Вызывается в разные моменты времени с числом от 0,0 до 100,0 для указания хода отправки. По крайней мере один раз этот параметр вызывается со значением 100,0.
cancel Вызывается, если пользователь нажимает кнопку отмены в средстве сохранения.
error Вызывается, если на сервере произошла ошибка, пользователь превысил квоту, у пользователя нет разрешения на отправку файла в выбранное расположение или если пользователь не выбрал файл, который необходимо отправить.

Примечание. Если параметр openInNewWindow имеет значение false, то чтобы можно было ссылаться на пакет SDK для гарантированного вызова функций, сначала необходимо глобально объявить все функции обратного вызова на странице. При глобальной регистрации к именам функций обратного вызова добавляется префикс oneDriveFilePicker. Например, функция success становится функцией oneDriveFilePickerSuccess.

Типы действий

С помощью параметра action пакета SDK средства выбора вы можете указать, как средство выбора должно вести себя. Для действия save() разрешены указанные ниже значения.

Значение Описание
save Сохраняет файл, предоставленный sourceInputElementId или sourceUri , в выбранную папку в OneDrive пользователя.
query Возвращает метаданные API о выбранной папке. Затем ваше приложение отправляет один или несколько файлов в папку, выбранную пользователем.

4. Обработка объекта response средства выбора

После того как пользователь закончит выбирать файлы, обратный вызов success получит объект response. Этот объект содержит свойства, в том числе свойство value, которое представляет собой коллекцию ресурсов Item с подмножеством свойств элемента.

При использовании действия save эта коллекция предоставляет метаданные элемента для вновь отправленного файла. Для действия query эта коллекция будет содержать метаданные для выбранной папки.

Пример отправки документа

{
  "value": [
    {
      "id": "123456",
      "name": "document1.docx",
      "size": 12340,
      "@content.downloadUrl": "https://contoso-my.sharepoint.com/download.aspx?guid=1231231231a",
      "webUrl": "https://cotoso-my.sharepoint.com/personal/user_contoso_com/documents/document1.docx",
      "thumbnails": [
        {
          "id": "0",
          "small": { "url": "https://sn3302files.onedrive.live.com/..." },
          "medium": { "url": "https://sn3302files.onedrive.live.com/..." },
          "large": { "url": "https://sn3302files.onedrive.live.com/..." }
        }
      ]
    }
  ]
}

Пример использования query для сохранения файла в папку

{
  "value": [
    {
      "id": "1234567!12",
      "name": "Project Vroom",
      "webUrl": "https://cotoso-my.sharepoint.com/personal/user_contoso_com/documents/project%20vroom",
      "folder": { "childCount": 4 }
    }
  ]
}

Расширенные сценарии сохранения

Параметр advanced объекта options имеет указанные ниже определенные свойства.

Имя параметра Описание
redirectUri По умолчанию средство выбора использует страницу, с которой оно запущено, в качестве URI перенаправления для аутентификации. Это может быть нежелательно в некоторых сценариях, поэтому вы можете настроить пользовательский URL-адрес, чтобы использовать его вместо этой страницы. Этот URL-адрес должен быть в том же корневом домене и для него должен использоваться тот же протокол, что и для страницы, на которой размещен пакет SDK средства выбора. Целевая страница должна ссылаться на пакет SDK средства выбора в OneDrive так же, как и вызывающая страница.

Использование пользовательского URI перенаправления

Если ваше приложение представляет собой большое клиентское приложение на JavaScript либо использует параметры строки запроса для поддержания состояния, может быть нежелательным использовать страницу, запускающую средство выбора файлов, в качестве URI перенаправления. Для этого необходимо, чтобы все ваше приложение было повторно загружено во всплывающем окне, что может снизить производительность системы. Вы можете указать альтернативный URI перенаправления с помощью объекта advanced.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  openInNewWindow: true,
  advanced: {
    redirectUri: "https://contoso.com/filePickerRedirect.htm"
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

Странице, на которую вы выполняете перенаправление, необходимо только загрузить сценарий SDK OneDrive:

<html>
<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>
</html>

Примечание. Вы можете указать пользовательский URI перенаправления, только если используете средство выбора файлов в виде всплывающего окна (значение параметра openInNewWindow равно true). При использовании встроенного интерфейса всегда применяется URI перенаправления, используемый по умолчанию.