Recursos de endereço em uma unidade no OneDrive
Saiba como acessar itens em uma unidade no OneDrive com endereçamento baseado em ID e em caminho e como codificar caminhos corretamente para o Microsoft Graph.
O OneDrive dá suporte ao endereçamento de itens baseado em ID. Os itens recebem um identificador exclusivo quando são criados, e a ID persiste nas ações que um usuário executa no item. Renomear ou mover o item não mudará a ID do item.
O endereçamento baseado em ID é uma maneira útil de acompanhar itens que podem ser movidos pelo usuário para locais diferentes no OneDrive. Desde que você tenha a ID do item e o item exista, será possível encontrá-lo.
O OneDrive também dá suporte ao endereçamento com base no caminho. Isso permite que você use uma sintaxe da URL amigável para endereçar itens em relação à hierarquia de itens visíveis no OneDrive. Se souber a hierarquia de um item, você poderá endereçar diretamente esse item, sem perder tempo fazendo chamadas repetidas para descobrir cada nível da hierarquia.
No entanto, como o endereçamento com base no caminho se baseia no nome do item, renomear ou mover o item para um novo local fará com que o caminho dele seja alterado.
Você pode usar o endereçamento baseado em caminho em relação a qualquer item no OneDrive. Por exemplo, ao trabalhar com pastas compartilhadas, você pode usar uma URL com base em caminho relativa à ID do item da pasta compartilhada para lidar com algo na pasta compartilhada pelo caminho.
Os exemplos a seguir mostram os diferentes formatos de URL disponíveis para acessar dados. Todas essas URLs são logicamente equivalentes e retornam o conteúdo de MyFile.xlsx.
Exemplo de URL | Descrição |
---|---|
/drive/root:/Documents/MyFile.xlsx:/content |
Especificado pelo caminho relativo à raiz de uma unidade. |
/drive/special/documents:/MyFile.xlsx:/content |
Especificado por filename na pasta especial documents . |
/drive/items/0123456789AB/content |
Especificado por item-id. |
/drives/AB0987654321/items/0123456789AB/content |
Especificado por drive-id e item-id. |
O OneDrive dá suporte ao endereçamento de pastas e arquivos usando o caminho do item no OneDrive do usuário. No entanto, como o caminho contém conteúdo especificado pelo usuário, que pode conter caracteres que não são seguros para URL, você deve garantir a codificação adequada de quaisquer segmentos de caminho.
O Microsoft Graph espera que as URLs estejam em conformidade com RFC 3986. A seguir está um resumo de como codificar caminhos corretamente para o Microsoft Graph.
Os caracteres a seguir são caracteres reservados do OneDrive e não podem ser usados em nomes de pastas e arquivos do OneDrive.
onedrive-reserved = "/" / "\" / "*" / "<" / ">" / "?" / ":" / "|"
onedrive-business-reserved
= "/" / "\" / "*" / "<" / ">" / "?" / ":" / "|" / "#" / "%"
Observação
- Nomes de pastas não podem terminar com um ponto (
.
). - Nomes de arquivo ou pasta não podem começar com til (~).
Para mais informações, confira Restrições e limitações quando você sincronizar as bibliotecas do SharePoint com seu computador por meio do OneDrive para o trabalho ou escola.
Ao construir o segmento de caminho de uma URL para a API do Microsoft Graph, os seguintes caracteres são permitidos para nomes de caminho, com base no RFC do URI.
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
pct-encoded = "%" HEXDIG HEXDIG
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
sub-delims = "!" / "$" / "&" / "'" / "(" / ")"
/ "*" / "+" / "," / ";" / "="
Os caracteres de nome de item, que não são incluídos no grupo pchar
, como #
e
(espaço), devem ser codificados como percentual.
O Microsoft Graph usa a codificação de percentual padrão, em que os caracteres inválidos para URL são codificados com um % e o código de caracteres UTF-8 para o caractere. Por exemplo:
-
" "
->%20
-
"#"
->%23
Você não pode codificar uma URL inteira em uma chamada, pois as regras de codificação de cada segmento de uma URL são diferentes. Sem codificação adequada, a URL não codificada será ambígua em relação a quais segmentos têm qual conteúdo. Assim, você precisa codificar o caminho da URL durante a criação da cadeia de caracteres de URL.
Por exemplo, em vez de escrever isto:
string url = url_encode("https://graph.microsoft.com/v1.0/me/drive/root:/" + path + ":/children")
Escreva isto:
string url = "https://graph.microsoft.com/v1.0/me/drive/root:/" + url_path_encode(path) + ":/children")
No entanto, nem todas as bibliotecas de codificação de URL respeitam todos os requisitos de codificação de caminho de URL padrão.
As classes .NET para HttpUtility
e Uri
incluem vários métodos de codificação de URL. No entanto, nenhum desses métodos codifica corretamente todos os caracteres reservados para o componente de caminho da URL (incluindo HttpUtility.UrlPathEncode
).
Em vez de usar esses métodos, você deve usar UriBuilder
para construir uma URL com escape correto.
UriBuilder builder = new UriBuilder("https://graph.microsoft.com");
builder.Path = "/v1.0/me/drive/root:/Documents/My Files/#nine.docx";
Uri url = builder.Uri;
Para o desenvolvimento em Objective-C, iOS e Mac OS X, use o método stringByAddingPercentEncodingWithAllowedCharacters
e [NSCharacterSet URLPathAllowedCharacterSet]
para codificar corretamente o componente de caminho da URL.
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]];
Use a classe Uri.Builder
para construir uma URL codificada corretamente.
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();
Use escape()
em JavaScript para codificar adequadamente um componente de caminho.
var root = "https://graph.microsoft.com/v1.0/me/drive/root:";
var path = "/Documents/My Files/#nine.docx";
var url = root + escape(path);
Aqui está um exemplo de um usuário do OneDrive (Adele) com a seguinte hierarquias de pastas:
OneDrive
\Adele's Files
\doc (1).docx
\estimate%s.docx
\Break#Out
\saved_game[1].bin
Para endereçar cada um dos arquivos de Adele, utilize a codificação percentual, da seguinte forma:
Caminho | URL codificada para caminho |
---|---|
\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 |