使用 OneDrive 文件选取器 JavaScript SDK v7.2 打开文件

项目
04/08/2023

下面逐步展示了如何将文件选取器 SDK 集成到客户端 JavaScript 应用中。

1.注册应用

若要使用 OneDrive 选取器，需要通过“Azure 应用注册”页注册应用程序并接收应用程序 ID。还需要使用选取器为 Web 应用程序添加有效的重定向 URI。这可以是托管文件选取器 SDK 的网页，也可以是定义的自定义 URL。有关详细信息，请参阅设置。

2.添加对 SDK 的引用

将 OneDrive JavaScript SDK 嵌入网页。

<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	应用注册控制台为了实现集成而生成的应用 ID。
action	选择文件后要执行的操作类型。可以指定 `share` 生成可共享 URL，可以指定 `download` 获取用于下载文件内容的短期 URL，也可以指定 `query` 返回可与 Microsoft Graph API 或 OneDrive API 结合使用的标识符。
multiSelect	默认值可以是 false，要求用户只选取一个文件；也可以是 true，允许用户选取多个文件。
viewType	可以选择的项目的类型。默认值为 `files`。可以指定 `folders`仅选择文件夹，或指定 `all` 支持选择文件和文件夹。
accountSwitchEnabled	默认值是 `true`，它在托管文件选取器页上呈现“切换账户”用户界面。
advanced	一组可进一步自定义文件选取器行为，但并不为大多数方案所需的其他属性。有关详细信息，请参阅高级选项。
success	在用户选取完文件并获得包含一组选定文件的 response 对象时调用。如果 openInNewWindow 为 `true`，此为必需参数。
cancel	在用户取消文件选取器时调用。此函数无需使用任何参数。
error	在服务器出错或用户无权获取选定文件的链接时调用。此函数需要使用一个参数，即 error 对象。

操作类型

可以使用文件选取器的 action 参数，指定在用户选取文件或文件夹后应返回的 URL 的类型。可取值如下：

值	说明
`download`	返回选定文件的 ID、名称和短期下载 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	Array of driveItems	与选定文件有关的元数据。
webUrl	Url	针对多重选择方案从 OneDrive 个人版返回的 URL。
accessToken	string	应用的文件选取器获取的访问令牌。这可用于向 Microsoft Graph 发出其他请求，而无需重新生成身份验证流。
apiEndpoint	Url	可与 accessToken 结合使用的 API 终结点。

高级选项

文件选取器还支持其他高级方案。这样一来，可以将文件选取器与 OneDrive API 结合使用，从而完成高级方案。

options 对象中的 advanced 参数包含以下定义属性：

参数名称	说明	方案
queryParameters	OneDrive API 指定的一组其他查询参数，以定义项返回方式。这通常包括 select 和/或 expand 值。	查询文件或文件夹
createLinkParameters	更改用于生成 share 操作链接的参数。	共享文件
filter	可以应用于仅显示特定类型的一组文件类型。支持系统类型“photo”和“folder”，以及使用“docx”等任意扩展名的自定义类型。一种适用的 filter 设置是“folder,.png”，其中每个筛选器用 `,` 分隔。	显示文件
redirectUri	默认情况下，文件选取器将启动网页用作重定向 URI，以供进行身份验证时使用。这可能并不是对所有方案都适合，因此可以设置并改用自定义 URL。必须在应用注册门户上将此 URL 注册为重定向 URL。目标网页必须按照网页调用方式，引用 OneDrive 文件选取器 SDK。	OAuth
endpointHint	使用终结点提示，SDK 可以根据应用要与之通信的 OneDrive API 终结点，将应用重定向到正确的 OAuth 终结点。 OneDrive API 终结点包括 OneDrive 个人版、OneDrive for Business 或 SharePoint Online。 `endpointHint` 的值可以是 OneDrive 个人版的 `api.onedrive.com`、OneDrive for Business URL 或 SharePoint 文档库 URL（例如， `https://contoso-my.sharepoint.com/personal/foo_contoso_onmicrosoft_com/` 或 `https://contoso.sharepoint.com/shared%20documents/`）。如果应用要与 Microsoft Graph API 通信，此为可选参数。	OAuth
accessToken	可以传递有权访问 OneDrive 个人版、OneDrive for Business 或 SharePoint Online 的 OneDrive API 终结点的 accessToken，以跳过 OAuth 流，从而加快用户操作速度。如果 accessToken 已存在，则需要 `endpointHint`	OAuth
loginHint	如果用户之前登录过应用，可以提供用于启用单一登录的 loginHint 值。	OAuth
isConsumerAccount	如果与 Microsoft Graph API 通信且已指定 `loginHint`，SDK 还要求应用区分登录用户是使用者帐户（亦称为“Microsoft 帐户”），还是业务往来联系人。	OAuth
scopes	SDK 将自动请求获取文件打开流的 `Files.Read.All` 作用域，以及文件保存流的 `Files.ReadWrite.All` 作用域。不过，若要请求获取其他权限，可以在此处添加其他作用域。	OAuth
navigation	在文件选取器 SDK 7.2 中，我们引入了新的文件选取器 UI，可以在其中设置多个配置。所有配置均位于 `navigation` 对象下。	文件选取器 UI

注意：目前，仅 OneDrive 个人版帐户支持“photo”筛选器类型。

结合使用文件选取器和 API

可以使用 action 值 query，同时设置 advanced 对象的 queryParameters，从而通过 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 在 response 中选择 id、name、size、file、folder 和 photo 属性。

返回可共享的读/写公司链接

默认情况下，如果将 action 设置为 share，OneDrive 文件选取器会返回仅供查看的共享 URL。不过，可以使用 createLinkParameters 属性，更改传递给 createLink action 的参数。

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 对象来指定替代的重定向 URI。

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 终结点

Microsoft Graph API 提供了对 OneDrive 个人版、OneDrive for Business 和 SharePoint Online 上存储的文件的统一访问权限。不过，在一些受限制的方案中，可能需要使用特定的 SharePoint 网站 URL，而非 Microsoft Graph。

在这种情况下，应用可以指定 SharePoint 网站的 OneDrive API 终结点，而非 Microsoft Graph API 终结点。 OneDrive 文件选取器 SDK 会重定向到正确的 OAuth 终结点来获取访问令牌。 OneDrive API 终结点和 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/

重定向到 MSA OAuth 终结点

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

重定向到的网页只需加载 OneDrive SDK 脚本：

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

自定义功能

虽然文件选取器允许用户选取 Office 365（包括 OneDrive 和 SharePoint 文档库）中的文件，但可能需要限制可以从中打开文件的源。可以使用下列属性，限制为仅启用所需的功能：

参数名称	说明
disable	设置此值后，将不显示导航窗格。
entryLocation	设置在 OneDrive 文件选取器 UI 中呈现的文档库。
sourceTypes	用户可以在导航窗格上选择的文件源。

应用可以指定、OneDrive、Recent 等 Sites，也可以在数组 [`OneDrive`, `Recent`] 中指定多个源。应用还可以指定 entryLocation 对象，从而指定自定义入口位置，而非默认入口位置。自定义入口位置只能是 SharePoint 文档库。默认入口位置是用户的 OneDrive for Business。

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

通过