Direccionamiento de recursos en una unidad de OneDrive

Artículo
04/08/2023

La API de OneDrive permite que una única URL direccione dos aspectos de un recurso:

El recurso driveItem
Una propiedad, faceta o relación del elemento

Una faceta Item representa un elemento del recurso, como los metadatos de imagen y los metadatos de carpeta, entre otros.

En este ejemplo, una dirección URL canónica para un archivo puede tener este aspecto.

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

Esta URL de ejemplo tiene estos componentes:

https://graph.microsoft.com/v1.0: la versión de Microsoft Graph que se usa.
/me: un recurso de Microsoft Graph de nivel superior que se va a direccionar, en este caso, el usuario actual.
/drive: la unidad predeterminada del recurso anterior, en este caso, el OneDrive del usuario.
/root: la carpeta raíz de la unidad.
:/Documents/MyFile.xlsx:: los : : alrededor de /Documents/MyFile.xlsx representan un modificador de la sintaxis de direccionamiento basada en la ruta de acceso. Todo lo que aparece entre los dos puntos se trata como una ruta de acceso en relación con el elemento anterior de la ruta (en este caso, la raíz).
/content: representa la secuencia binaria predeterminada del archivo. También puede direccionar otras propiedades o relaciones del elemento.

Direccionamiento basado en el identificador

OneDrive admite el direccionamiento basado en el identificador de los elementos. A los elementos se les asigna un identificador único cuando se crean y el identificador continúa en las acciones que realiza un usuario en el elemento. Cambiar el nombre o mover el elemento no cambiará el identificador de este.

El direccionamiento basado en el identificador es una manera útil de realizar un seguimiento de los elementos que el usuario puede haber movido a diferentes ubicaciones de OneDrive. Siempre que tenga el id. de elemento y el elemento exista, podrá encontrarlo.

Direccionamiento basado en la ruta de acceso

OneDrive también admite el direccionamiento basado en la ruta de acceso. Esto le permite usar una sintaxis de URL descriptiva para direccionar elementos en relación con la jerarquía de elementos visibles en OneDrive. Si conoce la jerarquía de un elemento, puede direccionar directamente ese elemento, sin invertir tiempo en realizar llamadas repetidas para detectar cada nivel de la jerarquía.

En cambio, como el direccionamiento basado en la ruta de acceso se basa en el nombre del elemento, cambiar el nombre o mover el elemento a una nueva ubicación provocará que la ruta del elemento cambie.

El direccionamiento basado en la ruta de acceso puede usarse en relación con cualquier elemento de OneDrive, que permite algunos escenarios muy útiles. Por ejemplo, al trabajar con carpetas compartidas, puede usar una dirección URL basada en la ruta de acceso en relación con el id. de elemento de la carpeta compartida para direccionar algo de la carpeta compartida mediante la ruta.

Ejemplos

En estos ejemplos se muestran los diferentes formatos de URL que pueden usarse para tener acceso a los datos. Todas estas direcciones URL son equivalentes de manera lógica y devuelven el contenido de MyFile.xlsx.

Ejemplo de URL	Descripción
`/drive/root:/Documents/MyFile.xlsx:/content`	Se especifica mediante la ruta en relación con la raíz de una unidad.
`/drive/special/documents:/MyFile.xlsx:/content`	Se especifica mediante el nombre de archivo en la carpeta especial `documents`.
`/drive/items/0123456789AB/content`	Se especifica mediante el id. de elemento.
`/drives/AB0987654321/items/0123456789AB/content`	Se especifica mediante el id. de unidad y el id. de elemento.

Codificación de la ruta de acceso

OneDrive admite el direccionamiento de archivos y carpetas con la ruta del elemento en el OneDrive del usuario. En cambio, como la ruta contiene contenido especificado por el usuario que puede contener potencialmente caracteres que no son seguros para la URL, debe garantizar una codificación correcta de cualquier segmento de la ruta de acceso.

Microsoft Graph espera que las direcciones URL cumplan con RFC 3986. A continuación se muestra un resumen de cómo codificar rutas de acceso correctamente en Microsoft Graph.

Caracteres reservados de OneDrive

Los siguientes caracteres son caracteres reservados de OneDrive, y no pueden usarse en los nombres de archivo y carpeta de OneDrive.

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

Nota: Los nombres de carpeta no pueden terminar con un punto (.).

Nota: Los nombres de archivo o carpeta de OneDrive para la Empresa no pueden comenzar con una tilde de la ñ ("~"). Vea Restricciones y limitaciones con OneDrive para la Empresa para obtener más información.

Caracteres de la ruta de acceso de URI

Al crear el segmento de ruta de acceso de una dirección URL para la API de OneDrive, se permiten los siguientes caracteres para los nombres de ruta, basados en las RFC del URI.

  pchar       = unreserved / pct-encoded / sub-delims / ":" / "@"
  pct-encoded = "%" HEXDIG HEXDIG
  unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"
  sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="

Los caracteres de nombre de elemento, que no se incluyen en el grupo pchar, como # y (espacio), debe ser codificados por porcentaje.

Codificación de caracteres

Microsoft Graph usa la codificación por porcentaje estándar, donde los caracteres de URL no válida se codifican con un % y, después, el código de carácter UTF-8 para el carácter. Por ejemplo:

" " ->%20
"#" ->%23

Errores comunes de codificación URL

No puede codificar una dirección URL completa en una llamada, porque las reglas de codificación para cada segmento de una dirección URL son diferentes. Sin una codificación correcta, la URL sin codificar será ambigua para los segmentos que contienen contenido. Como tal, necesita codificar la ruta de dirección URL al crear la cadena de URL.

Por ejemplo, en lugar de escribir esto:

string url = url_encode("https://api.onedrive.com/v1.0/drive/root:/" + path + ":/children")

Escriba esto:

string url = "https://api.onedrive.com/v1.0/drive/root:/" + url_path_encode(path) + ":/children")

En cambio, no todas las bibliotecas de codificación URL respetan todos los requisitos de la codificación de la ruta de acceso de URL estándar.

.NET / C-Sharp / Visual Basic

Las clases .NET para HttpUtility y Uri incluyen varios métodos para la codificación URL. En cambio, ninguno de esos métodos codifica correctamente todos los caracteres reservados para el componente de ruta de la dirección URL (incluido HttpUtility.UrlPathEncode).

En lugar de usar esos métodos, debe usar UriBuilder para crear una dirección URL de escape correctamente.

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 el desarrollo de Objective-C, iOS y Mac OS X, use el método stringByAddingPercentEncodingWithAllowedCharacters y [NSCharacterSet URLPathAllowedCharacterSet] para codificar correctamente el componente de la ruta de la dirección 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 la clase Uri.Builder para crear una dirección URL codificada correctamente.

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() en JavaScript para codificar correctamente un componente de ruta.

var root = "https://api.onedrive.com/v1.0/drive/root:";
var path = "/Documents/My Files/#nine.docx";
var url = root + escape(path);

Ejemplos

Aquí se muestra un ejemplo de un usuario de OneDrive (Ryan) con la siguiente jerarquía de carpetas:

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

Para tratar cada uno de los archivos de Ryan, use la codificación por porcentaje, de la manera siguiente:

Ruta de acceso	Dirección URL codificada para la ruta de acceso
`\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`

Direccionamiento de recursos en una unidad de OneDrive

Direccionamiento basado en el identificador

Direccionamiento basado en la ruta de acceso

Ejemplos

Codificación de la ruta de acceso

Caracteres reservados de OneDrive

Caracteres de la ruta de acceso de URI

Codificación de caracteres

Errores comunes de codificación URL

.NET / C-Sharp / Visual Basic

Objective-C / iOS

Android

JavaScript

Ejemplos

Recursos adicionales