Compartilhar via

Endereçar recursos em uma unidade no OneDrive

  • Artigo

A API do OneDrive permite que uma única URL enderece dois aspectos de um recurso:

  • O recurso driveItem
  • Uma propriedade, faceta ou relação do Item

Uma faceta de Item representa um elemento do recurso, como os metadados de imagem, os metadados de pasta e assim por diante.

Neste exemplo, uma URL canônica de um arquivo pode ter esta aparência.

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

Esta URL de exemplo tem estes componentes:

  • https://graph.microsoft.com/v1.0 – a versão do Microsoft Graph que está sendo usada.
  • /me – um recurso do Microsoft Graph de nível superior que está sendo endereçado, neste caso, o usuário atual.
  • /drive – a unidade padrão do recurso anterior, neste caso, o OneDrive do usuário.
  • /root – a pasta raiz da unidade.
  • :/Documents/MyFile.xlsx: – : : em torno de /Documents/MyFile.xlsx representa uma opção para a sintaxe de endereçamento baseada no caminho. Tudo entre dois-pontos será tratado como um caminho relativo para o item antes do caminho (nesse caso, a raiz).
  • /content – representa o fluxo binário padrão do arquivo. Você também pode endereçar outras propriedades ou relações no item.

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.

O endereçamento baseado no caminho pode ser usado em relação a qualquer item no OneDrive, o que habilita alguns cenários muito úteis. 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

Esses exemplos mostram os diferentes formatos de URL que podem ser usados 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 em URLs, você deve garantir uma codificação adequada de todos os 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 arquivos e pastas do OneDrive.

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

Observação: nomes de pastas não podem terminar com um ponto (.).

Observação: nomes de arquivo ou pasta do OneDrive for Business não podem começar com til (~). Confira mais informações em Restrições e limitações com o OneDrive for Business.

Caracteres de caminho de URI

Ao se construir o segmento de caminho de URL para a API do OneDrive, os caracteres a seguir são permitidos para nomes de caminho, com base no URI RFC.

  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://api.onedrive.com/v1.0/drive/root:/" + path + ":/children")

Escreva isto:

string url = "https://api.onedrive.com/v1.0/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://api.onedrive.com");
builder.Path = "/v1.0/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://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

Use a classe Uri.Builder para construir uma URL codificada corretamente.

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

Use escape() em JavaScript para codificar adequadamente um componente de caminho.

var root = "https://api.onedrive.com/v1.0/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 (Carlos) com a seguinte hierarquia de pastas:

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

Para endereçar cada um dos arquivos de Carlos, você usa a codificação de percentual, da seguinte maneira:

Caminho URL codificada para caminho
\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