Zugreifen auf OneDrive und SharePoint in Microsoft GraphOneDrive and SharePoint in Microsoft Graph

Dokumentationsüberprüfung und BuildstatusDocumentation validation and build status

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.The OneDrive REST API is a portion of the Microsoft Graph API which allows your app to connect to content stored in OneDrive and SharePoint. 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.The REST API is shared between OneDrive, OneDrive for Business, SharePoint document libraries, and Office Groups, to allow your app the flexibility to read and store content in any of these locations with the same code.

Diese REST-APIs sind Teil der Microsoft-Graph-API, eine gemeinsame API für Microsoft-Dienste.OneDrive APIs are a part of the Microsoft Graph, a common API for Microsoft services.

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.For existing solutions using OneDrive API outside of Microsoft Graph, or solutions targeting SharePoint Server 2016, see direct endpoint differences for more context on reading this documentation.

Erste SchritteGetting started

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.To quickly experiment with Microsoft Graph and accessing files, check out the Graph Explorer and the Microsoft Graph Quick Start.

Die REST-API von OneDrive bietet einige Typen auf oberster Ebene, die adressierbare Ressourcen in der API darstellen:OneDrive's REST API provides a few top-level types that represent addressable resources in the API:

Es folgt ein Beispiel für eine driveItem-Ressource:The following is an example of a driveItem resource.

{
  "@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:Data about a resource is provided in three ways:

  • Eigenschaften (wie id und name) legen einfache Werte offen.Properties (like id and name) expose simple values.
  • 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.Facets (like file and photo) expose complex values. The presence of facets on an item generally indicate behaviors or capabilities of an item and related properties.
  • Referenzen (wie children) verweisen auf Sammlungen anderer Ressourcen.References (like children) point to collections of other resources.

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.Many requests can be tailored to include additional data or remove unused properties from the responses. OneDrive uses optional query parameters to enable this functionality. Throughout the documentation, each request provides more context about which parameters are supported.

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.By default, most properties and facets are returned while all references are hidden. For efficiency, we recommend that you specify select and expand for the data you care about.

Weitere Informationen zu Ressourcen und Facets finden Sie unter Ressourcen und Facets.For details about resources and facets, see Resources and Facets.

Microsoft Graph-StammressourcenMicrosoft Graph root resources

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:Within the Microsoft Graph, the OneDrive functionality is available from several root resources. These resources correspond to where OneDrive and SharePoint document libraries are available within Office 365. The follow entities in Microsoft Graph may contain one or more drives:

EntitätEntity BeispielpfadExample Path
BenutzerUser /v1.0/users/{id} oder /v1.0/me/v1.0/users/{id} or /v1.0/me
GruppeGroup /v1.0/groups/{id}
SiteSite /v1.0/sites/{id}

OneDrive-StammressourcenOneDrive root resources

Beim Adressieren einer Microsoft Graph-Stammressource kann Ihre App OneDrive-Ressourcen mithilfe der folgenden Pfade adressieren:When addressing a Microsoft Graph root resource, your app can address OneDrive resources using the following paths:

PfadPath RessourceResource
/drives Auflisten von drive-Ressourcen, die für den authentifizierten Benutzer verfügbar sind.List drive resources available to the authenticated user.
/drives/{drive-id} Zugriff auf ein bestimmtes Laufwerk anhand seiner ID.Access a specific drive by its ID.
/drives/{drive-id}/root/children Auflisten von Elementen im Stammverzeichnis eines bestimmten Laufwerks.List items in the root of a specific drive.
/drive/items/{item-id} Zugriff auf ein driveItem-Objekt anhand seiner ID.Access a driveItem by its ID.
/drive/special/{special-id} Zugriff auf einen bekannten Ordner anhand seines bekannten Namens.Access a known folder by its known name.
/shares/{share-id} Zugriff auf ein driveItem-Objekt anhand seiner shareId oder einer URL zum Teilen.Access a driveItem by its shareId or a sharing URL.

Pfadbasierte Adressierung innerhalb eines LaufwerksPath-based addressing within a drive

Ein driveItem kann entweder durch einen eindeutigen Bezeichner oder anhand der Position, an der das Element in der Laufwerkhierarchie vorhanden ist, adressiert werden (d.h. anhand des Benutzerpfads). Innerhalb einer API-Anforderung kann ein Doppelpunkt verwendet werden, um zwischen dem API-Pfadraum und dem Benutzerpfadraum umzuschalten. Diese Syntax gilt für jedes driveItem, das über den API-Raum adressiert wird.A driveItem can be addressed by either a unique identifier or where that item exists in the drive's hierarchy (i.e. user path). Within an API request, a colon can be used to shift between API path space and user path space. This syntax is valid for any driveItem addressed via the API space.

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.You can also transition back to API path space by using a colon at the end of the file system path space. Ensure user data within the URL follows the addressing and path encoding requirements.

PfadPath RessourceResource
/drive/root:/path/to/file Zugriff auf ein driveItem-Objekt anhand des Pfads unter dem Stamm.Access a driveItem by path under the root.
/drive/items/{item-id}:/path/to/file Zugriff auf ein driveItem-Objekt über seinen Pfad relativ zu einem anderen Element.Access a driveItem by its path relative to another item.
/drive/root:/path/to/folder:/children Auflisten von untergeordneten Elementen beim Zugriff anhand des Pfads relativ zum Laufwerkstamm.List children when accessing by path relative to the drive root.
/drive/items/{item-id}:/path/to/folder:/children Auflisten von untergeordneten Elementen beim Zugriff anhand des Pfads relativ zu einem anderen Element.List children when accessing by path relative to another item.

Geteilte Ordner und RemoteelementeShared folders and remote items

In OneDrive Personal kann ein Benutzer ein oder mehrere geteilte Elemente von einem anderen Laufwerk zu seinem eigenen OneDrive hinzufügen. Diese geteilten Elemente werden als driveItem in der children-Sammlung mit einem remoteItem-Facet angezeigt.OneDrive personal allows a user to add one or more shared items from another drive to their OneDrive. These shared items appear as a driveItem in the children collection with a remoteItem facet.

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 Mit mir geteilt zurückgegeben werden.In addition, scenarios where items are returned from outside the target drive will also include a remoteItem facet. These items may also be returned from search, recent files, shared with me.

Weitere Informationen zum Arbeiten mit geteilten Ordnern und Remoteelementen finden Sie unter Remoteelemente und geteilte Ordner.For more information on working with shared folders and remote items, see Remote items and shared folders.

Teilen und BerechtigungenSharing and permissions

Eine der am häufigsten verwendeten Aktionen für OneDrive und SharePoint besteht im Teilen von Inhalten mit anderen Personen. Über OneDrive kann Ihre App Links zum Teilen erstellen, Berechtigungen hinzufügen und Einladungen an Elemente senden, die auf einem Laufwerk gespeichert sind.One of the most common actions for OneDrive and SharePoint is sharing items with other people. OneDrive allows your app to create sharing links, add permissions, and send invitations to items stored in a drive.

OneDrive bietet der App auch eine Möglichkeit, Zugriff auf geteilte Inhalte direkt über den Link zum Teilen zu erhalten.OneDrive also provides a way for your app to access shared content directly from the sharing link.

Weitere Details zum Teilen und Nutzen von geteilten Inhalten finden Sie unter Teilen von Elementen in OneDrive.For more details on how to share and consume shared content, see Sharing items in OneDrive.

Webhooks und BenachrichtigungenWebhooks and notifications

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.OneDrive supports sending webhook-style push notifications when the contents of a OneDrive is changed. Your app can use these notifications to track changes in near real-time instead of polling the server for changes.

Hinweise zur ProgrammierungProgramming notes

API-KompatibilitätAPI compatibility

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.OneDrive will continue to evolve and gain additional functionality. The API path includes a version number to protect your app against breaking changes. When a breaking change is required, the API version number will be incremented. Existing apps calling the original version number will remain unaffected by the change. See the Microsoft Graph support policy for information about how long a version of the API is supported.

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.A breaking change is a change in the format of a request or response that removes or alters an existing documented behavior or removes an element of a resource's definition. It is not a breaking change to add additional actions, properties, facets, or references to a resource.

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.It is possible that the API will expose additional undocumented features from time to time. These features should not be utilized until they are documented. Do not assume that current behavior that deviates from the documentation will persist.

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:We will continue to make non-breaking changes to the existing version of the API, including adding facets, properties, and resources to the API. As such, any code calling the API needs to:

  • Er muss stabil sein, während zusätzliche Eigenschaften zu JSON-Antworten hinzugefügt werden. Er kann ignoriert werden.Be resilient to additional properties being added to JSON responses. Ignoring them is OK.
  • Er ist nicht von der Reihenfolge der Eigenschaften abhängig, die in JSON-Antworten zurückgegeben werden.Have no dependency on the order of properties returned in JSON responses.
  • Er darf nur dokumentierte API-Pfade, Ressourcen, Eigenschaften und Aufzählungswerte verwenden. Bei nicht dokumentierten Werten kann nicht garantiert werden, dass diese konsistent bleiben.Use documented API paths, resources, properties, and enumerated values only. Non-documented values are not guaranteed to remain consistent.
  • 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.All URLs returned by OneDrive API should be treated as opaque URLs. Your app should not make any assumptions about format or parameters in these URLs. They are subject to change without notice.

DrosselungThrottling

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.OneDrive has limits in place to make sure that individuals and apps do not adversely affect the experience of other users. When an activity exceeds OneDrive's limits, API requests will be rejected for a period of time. OneDrive may also return a Retry-After header with the number of seconds your app should wait before sending more requests.

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

Arbeiten mit OneNote-NotizbüchernWorking with OneNote Notebooks

Hinweis: In OneDrive werden zwar OneNote-Notizbücher gespeichert, Sie sollten jedoch die OneDrive-API nicht verwenden, um mit OneNote-Notizbüchern zu arbeiten.Note: Although OneDrive stores OneNote notebooks, you shouldn't use the OneDrive API to work with OneNote notebooks. Verwenden Sie stattdessen die OneNote-API.Instead, use the OneNote API.

Kontinuierliche DokumentationsüberprüfungContinuous documentation validation

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.As part of our commitment to high quality documentation, we've developed a process through which the samples and examples in our documentation are tested for validity as part of every check-in. We call this continuous documentation validation.

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.Each time a change to our documentation is made, we validate that everything works as documented in the service. When we create a new build of the service, we validate that the examples in our documentation also continue to work. This helps us ensure that everything we document works and works as expected even as new updates are made available.

Sehen Sie sich die AppVeyor-Buildstatusseite für unser Dokumentationsrepository an, um Informationen zu den neuesten Builds zu erhalten.For the latest build details, check out the AppVeyor build status page for our documentation repository.

Die folgenden Themen enthalten einen allgemeinen Überblick über weitere Konzepte, die mit der OneDrive-API verbunden sind.The following topics contain high level overviews of other concepts that apply to the OneDrive API.