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

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

  • Статья

Ниже представлено пошаговое руководство по интеграции пакета SDK средства выбора файлов в клиентское приложение на JavaScript.

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.open(...) укажите параметры, определяющие поведение средства выбора и то, каким образом средство выбора будет совершать обратные вызовы в ваш код, а также объект options.

<script type="text/javascript">
  function launchOneDrivePicker(){
    var odOptions = { /* ... specify the desired options ... */ };
    OneDrive.open(odOptions);
  }
</script>
<button onClick="launchOneDrivePicker()">Open from OneDrive</button>

Примечание: при открытии средства выбора OneDrive, откроется новое окно с вашей страницей, а SDK будет использовать строку запроса для перенаправления окна на средство выбора. Если SDK отсутствует на вашей странице при загрузке (если выполнена отложенная загрузка в ответ на действия пользователя, например), средство выбора не может открываться надлежащим образом. Может потребоваться использование redirectUri дополнительного параметра для перенаправления всплывающего окна на страницу, которая загружает SDK без вмешательства со стороны пользователя.

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

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

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

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "query",
  multiSelect: true,
  advanced: {},
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

Параметры

Имя параметра Описание
clientId Идентификатор приложения, созданный консолью регистрации приложения для вашей интеграции.
action Тип действия, выполняемого над выбранными файлами. Вы можете указать share, чтобы создать URL-адрес для общего доступа, download чтобы получить URL-адрес с небольшим сроком действия, по которому можно скачать содержимое файлов, или query, чтобы система возвращала идентификаторы, которые можно использовать с API Microsoft Graph или API OneDrive.
multiSelect По умолчанию используется значение false. Если указано это значение, пользователь может выбрать только один файл. Если указано значение true, пользователь может выбрать несколько файлов.
viewType Тип элемента, который можно выбрать. Значение по умолчанию — files. Можно указать параметр folders, чтобы ограничить выбор только папками, или указать параметр all, позволяющий выбрать одновременно файлы и папки.
accountSwitchEnabled По умолчанию задано значение true, которое приводит к отображению пользовательского интерфейса смены учетной записи на размещенной странице средства выбора файлов.
advanced Коллекция дополнительных свойств, с помощью которых можно более глубоко настроить поведение средства выбора. Эти свойства не нужны в большинстве сценариев. Дополнительные сведения см. в разделе Дополнительные параметры .
success Вызывается, если пользователь закончил выбирать файлы, и получает объект response, включающий коллекцию выбранных файлов. Это обязательный параметр, если параметр openInNewWindow имеет значение true.
cancel Вызывается, если пользователь нажимает кнопку отмены в средстве выбора файлов. Эта функция не получает никаких параметров.
error Вызывается при возникновении ошибки на сервере либо если у пользователя нет разрешения на получение ссылки на выбранный файл. Эта функция получает один параметр: объект error.

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

С помощью параметра action средства выбора вы можете указать тип URL-адреса, возвращаемого после того как пользователь выберет файл или папку. Разрешены указанные ниже значения.

Значение Описание
download Возвращает идентификаторы и имена файлов, а также URL-адреса с небольшим сроком действия для скачивания выбранных файлов.
share Возвращает URL-адрес общего доступа (только для чтения) к выбранным файлам. Вы можете передавать этот URL-адрес другим пользователям.
query Возвращает метаданные только для выбранных файлов. С помощью API вы можете выполнить соответствующие дополнительные действия над файлами.

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

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

{
  "value": [
    {
      "id": "123456",
      "name": "document1.docx",
      "size": 12340,
      "@microsoft.graph.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/..." }
        }
      ]
    }
  ],
  "accessToken": "ey...",
  "apiEndpoint": "https://graph.microsoft.com"
}

Свойства ответа

Имя свойства Тип Описание
value Массив элементов driveItems Метаданные о выбранных файлов.
webUrl URL-адрес Возвращается в сценариях выбора нескольких файлов в учетных записях OneDrive персональный.
accessToken string Маркер доступа, получаемый средством выбора файлов для вашего приложения. Он может понадобиться для создания дополнительных запросов к Microsoft Graph без необходимости использовать другой поток аутентификации.
apiEndpoint URL-адрес Конечная точка API, с которой можно использовать accessToken.

Дополнительные параметры

Средство выбора также поддерживает дополнительные расширенные сценарии. Это позволяет использовать средство выбора наряду с API OneDrive для выполнения расширенных сценариев.

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

Имя параметра Описание Сценарии
queryParameters Набор дополнительных параметров запроса, указанных в API OneDrive и определяющих способ возвращения элемента. Этот параметр обычно включает значение select или expand. Запрос файла или папки
createLinkParameters Изменение параметров, используемых для создания ссылки для действия предоставления общего доступа. Общий доступ к файлу
filter Вы можете использовать набор типов файлов для отображения файлов только определенных типов. Мы поддерживаем системный тип photo и folder, а также пользовательские типы с любыми расширениями, например .docx. Пример допустимого параметра фильтра: folder,.png. Здесь каждый фильтр отделяется символом ,. Отображение файлов
redirectUri По умолчанию средство выбора использует страницу, с которой оно запущено, в качестве URI перенаправления для аутентификации. Это может быть нежелательно в некоторых сценариях, поэтому вы можете настроить пользовательский URL-адрес, чтобы использовать его вместо этой страницы. Этот URL-адрес должен быть зарегистрирован в качестве URL-адреса перенаправления на портале регистрации вашего приложения. Целевая страница должна ссылаться на пакет SDK средства выбора в OneDrive так же, как и вызывающая страница. OAuth
endpointHint Указание конечной точки используется, когда пакет SDK перенаправляет приложение на правильную конечную точку OAuth на основании того, с какими конечными точками API OneDrive приложение предполагает взаимодействовать. Конечные точки API OneDrive включают OneDrive персональный, OneDrive для бизнеса или SharePoint Online. Параметр endpointHint может иметь значение api.onedrive.com для OneDrive персональный, URL-адрес OneDrive для бизнеса или URL-адрес библиотеки документов SharePoint, например https://contoso-my.sharepoint.com/personal/foo_contoso_onmicrosoft_com/ или https://contoso.sharepoint.com/shared%20documents/. Параметр не является обязательным, если приложение взаимодействует с API Microsoft Graph. OAuth
accessToken Чтобы пропустить поток OAuth и ускорить работу, можно передать маркер доступа, предоставляющий доступ к конечным точкам API OneDrive для OneDrive персональный, OneDrive для бизнеса или SharePoint Online. Параметр endpointHint является обязательным, если имеется маркер доступа. OAuth
loginHint Если пользователь ранее вошел в систему в вашем приложении, вы можете указать значение loginHint, с помощью которого можно использовать функцию единого входа. OAuth
isConsumerAccount Если пакет SDK взаимодействует с API Microsoft Graph, и указано значение параметра loginHint, для пакета SDK также необходимо, чтобы приложение сообщило, учетную запись какого типа применяет пользователь, вошедший в систему: учетную запись потребителя (учетная запись Майкрософт) или учетную запись организации. OAuth
scopes Пакет SDK будет автоматически запрашивать разрешение Files.Read.All для потоков открытия и разрешение Files.ReadWrite.All для потоков сохранения. Тем не менее если вы хотите запросить дополнительные разрешения, вы можете добавить дополнительные разрешения здесь. OAuth
navigation В пакете SDK 7.2 средства выбора появился новый пользовательский интерфейс, для которого можно настроить несколько конфигураций. Все конфигурации находятся в объекте navigation. Пользовательский интерфейс средства выбора

Примечание. На данный момент тип фильтра photo поддерживается только для учетных записей OneDrive персональный.

Совместное использование средства выбора и API

Вы можете использовать значение действияquery вместе с параметром queryParameters объекта advanced, чтобы возвращать пользовательский набор свойств для выбранного объекта из API. Например, чтобы включать сведения о фотографии (если они доступны) при выборе файла:

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "query",
  multiSelect: false,
  advanced: {
    queryParameters: "select=id,name,size,file,folder,photo,@microsoft.graph.downloadUrl",
    filter: "folder,.png" /* display folder and files with extension '.png' only */
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

Данный код указывает пакету SDK средства выбора, что в ответе необходимо возвратить свойства id, name, size, file, folder и photo.

По умолчанию, когда параметр action имеет значение share, средство выбора файлов в OneDrive возвращает URL-адрес для общего доступа только для просмотра. Тем не менее вы можете использовать свойство createLinkParameters, чтобы изменить параметры, передаваемые в действие createLink.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "share",
  multiSelect: false,
  advanced: {
    createLinkParameters: { type: "edit", scope: "organization" }
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

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

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

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

Использование альтернативных конечных точек API

API Microsoft Graph предоставляет унифицированный доступ к файлам, хранящимся в OneDrive персональный, OneDrive для бизнеса и SharePoint Online. Тем не менее в небольшом количестве сценариев может потребоваться использовать определенный URL-адрес сайта SharePoint вместо Microsoft Graph.

В этом случае приложение может указать конечную точку API OneDrive для сайта SharePoint, а не конечную точку API Microsoft Graph. Чтобы получить маркер доступа, пакет SDK средства выбора OneDrive выполнит перенаправление на правильную конечную точку OAuth. Ниже приведено сопоставление конечных точек API OneDrive и центра OAuth.

Конечная точка API Конечная точка OAuth endpointHint
https://graph.microsoft.com/v1.0/ https://login.microsoftonline.com/common/oauth2/v2.0/authorize Недоступно
https://api.onedrive.com/v1.0/ https://login.live.com/oauth20_authorize.srf https://api.onedrive.com
https://contoso-my.sharepoint.com/personal/ryan_contoso_com/ https://login.microsoftonline.com/common/oauth2/authorize https://contoso-my.sharepoint.com/personal/ryan_contoso_com/

Перенаправление в конечную точку OAuth MSA

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "query",
  advanced: {
    endpointHint: "api.onedrive.com",
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

Перенаправление непосредственно в библиотеку документов, при этом приложение управляет потоком OAuth в другом месте.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  advanced: {
    endpointHint: "https://contoso.sharepoint.com/shared%20documents/",
    accessToken "INSERT-ACCESS-TOKEN-HERE"
  },
  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>

Настройка возможностей

Средство выбора файлов дает пользователям возможность выбирать файлы в Office 365, в том числе в OneDrive и в библиотеках документов SharePoint, но вам может потребоваться ограничить перечень источников, в которых можно открывать файлы. Вы можете использовать указанные ниже свойства, чтобы ограничить перечень возможностей и разрешить только выбранные вами возможности.

Имя параметра Описание
disable Если для этого параметра задано значение, панель навигации не отображается.
entryLocation Настройка библиотеки документов, отображаемой в средстве выбора в OneDrive.
sourceTypes Источники файлов, которые пользователь может выбрать на панели навигации.

Приложение может указать значение для параметра sourceTypes, например OneDrive, Recent, Sites, или несколько источников в массиве [`OneDrive`, `Recent`]. Кроме того, приложение может указать пользовательское расположение записи вместо расположения, используемого по умолчанию, задав объект entryLocation. Пользовательские расположения записей могут быть расположены только в библиотеке документов SharePoint. Расположение записи по умолчанию — OneDrive для бизнеса пользователя.

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  advanced: {
    navigation: {
      entryLocation: {
        sharePoint: {
          sitePath: "THE-SITE-PATH",
          listPath: "THE-LIST-PATH",
          itemPath: "THE-ITEM-PATH"
        }
      },
      sourceTypes: "Sites" /* or an array like ["OneDrive", "Sites"] */
    }
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }