适用于 Android 的 OneDrive 选取器
文件选取器是将 Android 应用与 OneDrive 和 OneDrive for Business 集成的最快捷方式。 它提供了一组 Java API,应用可以使用这些 API 在用户的 OneDrive 中浏览、选取、打开和保存文件。 打开 OneDrive 中的文件时,还可以获取可共享文件链接(非常适合发送给亲朋好友和同事)以及图像和视频文件的缩略图,免去了自行生成的麻烦。
本指南将介绍如何让应用在 OneDrive 上快速打开文件,并将文件保存到 OneDrive。 也可以沿用文件打开选取器示例应用和保存器示例应用。

设置
使用源代码进行编译
适用于 Android 的文件选取器已作为 GitHub 上的开放源代码公开,同时包含文件打开和保存功能。 可以直接下载最新版本,也可以克隆存储库:
若要了解如何将环境配置为支持示例应用或文件选取器 SDK,请参阅配置 Android 环境。
通过 Gradle 安装 AAR
repositories {
jcenter()
}
dependencies {
compile ('com.microsoft.onedrivesdk:onedrive-picker-android:v2.0')
}
获取应用 ID
单击此处注册应用,以获取启动文件选取器所需的应用 ID(客户端 ID)。
生成库
Android Studio
- 选择“导入项目...”或“导入模块...”,以导入到现有项目中。
- 转到 SDK 的保存位置,然后选择根 onedrive-picker-android
- 如果尚未安装,请按照提示操作或转到“Android SDK 管理器”,以安装 Android 4.4.2 (API 19) 及相关生成工具。
Eclipse
- 在 Eclipse 中,依次转到“文件”→“导入”→“常规”→“将现有项目导入工作区”。
- 单击“浏览...”,选择 SDK 保存位置“onedrive-picker-android”作为根目录。请确保至少已选中“OneDriveSDK”。
- 如果尚未安装,请在“Android SDK 管理器”中安装 Android 4.4.2 (API 19)。
- 右键单击项目并选择“属性”,然后转到左侧边栏中的“Android”。
- 单击“库”中的“添加...”,然后选择“OneDriveSDK”,将其与项目相关联。
打开文件
用户需要能够使用应用开始打开 OneDrive 中的文件。 以下示例设置了通过 onClick() 启动文件打开选取器的单击处理程序。 在此示例中,应用使用 LinkType.WebViewLink 请求获取仅供查看共享链接类型。
请务必将 APP_ID 替换成应用标识符
import android.view.View.OnClickListener;
import com.microsoft.onedrivesdk.picker.*;
// Within the activity's class definition
private IPicker mPicker;
private String ONEDRIVE_APP_ID = "APP_ID"; // Get app id here: https://account.live.com/developers/applications
// The onClickListener that will start the OneDrive picker
private final OnClickListener mStartPickingListener = new OnClickListener() {
@Override
public void onClick(final View v) {
mPicker = Picker.createPicker(ONEDRIVE_APP_ID);
mPicker.startPicking((Activity)v.getContext(), LinkType.WebViewLink);
}
};
在 onClick() 方法得到调用后,文件选取器会针对用户请求获取的链接类型进行创建和配置。 然后,调用 startPicking() 方法来启动文件选取器。 如果在调用 startPicking() 时用户尚未安装 OneDrive 应用,则提示用户下载此应用,并将用户转到应用商店。
链接类型
可以将文件打开选取器配置为返回选定文件的以下格式之一 URL:
LinkType.DownloadLink- 返回可提供对文件内容的 1 小时直接访问权限的 URL。可以使用此 URL 将文件下载到应用中。LinkType.WebViewLink- 将创建可提供文件 Web 预览的共享链接。在用户通过 OneDrive 删除共享链接前,此链接一直有效。共享链接不适用于 OneDrive for Business 文件。
捕获结果
在用户完成文件打开操作或在文件打开选取器中取消操作后,将调用 onActivityResult() 方法来处理文件选取器结果。可以使用此方法捕获结果,并访问用户选取的文件。
protected void onActivityResult(final int requestCode, final int resultCode, final Intent data) {
// Get the results from the picker
IPickerResult result = mPicker.getPickerResult(requestCode, resultCode, data);
// Handle the case if nothing was picked
if (result != null) {
// Do something with the picked file
Log.d("main", "Link to file '" + result.getName() + ": " + result.getLink());
return;
}
// Handle non-OneDrive picker request
super.onActivityResult(requestCode, resultCode, data);
}
如果用户已取消选取文件,result 对象将为 null。
文件选取器 result 对象
除了文件的文件名和链接以外,还可以访问 IPickerResult 对象中的其他几个属性,更详细地了解选定文件:
public static class IPickerResult {
// Name of the file with extension
public String getName();
// Type of link generated
public LinkType getLinkType();
// URI for the file, which varies based on the value of getLinkType()
public Uri getLink();
// Size of the file, in bytes
public int getSize();
// Set of thumbnail links for various sizes: "small", "medium", and "large"
public Map<String, Uri> getThumnailLinks();
}
运行文件打开选取器示例应用,了解此任务的所有实际操作。
保存文件
与文件打开功能相似,用户应能够使用应用将文件保存到 OneDrive。 在以下代码示例中,单击处理程序用于通过 onClick() 启动文件保存器。 应用设备上必须有要传递给文件保存器的文件的文件名和 URI。 以下示例代码在应用本地文件夹中创建占位符文件。例如,可将此文件命名为 file.txt。
请务必将 APP_ID 替换成应用标识符
import android.view.View.OnClickListener;
import com.microsoft.onedrivesdk.saver.*
// Within the activity's class definition
private ISaver mSaver;
private String ONEDRIVE_APP_ID = "APP_ID"; // Get app id here: https://account.live.com/developers/applications
// The onClickListener that will start the OneDrive picker
private final OnClickListener mStartPickingListener = new OnClickListener() {
@Override
public void onClick(final View v) {
// create example file to save to OneDrive
final String filename = "file.txt";
final File f = new File(context.getFilesDir(), filename);
// create and launch the saver
mSaver = Saver.createSaver(ONEDRIVE_APP_ID);
mSaver.startSaving((Activity)v.getContext(), filename, Uri.fromFile(f));
}
};
调用 onClick() 方法后,将创建保存器,然后调用 startSaving() 方法。这将启动 OneDrive 文件保存器,以便用户可以选取将文件上传到的文件夹。如果在调用 startSaving() 时用户尚未安装 OneDrive 应用,则提示用户从应用商店下载此应用。
目前,文件保存器支持 content:// 和 file:// 文件 URI 方案。如果使用其他 URI 方案,文件保存器会返回 NoFileSpecified 错误。请参阅下文,详细了解文件保存器响应。
文件保存器结果
在用户保存完文件或无法保存文件时,将调用 onActivityResult() 方法来处理文件保存器结果。可以使用此方法检查文件是否已保存。如果未保存,可以捕获异常并处理错误。
protected void onActivityResult(final int requestCode, final int resultCode, final Intent data) {
// check that the file was successfully saved to OneDrive
try {
mSaver.handleSave(requestCode, resultCode, data);
} catch (final SaverException e) {
// Log error information
Log.e("OneDriveSaver". e.getErrorType().toString()); // Provides one of the SaverError enum
Log.d("OneDriveSaver", e.getDebugErrorInfo()); // Detailed debug error message
}
}
getDebugErrorInfo() 提供的错误消息主要用于开发和调试目的,可能会随时发生变更。处理错误时,可以使用 getErrorType() 确定导致错误出现的常见原因。
文件保存器错误类型
无法完成文件保存并引发异常时,文件保存器通过 getErrorType() 提供 SaverError,以从一组可能错误类型中指明一种错误。
public enum SaverError {
// The error type was not known
Unknown,
// The saver was cancelled by the user
Cancelled,
// The OneDrive account did not have enough quota available to save the file
OutOfQuota,
// The file could not be saved onto OneDrive because it contained
// unsupported characters
InvalidFileName,
// No network connectivity was available when attempting to save the file
NoNetworkConnectivity,
// The Uri to the file could not be accessed
CouldNotAccessFile,
// No file was specified to be saved, or the file URI scheme was not supported,
// content:// and file:// are currently supported
NoFileSpecified
}
运行文件保存器示例应用,了解此任务的所有实际操作。
支持的 Android 版本
Android API 版本 14 及更高版本的运行时支持 OneDrive 文件选取器库。 必须安装 Android API 版本 19 或更高版本,才能生成文件选取器库。
必须安装 OneDrive 应用,才能运行文件选取器。如果未安装 OneDrive 应用,将在调用 startPicking() 或 startSaving() 方法时提示用户下载此应用。