Обращение к ресурсам на диске в OneDrive
Узнайте о доступе к элементам на диске в OneDrive с помощью адресов на основе идентификаторов и путей, а также о правильном кодировании путей для Microsoft Graph.
Обращение к элементам с использованием идентификаторов
OneDrive поддерживает обращение к элементам с использованием идентификаторов. При создании элементов им назначаются уникальные идентификаторы. Эти идентификаторы остаются неизменными при выполнении действий над элементами. При переименовании или перемещении элемента его идентификатор не изменяется.
Обращение к элементам с использованием идентификаторов — удобный способ отслеживания элементов, которые пользователь может перемещать в различные расположения в OneDrive. Если у вас есть идентификатор существующего элемента, вы сможете найти этот элемент.
Обращение к элементам с использованием пути
OneDrive также поддерживает обращение к элементам с использованием пути. Такой способ позволяет использовать понятный синтаксис URL-адресов для обращения к элементам относительно иерархии элементов, видимой в OneDrive. Если вы знаете иерархию, ведущую к элементу, вы можете напрямую обратиться к нему, не тратя время на выполнение повторяющихся вызовов для обнаружения каждого уровня иерархии.
Так как при обращении к элементу с использованием пути применяется имя элемента, при переименовании элемента или перемещении его в другое расположение путь к элементу изменится.
Вы можете использовать адресацию на основе путей относительно любого элемента в OneDrive. Например, при работе с общими папками вы можете использовать URL-адрес на основе пути, относительный для идентификатора элемента общей папки, для обращения к каким-либо объектам в общей папке с использованием пути.
Примеры
В следующих примерах показаны различные форматы URL-адресов для доступа к данным. Все эти URL-адреса логически эквивалентны и возвращают содержимое файла MyFile.xlsx.
Пример URL-адреса | Описание |
---|---|
/drive/root:/Documents/MyFile.xlsx:/content |
Указан с использованием пути, относительного для корня диска. |
/drive/special/documents:/MyFile.xlsx:/content |
Указан с использованием имени файла в специальной папке documents . |
/drive/items/0123456789AB/content |
Указан с использованием идентификатора элемента. |
/drives/AB0987654321/items/0123456789AB/content |
Указан с использованием идентификатора диска и идентификатора элемента. |
Кодировка символов пути
OneDrive поддерживает обращение к файлам и папкам с использованием пути к элементу в OneDrive пользователя. Тем не менее, поскольку путь содержит содержимое, указанное пользователем, которое потенциально может содержать символы, которые не являются безопасными для URL-адреса, следует обеспечить правильное кодирование любых сегментов пути.
При работе с Microsoft Graph предполагается, что URL-адреса соответствуют требованиям документа RFC 3986. Ниже кратко описано, как правильно кодировать пути для Microsoft Graph.
Символы, зарезервированные в OneDrive
Указанные ниже символы зарезервированы в OneDrive. Их не следует использовать в именах папок и файлов в OneDrive.
onedrive-reserved = "/" / "\" / "*" / "<" / ">" / "?" / ":" / "|"
onedrive-business-reserved
= "/" / "\" / "*" / "<" / ">" / "?" / ":" / "|" / "#" / "%"
Примечание.
- Имена папок не должны оканчиваться точкой (
.
). - Имена файлов и папок не должны начинаться с тильды (~).
Дополнительные сведения см. в разделе Ограничения при синхронизации библиотек SharePoint с компьютером с помощью OneDrive для работы или учебы.
Символы, используемые в пути URI
При создании сегмента пути URL-адреса для API Microsoft Graph в именах путей, основанных на RFC URI, можно использовать указанные ниже символы.
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://graph.microsoft.com/v1.0/me/drive/root:/" + path + ":/children")
Напишите это:
string url = "https://graph.microsoft.com/v1.0/me/drive/root:/" + url_path_encode(path) + ":/children")
Не во всех библиотеках кодирования URL-адресов соблюдаются все требования стандартного кодирования путей URL-адресов.
.NET, C-Sharp и Visual Basic
Классы .NET для HttpUtility
и Uri
включают различные методы кодирования URL-адресов. Тем не менее ни один из этих методов не может правильно кодировать все зарезервированные символы для компонента пути URL-адреса (включая HttpUtility.UrlPathEncode
).
Вместо этих методов для создания правильного URL-адреса используйте UriBuilder
.
UriBuilder builder = new UriBuilder("https://graph.microsoft.com");
builder.Path = "/v1.0/me/drive/root:/Documents/My Files/#nine.docx";
Uri url = builder.Uri;
Objective-C и iOS
При разработке для Objective-C, iOS и Mac OS X для правильного кодирования компонента пути URL-адреса используйте метод stringByAddingPercentEncodingWithAllowedCharacters
и [NSCharacterSet URLPathAllowedCharacterSet]
.
NSString *root = @"https://graph.microsoft.com/v1.0/me/drive/root:/";
NSString *path = @"Documents/My Files/#nine.docx";
NSString *encPath = [path stringByAddingPercentEncodingWithAllowedCharacters:[NSCharacterSet URLPathAllowedCharacterSet]];
NSURL *url = [[NSURL alloc] initWithString:[root stringByAppendingString:encPath]];
Android
Для создания правильно закодированного URL-адреса используйте класс Uri.Builder
.
Uri.Builder builder = new Uri.Builder();
builder.
scheme("https").
authority("graph.microsoft.com").
appendPath("v1.0").
appendPath("me").
appendPath("drive").
appendPath("root:").
appendPath("Documents").
appendPath("My Files").
appendPath("#nine.docx");
String url = builder.build().toString();
JavaScript
Для правильного кодирования компонента пути в JavaScript используйте escape()
.
var root = "https://graph.microsoft.com/v1.0/me/drive/root:";
var path = "/Documents/My Files/#nine.docx";
var url = root + escape(path);
Примеры
Вот пример пользователя OneDrive (Adele) с указанной ниже иерархией папок.
OneDrive
\Adele's Files
\doc (1).docx
\estimate%s.docx
\Break#Out
\saved_game[1].bin
Для обращения к любым файлам пользователя Adele необходимо применять кодирование с использованием знака процента, как показано ниже.
Путь | Закодированный URL-адрес для пути |
---|---|
\Adele's Files |
/root:/Adele's%20Files |
\...\doc (1).docx |
/root:/Adele's%20Files/doc%20(1).docx |
\...\estimate%.docx |
/root:/Adele's%20Files/estimate%25s.docx |
\Break#Out |
/root:/Break%23Out |
\...\saved_game[1].bin |
/root:/Break%23Out/saved_game[1].bin |