Обращение к ресурсам объекта drive в OneDrive

Статья
04/08/2023

API OneDrive позволяет использовать один URL-адрес для обращения к двум аспектам ресурса:

ресурс driveItem;
свойство, аспект или связь элемента.

Аспект Item представляет элемент ресурса, например метаданные изображения, метаданные папки и т. д.

В этом примере канонический 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— представляет двоичный поток, используемый по умолчанию, для файла. Вы также можете адресовать другие свойства или связи для элемента.

Обращение к элементам с использованием идентификаторов

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
                     = "/" / "\" / "*" / "<" / ">" / "?" / ":" / "|" / "#" / "%"

Примечание. Имена папок не должны заканчиваться точкой (.).

Примечание. Имена файлов и папок в OneDrive для бизнеса не должны начинаться с тильды (~). Дополнительные сведения см. в статье об ограничениях при работе с OneDrive для бизнеса.

Символы, используемые в пути URI

При создании сегмента пути URL-адреса для API OneDrive в именах путей, основанных на 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://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

Классы .NET для HttpUtility и Uri включают различные методы кодирования URL-адресов. Тем не менее ни один из этих методов не может правильно кодировать все зарезервированные символы для компонента пути URL-адреса (включая HttpUtility.UrlPathEncode).

Вместо этих методов для создания правильного URL-адреса используйте UriBuilder.

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 для правильного кодирования компонента пути URL-адреса используйте метод stringByAddingPercentEncodingWithAllowedCharacters и [NSCharacterSet URLPathAllowedCharacterSet].

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

Для создания правильно закодированного URL-адреса используйте класс Uri.Builder.

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`

Обращение к ресурсам объекта drive в OneDrive

Обращение к элементам с использованием идентификаторов

Обращение к элементам с использованием пути

Примеры

Кодировка символов пути

Символы, зарезервированные в OneDrive

Символы, используемые в пути URI

Кодирование символов

Распространенные ошибки при кодировании URL-адресов

.NET, C-Sharp и Visual Basic

Objective-C и iOS

Android

JavaScript

Примеры

Дополнительные ресурсы