寻址 OneDrive 上驱动器中的资源

项目
04/08/2023

使用 OneDrive API，可以通过一个 URL 寻址资源的两个方面：

driveItem 资源
项的属性、Facet 或关系

项 Facet 表示资源元素，如图像元数据、文件夹元数据等。

在此示例中，文件的规范 URL 如下所示。

https://graph.microsoft.com/v1.0/me/drive/root:/Documents/MyFile.xlsx:/content

此示例 URL 由以下部分组成：

https://graph.microsoft.com/v1.0 - 所用 Microsoft Graph 版本。
/me - 在寻址的顶级 Microsoft Graph 资源（在此示例中，为当前用户）。
/drive - 旧资源的默认驱动器（在此示例中，为用户的 OneDrive）。
/root - 驱动器的根文件夹。
:/Documents/MyFile.xlsx: - /Documents/MyFile.xlsx 两边的 : : 表示切换到基于路径的寻址语法。将两个冒号之间的所有内容都视为相对路径前面的项（在此示例中为 root）的路径。
/content - 表示文件的默认二进制流。还可以寻址项的其他属性或关系。

基于 ID 的寻址

OneDrive 支持对项进行基于 ID 的寻址。项在创建时即分配有唯一标识符，此 ID 保持不变，无论用户对项执行的操作如何。重命名或移动项不会更改项 ID。

借助基于 ID 的寻址，可以非常方便地跟踪可能被用户移到 OneDrive 中其他位置上的项。只要有项 ID 且项存在，就可以找到项。

基于路径的寻址

OneDrive 还支持基于路径的寻址。这样一来，可以使用易记的 URL 语法，根据 OneDrive 中可见项的层次结构寻址项。如果知道项所处的层次结构，可以直接寻址此项，而无需为了发现层次结构的每一层级而花费时间进行重复调用。

然而，由于基于路径的寻址是以项名称为依据，因此重命名项或将项移到新位置将导致项路径发生变化。

可以相对于 OneDrive 中的任意项使用基于路径的寻址，这样可以完成一些非常实用的方案。例如，使用共享文件夹时，可以使用相对于共享文件夹项 ID 的基于路径的 URL，按路径寻址共享文件夹中的某项。

示例

下面的示例展示了可用于访问数据的不同 URL 格式。所有这些 URL 在逻辑上是等效的，都返回 MyFile.xlsx 的内容。

URL 示例	说明
`/drive/root:/Documents/MyFile.xlsx:/content`	由相对于驱动器根目录的路径指定。
`/drive/special/documents:/MyFile.xlsx:/content`	由 `documents` 特殊文件夹中的文件名指定。
`/drive/items/0123456789AB/content`	由 item-id 指定。
`/drives/AB0987654321/items/0123456789AB/content`	由 drive-id 和 item-id 指定。

路径编码

OneDrive 支持使用用户 OneDrive 中项的路径寻址文件和文件夹。不过，由于路径中的用户指定内容可能包含 URL 不安全字符，因此应确保正确编码所有路径段。

Microsoft Graph 要求 URL 符合 RFC 3986。下面总结了如何正确编码 Microsoft Graph 路径。

OneDrive 保留字符

以下为 OneDrive 保留字符，不得用于 OneDrive 文件夹名称和文件名。

  onedrive-reserved  = "/" / "\" / "*" / "<" / ">" / "?" / ":" / "|"
  onedrive-business-reserved
                     = "/" / "\" / "*" / "<" / ">" / "?" / ":" / "|" / "#" / "%"

注意：文件夹名称不得以句点 (.) 结尾。

注意：OneDrive for Business 文件名或文件夹名称不得以波形符 (~) 开头。有关详细信息，请参阅 OneDrive for Business 的约束和限制。

URI 路径字符

构造 OneDrive API 的 URL 路径段时，根据 URI RFC，可以对路径名称使用下列字符。

  pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
  pct-encoded = "%" HEXDIG HEXDIG
  unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
  sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="

必须对 pchar 组中不包含的项名称字符（如 # 和（空格））进行百分比编码。

字符编码

Microsoft Graph 使用标准百分比编码，即先对 URL 无效字符进行百分比编码，然后使用 UTF-8 字符代码对字符进行编码。例如：

" " ->%20
"#" ->%23

常见 URL 编码错误

不能在一次调用中对整个 URL 进行编码，因为 URL 每个段的编码规则都不同。如果未经正确编码，将很难通过未编码的 URL 明确判断哪些段包含哪些内容。因此，必须在生成 URL 字符串时对 URL 路径进行编码。

例如，不用编写以下代码：

string url = url_encode("https://api.onedrive.com/v1.0/drive/root:/" + path + ":/children")

而是编写以下代码：

string url = "https://api.onedrive.com/v1.0/drive/root:/" + url_path_encode(path) + ":/children")

不过，并不是所有 URL 编码库都符合标准 URL 路径编码的全部要求。

.NET/C-Sharp/Visual Basic

HttpUtility 和 Uri 的 .NET 类包括各种 URL 编码方法。不过，这些方法（包括 HttpUtility.UrlPathEncode）都无法正确编码 URL 路径组成部分的所有保留字符。

应使用 UriBuilder 构造经过正确转义的 URL，而不是使用这些方法。

UriBuilder builder = new UriBuilder("https://api.onedrive.com");
builder.Path = "/v1.0/drive/root:/Documents/My Files/#nine.docx";
Uri url = builder.Uri;

Objective-C/iOS

对于 Objective-C、iOS 和 Mac OS X 开发，使用 stringByAddingPercentEncodingWithAllowedCharacters 方法和 [NSCharacterSet URLPathAllowedCharacterSet] 对 URL 路径组成部分进行正确编码。

NSString *root = @"https://api.onedrive.com/v1.0/drive/root:/";
NSString *path = @"Documents/My Files/#nine.docx";
NSString *encPath = [path stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLPathAllowedCharacterSet]];
NSURL *url = [[NSURL alloc] initWithString:[root stringByAppendingString:encPath]];

Android

使用 Uri.Builder 类构造经过正确编码的 URL。

Uri.Builder builder = new Uri.Builder();
builder.
  scheme("https").
  authority("api.onedrive.com").
  appendPath("v1.0").
  appendPath("drive").
  appendPath("root:").
  appendPath("Documents").
  appendPath("My Files").
  appendPath("#nine.docx");
String url = builder.build().toString();

JavaScript

使用 JavaScript 中的 escape() 正确编码路径组成部分。

var root = "https://api.onedrive.com/v1.0/drive/root:";
var path = "/Documents/My Files/#nine.docx";
var url = root + escape(path);

示例

下面的示例展示了具有以下文件夹层次结构的 OneDrive 用户 (Ryan)：

OneDrive
	\Ryan's Files
		\doc (1).docx
    \estimate%s.docx
	\Break#Out
		\saved_game[1].bin

若要寻址 Ryan 的每个文件，请使用百分比编码，如下所示：

路径	已编码的 URL 路径
`\Ryan's Files`	`/root:/Ryan's%20Files`
`\...\doc (1).docx`	`/root:/Ryan's%20Files/doc%20(1).docx`
`\...\estimate%.docx`	`/root:/Ryan's%20Files/estimate%25s.docx`
`\Break#Out`	`/root:/Break%23Out`
`\...\saved_game[1].bin`	`/root:/Break%23Out/saved_game[1].bin`

通过