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.
Endereçamento baseado em ID
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.
Endereçamento com base no caminho
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.
Exemplos
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. |
Codificação de caminho
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.
Caracteres reservados do OneDrive
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.
Caracteres de caminho de URI
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.
Codificação de caracteres
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
erros comuns de codificação de URL
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.
.NET/C-Sharp/Visual Basic
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;
Objective-C/iOS
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]];
Android
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();
JavaScript
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);
Exemplos
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 |