Freigeben über

Zugreifen auf OneDrive und SharePoint in Microsoft Graph

  • Artikel

Dokumentationsüberprüfung und Buildstatus

Die OneDrive-REST-API ist ein Teil der Microsoft Graph-API, mit der Sie eine Verbindung zwischen Ihrer App und in OneDrive und in SharePoint gespeicherten Inhalten herstellen können. OneDrive, OneDrive for Business, SharePoint-Dokumentbibliotheken und Office-Gruppen nutzen die REST API gemeinsam, damit Ihre App mit demselben Code Inhalte von einem dieser Speicherorte auslesen oder sie dort speichern kann.

Diese REST-APIs sind Teil der Microsoft-Graph-API, eine gemeinsame API für Microsoft-Dienste.

Lesen Sie für vorhandene Lösungen, die die OneDrive-API außerhalb von Microsoft Graph verwenden, oder Lösungen, die auf SharePoint Server 2016 abzielen, Unterschiede des direkten Endpunkts, um weiteren Kontext zum Lesen dieser Dokumentation zu erhalten.

Erste Schritte

Um sich schnell mit Microsoft Graph und dem Zugreifen auf Dateien vertraut zu machen, sehen Sie sich den Graph-Tester und den Microsoft Graph-Schnellstart an.

Die REST-API von OneDrive bietet einige Typen auf oberster Ebene, die adressierbare Ressourcen in der API darstellen:

Es folgt ein Beispiel für eine driveItem-Ressource:

{
  "@microsoft.graph.downloadUrl":"http://public-sn3302.files.1drv.com/y2pcT7OaUEExF7EHOl",
  "createdDateTime": "2014-10-31T03:37:04.72Z",
  "eTag": "aRDQ2NDhGMDZDOTFEOUQzRCE1NDkyNy4w",
  "id":"D4648F06C91D9D3D!54927",
  "lastModifiedBy": {
    "user": {
      "displayName": "daron spektor",
      "id": "d4648f06c91d9d3d"
    }
  },
  "name":"BritishShorthair.docx",
  "size":35212,
  "file": {
    "hashes":{
      "sha1Hash":"cf23df2207d99a74fbe169e3eba035e633b65d94"
    }
  }
}

Daten zu einer Ressource werden auf drei Arten bereitgestellt:

  • Eigenschaften (wie id und name) legen einfache Werte offen.
  • Facets (wie file und photo) legen komplexe Werte offen. Das Vorhandensein von Facets eines Elements gibt im Allgemeinen Verhaltensweisen oder Funktionen eines Elements und verknüpfter Eigenschaften an.
  • Referenzen (wie children) verweisen auf Sammlungen anderer Ressourcen.

Viele Anfragen können so angepasst werden, dass zusätzliche Daten eingeschlossen oder nicht verwendete Eigenschaften aus den Antworten entfernt werden. OneDrive verwendet optionale Abfrageparameter, um diese Funktion zu aktivieren. In der gesamten Dokumentation liefert jede Anforderung mehr Kontext darüber, welche Parameter unterstützt werden.

Standardmäßig werden die meisten Eigenschaften und Facets zurückgegeben, wohingegen alle Referenzen ausgeblendet werden. Aus Leistungsgründen wird empfohlen, dass Sie select und expand für die Daten angeben, an denen Sie interessiert sind.

Weitere Informationen zu Ressourcen und Facets finden Sie unter Ressourcen und Facets.

Microsoft Graph-Stammressourcen

In Microsoft Graph ist die OneDrive-Funktionalität über mehrere Stammressourcen verfügbar. Diese Ressourcen entsprechen den Orten, an denen OneDrive- und SharePoint-Dokumentbibliotheken innerhalb von Office 365 verfügbar sind. Die folgenden Entitäten in Microsoft Graph können ein oder mehrere Laufwerke enthalten:

Entität Beispielpfad
Benutzer /v1.0/users/{id} oder /v1.0/me
Gruppe /v1.0/groups/{id}
Site /v1.0/sites/{id}

OneDrive-Stammressourcen

Beim Adressieren einer Microsoft Graph-Stammressource kann Ihre App OneDrive-Ressourcen mithilfe der folgenden Pfade adressieren:

Pfad Ressource
/drives Auflisten von drive-Ressourcen, die für den authentifizierten Benutzer verfügbar sind.
/drives/{drive-id} Zugriff auf ein bestimmtes Laufwerk anhand seiner ID.
/drives/{drive-id}/root/children Auflisten von Elementen im Stammverzeichnis eines bestimmten Laufwerks.
/drive/items/{item-id} Zugriff auf ein driveItem-Objekt anhand seiner ID.
/drive/special/{special-id} Zugriff auf einen bekannten Ordner anhand seines bekannten Namens.
/shares/{share-id} Zugriff auf ein driveItem-Objekt anhand seiner shareId oder einer URL zum Teilen.

Pfadbasierte Adressierung innerhalb eines Laufwerks

Ein driveItem kann entweder durch einen eindeutigen Bezeichner oder durch den Ort adressiert werden, an dem dieses Element in der Hierarchie des Laufwerks vorhanden ist (d. h. benutzerpfad). Innerhalb einer API-Anforderung kann ein Doppelpunkt verwendet werden, um zwischen API-Pfadbereich und Benutzerpfadbereich zu wechseln. Diese Syntax ist für alle driveItem-Elemente gültig, die über den API-Bereich adressiert werden.

Sie können auch zurück zum API-Pfadraum wechseln, indem Sie einen Doppelpunkt am Ende des Dateisystem-Pfadraums verwenden. Stellen Sie sicher, dass Benutzerdaten innerhalb der URL den Anforderungen der Adressierung und Pfadcodierung entsprechen.

Pfad Ressource
/drive/root:/path/to/file Zugriff auf ein driveItem-Objekt anhand des Pfads unter dem Stamm.
/drive/items/{item-id}:/path/to/file Zugriff auf ein driveItem-Objekt über seinen Pfad relativ zu einem anderen Element.
/drive/root:/path/to/folder:/children Auflisten von untergeordneten Elementen beim Zugriff anhand des Pfads relativ zum Laufwerkstamm.
/drive/items/{item-id}:/path/to/folder:/children Auflisten von untergeordneten Elementen beim Zugriff anhand des Pfads relativ zu einem anderen Element.

Geteilte Ordner und Remoteelemente

In OneDrive Personal kann ein Benutzer ein oder mehrere freigegebene Elemente von einem anderen Laufwerk zu seinem eigenen OneDrive hinzufügen. Diese freigegebenen Elemente werden als driveItem in der children-Sammlung mit einem remoteItem-Facet angezeigt.

Szenarien, in denen Elemente von außerhalb des Ziellaufwerks zurückgegeben werden, umfassen außerdem ein remoteItem-Facet. Diese Elemente können auch von Suche, Zuletzt verwendete Dateien oder Für mich freigegeben zurückgegeben werden.

Weitere Informationen zum Arbeiten mit geteilten Ordnern und Remoteelementen finden Sie unter Remoteelemente und geteilte Ordner.

Teilen und Berechtigungen

Eine der am häufigsten verwendeten Aktionen für OneDrive und SharePoint besteht im Freigeben von Inhalten für andere Personen. Über OneDrive kann Ihre App Freigabelinks erstellen, Berechtigungen hinzufügen und Einladungen an Elemente senden, die auf einem Laufwerk gespeichert sind.

OneDrive bietet der App auch eine Möglichkeit, Zugriff auf freigegebene Inhalte direkt über den Freigabelink zu erhalten.

Weitere Details zum Teilen und Nutzen von geteilten Inhalten finden Sie unter Teilen von Elementen in OneDrive.

Webhooks und Benachrichtigungen

OneDrive unterstützt das Senden von Pushbenachrichtigungen im Webhook-Format, wenn die Inhalte eines OneDrives geändert werden. Ihre App kann diese Benachrichtigungen verwenden, um Änderungen praktisch in Echtzeit zu verfolgen, anstatt Änderungen vom Server abzurufen.

Hinweise zur Programmierung

API-Kompatibilität

OneDrive wird ständig weiterentwickelt und erhält immer neue Funktionen. Der API-Pfad umfasst eine Versionsnummer, um Ihre App vor grundlegenden Änderungen zu schützen. Wenn eine grundlegende Änderung erforderlich ist, wird die API-Versionsnummer erhöht. Vorhandene Apps, die die ursprüngliche Versionsnummer aufrufen, sind nicht von der Änderung betroffen. In der Microsoft Graph-Supportrichtlinie finden Sie Informationen dazu, wie lange eine Version der API unterstützt wird.

Eine grundlegende Änderung ist eine Änderung im Format einer Anforderung oder Antwort, die ein vorhandenes dokumentiertes Verhalten entfernt oder ändert oder ein Element aus der Definition einer Ressource entfernt. Das Hinzufügen zusätzlicher Aktionen, Eigenschaften, Facets oder Verweise auf eine Ressource stellt keine grundlegende Änderung dar.

Die API kann von Zeit zu Zeit zusätzliche nicht dokumentierte Features verfügbar machen. Diese Features sollten erst verwendet werden, wenn sie dokumentiert sind. Gehen Sie nicht davon aus, dass das aktuelle Verhalten, das von der Dokumentation abweicht, bestehen bleibt.

An der vorhanden Version der API werden ständig nicht grundlegende Änderungen vorgenommen, es werden beispielsweise Facets, Eigenschaften und Ressourcen zu der API hinzugefügt. Für Code, der die API aufruft, gilt daher Folgendes:

  • Er muss stabil sein, während zusätzliche Eigenschaften zu JSON-Antworten hinzugefügt werden. Er kann ignoriert werden.
  • Er ist nicht von der Reihenfolge der Eigenschaften abhängig, die in JSON-Antworten zurückgegeben werden.
  • Er darf nur dokumentierte API-Pfade, Ressourcen, Eigenschaften und Aufzählungswerte verwenden. Bei nicht dokumentierten Werten kann nicht garantiert werden, dass diese konsistent bleiben.
  • Alle URLs, die von der OneDrive-API zurückgegebenen sollte als opake URLs behandelt werden. Ihre App sollte keine Annahmen zum Format oder zu Parametern in diesen URLS machen. Diese können ohne vorherige Ankündigung geändert werden.

Einschränkung

In OneDrive gibt es gewisse Einschränkungen, um sicherzustellen, dass Personen und Apps die Erfahrung von anderen Benutzern nicht negativ beeinflussen. Wenn eine Aktivität die Grenzwerte von OneDrive überschreitet, werden API-Anforderungen für einen bestimmten Zeitraum abgelehnt. OneDrive kann auch den Header Retry-After mit der Anzahl von Sekunden zurückgeben, die Ihre App warten soll, bevor weitere Anforderungen gesendet werden.

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

Arbeiten mit OneNote-Notizbüchern

Hinweis: In OneDrive werden zwar OneNote-Notizbücher gespeichert, Sie sollten jedoch die OneDrive-API nicht verwenden, um mit OneNote-Notizbüchern zu arbeiten. Verwenden Sie stattdessen die OneNote-API.

Kontinuierliche Dokumentationsüberprüfung

Im Rahmen unseres Engagements im Hinblick auf qualitativ hochwertige Dokumentation haben wir einen Prozess entwickelt, über den die Beispiele in unserer Dokumentation im Hinblick auf Gültigkeit bei jedem Einchecken getestet werden. Wir bezeichnen dies als fortlaufende Dokumentationsüberprüfung.

Jedes Mal, wenn eine Änderung an unserer Dokumentation vorgenommen wird, überprüfen wir, dass alles wie in dem Dienst dokumentiert funktioniert. Wenn wir einen neuen Build des Diensts erstellen, überprüfen wir, dass die Beispiele in unserer Dokumentation auch weiterhin funktionieren. Auf diese Weise können wir sicherstellen, dass alles, was dokumentiert wird, wie erwartet funktioniert, auch wenn neue Updates verfügbar gemacht werden.

Sehen Sie sich die AppVeyor-Buildstatusseite für unser Dokumentationsrepository an, um Informationen zu den neuesten Builds zu erhalten.

Die folgenden Themen enthalten einen allgemeinen Überblick über weitere Konzepte, die mit der OneDrive-API verbunden sind.