Adressage de ressources dans un lecteur sur OneDrive

L’API OneDrive permet à une URL unique de traiter deux aspects d’une ressource :

• Ressource driveItem
• Propriété, facette ou relation de l’élément

Une facette Item représente un élément de la ressource comme les métadonnées de l’image, les métadonnées du dossier, etc.

Dans cet exemple, une URL canonique pour un fichier peut ressembler à ceci.

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

Cet exemple d’URL comporte les éléments suivants :

• https://graph.microsoft.com/v1.0- Version de Microsoft Graph utilisée.
• /me- Ressources Microsoft Graph de niveau supérieur traitées, dans ce cas, l’utilisateur actuel.
• /drive- Lecteur par défaut pour la ressource précédente, dans ce cas, le OneDrive de l’utilisateur.
• /root - Dossier racine du lecteur.
• :/Documents/MyFile.xlsx:- Le signe : : autour de /Documents/MyFile.xlsx représente un transfert vers la syntaxe d’adressage basée sur le chemin d’accès. Tout élément inclus entre les deux signes deux-points est traité comme un chemin d’accès relatif à l’élément avant le chemin d’accès (dans ce cas, la racine).
• /content- Représente le flux binaire par défaut pour le fichier. Vous pouvez également traiter d’autres propriétés ou relations de l’élément.

Adressage basé sur l’ID

OneDrive prend en charge l’adressage des éléments basé sur l’ID. Les éléments reçoivent un identificateur unique lorsqu’ils sont créés et l’ID est conservé pour les actions qu’un utilisateur réalise sur l’élément. L’attribution d’un nouveau nom ou le déplacement de l’élément ne modifie pas l’ID de l’élément.

L’adressage basé sur l’ID est utile pour suivre les éléments qui peuvent être déplacés par l’utilisateur à différents emplacements sur OneDrive. Tant que vous disposez de l’ID de l’élément et que l’élément existe, vous pouvez le retrouver.

Adressage basé sur le chemin d’accès

OneDrive prend également en charge l’adressage basé sur le chemin d’accès. Ainsi, vous pouvez utiliser une syntaxe URL conviviale pour traiter les éléments relatifs à la hiérarchie des éléments visibles dans OneDrive. Si vous connaissez la hiérarchie d’un élément, vous pouvez traiter directement cet élément et éviter d’effectuer des appels répétés pour découvrir chaque niveau de la hiérarchie.

Toutefois, étant donné que l’adressage basé sur le chemin d’accès dépend du nom de l’élément, l’attribution d’un nouveau nom ou le déplacement de l’élément vers un nouvel emplacement entraîne la modification du chemin d’accès de l’élément.

L’adressage basé sur le chemin d’accès peut être utilisé par rapport à n’importe quel élément dans OneDrive, ce qui permet de concevoir des scénarios très utiles. Par exemple, lorsque vous utilisez des dossiers partagés, vous pouvez utiliser une URL basée sur le chemin d’accès relative à l’ID d’élément du dossier partagé pour traiter un élément dans le dossier partagé par chemin d’accès.

Exemples

Ces exemples décrivent les différents formats d’URL qui peuvent être utilisés pour accéder aux données. Toutes ces URL sont logiquement équivalentes et renvoient le contenu de MyFile.xlsx.

Codage du chemin d’accès

OneDrive prend en charge l’adressage des fichiers et des dossiers à l’aide du chemin d’accès de l’élément dans le OneDrive de l’utilisateur. Toutefois, étant donné que le chemin d’accès inclut le contenu spécifié par l’utilisateur qui peut éventuellement comprendre des caractères non sécurisés, vous devez vérifier que le codage de chaque segment du chemin d’accès est correct.

Pour Microsoft Graph, les URL doivent être conformes à RFC 3986. Vous trouverez ci-dessous un résumé sur la façon de coder correctement les chemins d’accès pour Microsoft Graph.

Caractères OneDrive réservés

Les caractères suivants sont des caractères OneDrive réservés et ne peuvent pas être utilisés dans le dossier et les noms de fichiers OneDrive.

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

Remarque : Les noms de dossiers ne peuvent pas se terminer par un point (.).

Remarque : Les noms de fichiers et de dossiers OneDrive Entreprise ne peuvent pas commencer par un tilde ('~ '). Consultez la rubrique Restrictions et limites relatives à OneDrive Entreprise pour plus d’informations.

Caractères de chemin d’accès à l’URI

Lorsque vous créez le segment du chemin d’accès à l’URL pour l’API OneDrive, les caractères suivants sont autorisés pour les noms de chemin d’accès, en fonction des règles RFC de l’URI.

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

Les caractères du nom de l’élément, qui ne sont pas inclus dans le groupe pchar, comme # et (espace), doivent être codés en pourcentage.

Codage des caractères

Microsoft Graph utilise un codage standard en pourcentage, où les caractères non valides de l’URL sont codés avec un %, puis un code UTF-8 pour le caractère. Par exemple :

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

Erreurs courantes de codage d’URL

Il n’est pas possible de coder une URL dans son intégralité dans un seul appel, car les règles de codage pour chaque segment d’une URL sont différentes. Sans codage approprié, l’URL non codée n’indiquera pas clairement quels segments contiennent quel contenu. Ainsi, vous devez coder le chemin d’accès à l’URL lorsque vous créez votre chaîne d’URL.

Par exemple, au lieu d’écrire ce qui suit :

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

Écrivez ceci :

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

Toutefois, toutes les bibliothèques de codage d’URL ne respectent pas toutes les exigences de codage standard du chemin d’URL.

.NET / C-Sharp / Visual Basic

Les classes .NET pour HttpUtility et Uri comprennent différentes méthodes de codage d’URL. Toutefois, aucune de ces méthodes ne permet de coder correctement tous les caractères réservés pour le composant du chemin d’accès à l’URL (y compris HttpUtility.UrlPathEncode).

Au lieu d’utiliser ces méthodes, utilisez UriBuilder pour concevoir une URL correctement formulée.

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

Pour le développement d’Objective-C, d’iOS et de Mac OS X, utilisez la méthode stringByAddingPercentEncodingWithAllowedCharacters et [NSCharacterSet URLPathAllowedCharacterSet] pour coder correctement le composant du chemin d’accès à l’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

Utilisez la classe Uri.Builder pour créer une URL codée correctement.

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

Utilisez escape() dans JavaScript pour coder correctement un composant du chemin d’accès.

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

Exemples

Voici un exemple d’utilisateur OneDrive (Ryan) avec la hiérarchie de dossiers suivante :

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

Pour traiter chaque fichier de Ryan, utilisez le codage en pourcentage, comme suit :