Freigeben über

Adressieren von Ressourcen in einem Laufwerk auf OneDrive

  • Artikel

Die OneDrive-API ermöglicht die Adressierung von zwei Aspekten einer Ressource über eine einzige URL:

  • Die driveItem-Ressource
  • Eine Eigenschaft, ein Facet oder eine Beziehung des Elements

Ein „item“-Facet repräsentiert ein Element der Ressource, z. B. die Bildmetadaten, Ordnermetadaten usw.

In diesem Beispiel kann eine kanonische URL für eine Datei folgendermaßen aussehen.

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

Diese Beispiel-URL besteht aus diesen Komponenten:

  • https://graph.microsoft.com/v1.0 – Die verwendete Version von Microsoft Graph.
  • /me – Eine hochrangige Microsoft Graph-Ressource, die adressiert wird, in diesem Fall der aktuelle Benutzer.
  • /drive – Das Standardlaufwerk für die vorherige Ressource, in diesem Fall das OneDrive des Benutzers.
  • /root – Der Stammordner des Laufwerks.
  • :/Documents/MyFile.xlsx: – : : um /Documents/MyFile.xlsx stellt einen Switch zur pfadbasierten Adressierungssyntax dar. Alles zwischen den zwei Doppelpunkten wird als Pfad relativ zum Element vor dem Pfad (in diesem Fall das Stammelement) behandelt.
  • /content – Steht für den standardmäßigen binären Stream für die Datei. Sie können auch andere Eigenschaften oder Beziehungen für das Element adressieren.

ID-basierte Adressierung

OneDrive unterstützt die ID-basierten Adressierung von Elementen. Elemente sind einer eindeutigen ID zugewiesen, wenn sie erstellt werden, und die ID bleibt über alle Aktionen, die ein Benutzer mit dem Element ausführt, bestehen. Das Umbenennen oder Verschieben des Elements ändert nicht die Element-ID.

ID-basierte Adressierung ist ein nützliches Verfahren zum Nachverfolgen von Elementen, die vom Benutzer an verschiedene Positionen auf OneDrive verschoben werden können. Solange Sie die Element-ID kennen und das Element vorhanden ist, können Sie es finden.

Pfadbasierte Adressierung

OneDrive unterstützt auch die pfadbasierte Adressierung. Dies ermöglicht Ihnen die Verwendung einer benutzerfreundlichen URL-Syntax zur Adressierung von Elementen in Bezug auf die Hierarchie von Elementen, die in OneDrive sichtbar sind. Wenn Sie zu einem Element die Hierarchie kennen, können Sie dieses Element direkt adressieren, ohne wiederholte Aufrufe zur Ermittlung jeder Hierarchieebene durchführen zu müssen.

Da jedoch die pfadbasierte Adressierung auf dem Namen des Elements beruht, führt das Umbenennen oder Verschieben des Elements an eine neue Position auch zu einer Änderung des Pfads.

Die pfadbasierte Adressierung kann in Bezug auf ein beliebiges Element in OneDrive verwendet werden, was einige sehr hilfreiche Szenarien möglich macht. Z. B. können Sie bei der Arbeit mit freigegebenen Ordnern eine pfadbasierte URL bezüglich der Element-ID des freigegebenen Ordners verwenden, um Inhalte in den freigegebenen Ordnern anhand des Pfads zu adressieren.

Beispiele

In diesen Beispielen werden die verschiedenen URL-Formate dargestellt, die für den Zugriff auf Daten verwendet werden können. Alle diese URLs sind logisch gleichwertig und geben den Inhalt der Datei MyFile.xlsx zurück.

Beispiel-URL Beschreibung
/drive/root:/Documents/MyFile.xlsx:/content Durch den Pfad in Bezug auf das Stammelement eines Laufwerks angegeben.
/drive/special/documents:/MyFile.xlsx:/content Durch den Dateinamen im speziellen Ordner documents angegeben.
/drive/items/0123456789AB/content Durch die Element-ID angegeben.
/drives/AB0987654321/items/0123456789AB/content Durch die Laufwerk-ID und Element-ID angegeben.

Pfadcodierung

OneDrive unterstützt die Adressierung von Dateien und Ordnern über den Pfad des Elements im OneDrive des Benutzers. Da der Pfad jedoch vom Benutzer angegebene Inhalte umfasst, die möglicherweise nicht-URL-fähige Zeichen umfassen, sollten Sie die richtige Codierung aller Pfadsegmente sicherstellen.

Microsoft Graph erwartet, dass URLs den Vorgaben von RFC 3986 entsprechen. Im Folgenden finden Sie eine Übersicht zur richtigen Codierung von Pfaden für Microsoft Graph.

Für OneDrive reservierte Zeichen

Die folgenden Zeichen sind für OneDrive reservierte Zeichen und dürfen nicht für OneDrive-Ordner- und -Dateinamen verwendet werden.

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

Hinweis: Ordnernamen dürfen nicht mit einem Punkt (.) enden.

Hinweis: OneDrive for Business-Dateien oder Ordnernamen dürfen nicht mit einer Tilde („~“) beginnen. Weitere Informationen finden Sie unter Einschränkungen und Grenzen mit OneDrive for Business.

Zeichen für URI-Pfade

Bei der Erstellung des Pfadsegments einer URL für die OneDrive-API sind die folgenden Zeichen für Pfadnamen zulässig, basierend auf URI RFC.

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

Zeichen für Elementnamen, die nicht in der Gruppe pchar enthalten sind, z. B. # und (Leerzeichen), müssen Prozent-codiert werden.

Codieren von Zeichen

Microsoft Graph verwendet die standardmäßige Prozent-Codierung, bei der nicht-URL-fähige Zeichen mit einem % und dem UTF-8-Zeichencode für das Zeichen codiert werden. Beispiel:

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

Häufige Fehler bei der URL-Codierung

Sie können nicht die gesamte URL in einem Aufruf codieren, da die Regeln zur Codierung für jedes Segment einer URL unterschiedlich lauten. Ohne die richtige Codierung ist die nicht codierte URL nicht eindeutig im Hinblick darauf, welche Segmente welche Inhalte enthalten. Daher müssen Sie den URL-Pfad beim Erstellen der URL-Zeichenfolge codieren.

Beispiel: Statt diesem:

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

Schreiben Sie Folgendes:

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

Nicht alle URL-Codierungs-Bibliotheken berücksichtigen jedoch alle Anforderungen der standardmäßigen URL-Pfad-Codierung.

.NET/C-Sharp/Visual Basic

Die .NET-Klassen für HttpUtility und Uri enthalten verschiedene Methoden für die URL-Codierung. Keine dieser Methoden codiert jedoch alle reservierte Zeichen für die Pfadkomponente einer URL (einschließlich HttpUtility.UrlPathEncode) richtig.

Statt dieser Methoden sollten Sie UriBuilder zum Erstellen einer URL mit richtigen Escape-Zeichen verwenden.

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

Verwenden Sie für die Objective-C-, iOS- und Mac OS X-Entwicklung die stringByAddingPercentEncodingWithAllowedCharacters-Methode und [NSCharacterSet URLPathAllowedCharacterSet] zur ordnungsgemäßen Codierung der Pfadkomponente der 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

Verwenden Sie die Uri.Builder-Klasse zur Erstellung einer ordnungsgemäß codierten URL.

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

Verwenden Sie escape() in JavaScript zur ordnungsgemäßen Codierung einer Pfadkomponente.

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

Beispiele

Hier ist ein Beispiel eines OneDrive-Benutzers (Ryan) mit folgender Ordnerhierarchie:

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

Um jede von Ryans Dateien zu adressieren, verwenden Sie die Prozent-Codierung wie folgt:

Pfad Codierte URL für Pfad
\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