Öffnen von Dateien mit dem OneDrive File Picker JavaScript SDK v7.2
Die folgende Vorgehensweise zeigt, wie Sie das File Picker SDK in Ihre clientseitige JavaScript-Anwendung integrieren.
1. Registrieren der App
Um die OneDrive-Auswahl verwenden zu können, müssen Sie Ihre Anwendung über die Seite Azure-App Registrierungen registrieren und eine Anwendungs-ID erhalten. Außerdem müssen Sie mithilfe der Auswahl einen gültigen Umleitungs-URI für Ihre Webanwendung hinzufügen. Dies kann entweder die Seite sein, die das Auswahl-SDK hostet, oder eine von Ihnen definierte URL. Weitere Informationen finden Sie im Abschnitt zur Einrichtung.
2. Verweis auf das SDK hinzufügen
Betten Sie das OneDrive JavaScript SDK auf Ihrer Seite ein.
<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>
3. Dateiauswahl starten
Damit Dateien von OneDrive geöffnet werden können, sollte Ihre App eine Schaltfläche enthalten, um die OneDrive-Dateiauswahl programmgesteuert zu öffnen. Da durch diesen Code ein Popupfenster im Browser geöffnet wird, muss er im Rahmen einer expliziten Benutzeraktion aufgerufen werden, um zu vermeiden, dass er von einem Popupblocker blockiert wird.
Geben Sie im Rahmen der Methode OneDrive.open(...) an, wie sich die Dateiauswahl verhalten soll und wie diese über ein Optionsobjekt Ihren Code erneut aufruft.
<script type="text/javascript">
function launchOneDrivePicker(){
var odOptions = { /* ... specify the desired options ... */ };
OneDrive.open(odOptions);
}
</script>
<button onClick="launchOneDrivePicker()">Open from OneDrive</button>
Hinweis: Wenn die OneDrive-Auswahl geöffnet ist, wird ein neues Fenster mit Ihrer Seite geöffnet und das SDK verwendet eine Abfragezeichenfolge, um das Fenster an die Auswahl umzuleiten. Wenn das SDK beim Laden nicht auf Ihrer Seite vorhanden ist (beispielsweise wenn es als Reaktion auf eine Benutzerinteraktion nicht richtig geladen wird), wird die Auswahl evtl. nicht korrekt geöffnet. Sie können die erweiterte
redirectUri-Option verwenden, um das Popup zu einer Seite umzuleiten, die das SDK ohne Benutzerinteraktion lädt.
Optionen für Dateiauswahl
Sie können festlegen, wie sich die Dateiauswahl verhalten soll. Geben Sie dazu ein Objekt mit Parametern an, die das Verhalten der Auswahl steuern. Dieses Objekt enthält auch die Rückruffunktionen, wenn die Dateiauswahl fertig ist oder ein Fehler auftritt.
Beispieloptionen für die Dateiauswahl
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "query",
multiSelect: true,
advanced: {},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(error) { /* error handler */ }
}
Parameter
| Parametername | Beschreibung |
|---|---|
| clientId | Die ID der Anwendung, generiert von der App-Registrierungskonsole für Ihre Integration |
| action | Der Aktionstyp, der mit den ausgewählten Dateien durchgeführt wird. Sie können share angeben, um eine teilbare URL zu generieren, download, um eine URL mit kurzer Lebensdauer zu erhalten, über die die Inhalte der Dateien heruntergeladen werden, oder query, um Kennungen zurückzugeben, die mit der Microsoft Graph-API oder OneDrive-API verwendet werden können. |
| multiSelect | Der Standardwert lautet false. Ist dieser Wert festgelegt, kann der Benutzer nur eine einzelne Datei auswählen. true ermöglicht es dem Benutzer, mehrere Dateien auszuwählen. |
| viewType | Der Typ des Elements, das ausgewählt werden kann. Der Standardwert ist files. Sie können folders angeben, um die Auswahl nur auf Ordner zu beschränken, oder all angeben, wodurch das Auswählen sowohl von Dateien als auch von Ordnern ermöglicht wird. |
| accountSwitchEnabled | Der Standardwert lautet true; dadurch wird die Benutzeroberfläche „Konto wechseln“ auf der gehosteten Seite „Dateiauswahl“ gerendert. |
| advanced | Eine Sammlung zusätzlicher Eigenschaften, mit denen sich das Verhalten der Auswahl weiter anpassen lässt. Dies ist jedoch bei den meisten Szenarien nicht erforderlich. Weitere Informationen finden Sie unter Erweiterte Optionen . |
| success | Wird aufgerufen, wenn der Benutzer mit der Dateiauswahl fertig ist und ein Antwortobjekt übernimmt, das die Sammlung der ausgewählten Dateien enthält. Dies ist erforderlich, wenn OpenInNewWindow true lautet. |
| cancel | Wird aufgerufen, wenn der Benutzer die Dateiauswahl abbricht. Diese Funktion verwendet keine Parameter. |
| error | Wird aufgerufen, wenn ein Fehler auf dem Server aufgetreten ist oder der Benutzer keine Berechtigung hat, einen Link zu der ausgewählten Datei zu erhalten. Diese Funktion verwendet einen Parameter, und zwar ein Fehlerobjekt. |
Aktionstypen
Bei Verwendung des action-Parameters der Dateiauswahl können Sie angeben, welcher URL-Typ zurückgegeben werden soll, nachdem der Benutzer eine Datei oder einen Ordner ausgewählt hat. Folgende Werte sind gültig:
| Wert | Beschreibung |
|---|---|
download |
Gibt die ID und den Namen der Datei sowie eine kurzlebige Download-URL für die ausgewählten Dateien zurück. |
share |
Gibt eine schreibgeschützte Freigabe-URL für die ausgewählten Dateien zurück, die mit anderen Benutzern gemeinsam genutzt werden kann. |
query |
Gibt Metadaten nur für die ausgewählten Dateien zurück. Verwenden Sie die API, um zusätzliche Aktionen für die Dateien auszuführen. |
4. Behandlung des Auswahlantwort-Objekts
Wenn der Benutzer mit der Dateiauswahl fertig ist, erhält der success-Rückruf das Objekt response.
Dieses Objekt enthält Eigenschaften, u. a. value, eine Sammlung von Item-Ressourcen mit einer Teilmenge der Eigenschaften des Elements.
{
"value": [
{
"id": "123456",
"name": "document1.docx",
"size": 12340,
"@microsoft.graph.downloadUrl": "https://contoso-my.sharepoint.com/download.aspx?guid=1231231231a",
"webUrl": "https://cotoso-my.sharepoint.com/personal/user_contoso_com/documents/document1.docx",
"thumbnails": [
{
"id": "0",
"small": { "url": "https://sn3302files.onedrive.live.com/..." },
"medium": { "url": "https://sn3302files.onedrive.live.com/..." },
"large": { "url": "https://sn3302files.onedrive.live.com/..." }
}
]
}
],
"accessToken": "ey...",
"apiEndpoint": "https://graph.microsoft.com"
}
Antworteigenschaften
| Eigenschaftsname | Typ | Beschreibung |
|---|---|---|
| value | Array von driveItems | Metadaten zu den Dateien, die ausgewählt wurden |
| webUrl | Url | Wird für mehrere Auswahlszenarien von OneDrive Personal-Konten zurückgegeben. |
| accessToken | string | Der Zugriffstoken, den die Dateiauswahl für die Anwendung erhalten hat. Dieser kann verwendet werden, um weitere Anforderungen an Microsoft Graph zu senden, ohne dass ein weiterer Authentifizierungsvorgang erforderlich ist. |
| apiEndpoint | Url | Der API-Endpunkt, mit dem der accessToken verwendet werden kann. |
Erweiterte Optionen
Die Auswahl unterstützt auch zusätzliche erweiterte Szenarien. So kann die Auswahl zusammen mit der OneDrive-API verwendet werden, um erweiterte Szenarien zu realisieren.
Der erweiterte Parameter für das Optionsobjekt weist die folgenden definierten Eigenschaften auf:
| Parametername | Beschreibung | Szenarien |
|---|---|---|
| queryParameters | Eine Reihe zusätzlicher Abfrageparameter gemäß der OneDrive-API, die definieren, wie ein Element zurückgegeben wird. Dies umfasst in der Regel einen Auswahl- und/oder Erweiterungswert. | Abfragen einer Datei oder eines Ordners |
| createLinkParameters | Ändern Sie die Parameter, die verwendet werden, um einen Link für die Freigabeaktion zu generieren. | Freigeben eines Ordners |
| filter | Es können eine Reihe von Dateitypen angewendet werden, um nur die spezifischen Typen anzuzeigen. Wir unterstützen den Systemtyp 'Foto' und 'Ordner' sowie benutzerdefinierte Typen mit einer beliebigen Erweiterung wie z. B. 'DOCX'. Eine gültige Filtereinstellung ist "Ordner,.png", wobei jeder Filter durch ein , getrennt wird. |
Anzeigen von Dateien |
| redirectUri | Standardmäßig verwendet die Auswahl die Seite, von der sie aus gestartet wurde, als Umleitungs-URI für die Authentifizierung. Dies ist möglicherweise nicht in allen Szenarien wünschenswert. Deshalb können Sie eine benutzerdefinierte URL festlegen, die stattdessen verwendet wird. Diese URL muss im Registrierungsportal Ihrer App als Umleitungs-URL registriert sein. Die Zielseite muss auf das OneDrive Picker SDK auf die gleiche Weise verweisen wie die aufrufende Seite. | OAuth |
| endpointHint | Wird für die Umleitung der App zum richtigen OAuth-Endpunkt durch das SDK verwendet, je nachdem, mit welchen OneDrive-API-Endpunkten die App kommunizieren möchte. OneDrive-API-Endpunkte umfassen OneDrive Personal, OneDrive for Business oder SharePoint Online. Der Wert von endpointHint könnte api.onedrive.com für OneDrive Personal, die OneDrive for Business-URL oder die URL einer SharePoint-Dokumentbibliothek sein, z. B.
https://contoso-my.sharepoint.com/personal/foo_contoso_onmicrosoft_com/ oder https://contoso.sharepoint.com/shared%20documents/. Ist nicht erforderlich, wenn die App mit der Microsoft Graph-API kommuniziert. |
OAuth |
| accessToken | Ein accessToken, das Zugriff auf OneDrive-API-Endpunkte für oneDrive personal, OneDrive for Business oder SharePoint Online gewährt, könnte übergeben werden, überspringen Sie den OAuth-Flow, der Ihnen eine schnellere Erfahrung bietet.
endpointHint ist erforderlich, wenn ein accessToken angezeigt wird. |
OAuth |
| loginHint | Wenn sich ein Benutzer zuvor bei Ihrer Anwendung angemeldet hat, können Sie einen loginHint-Wert angeben, der das einmalige Anmelden aktiviert. | OAuth |
| isConsumerAccount | Wenn die Kommunikation mit der Microsoft Graph-API erfolgt und loginHint angegeben ist, erfordert das SDK außerdem, dass die App mitteilt, ob es sich bei dem angemeldeten Benutzer um ein Consumer-Konto (bzw. Microsoft-Konto) oder ein Business-Konto handelt. |
OAuth |
| scopes | Das SDK fordert automatisch den Bereich Files.Read.All zum Öffnen und den Bereich Files.ReadWrite.All zum Speichern an. Wenn Sie jedoch zusätzliche Berechtigungen anfordern möchten, können Sie hier weitere Bereiche hinzufügen. |
OAuth |
| navigation | Mit Picker SDK 7.2 wurde die neue Benutzeroberfläche für die Auswahl eingeführt, die mehrere Konfigurationen ermöglicht. Alle Konfigurationen befinden sich unter dem navigationObjekt. |
Benutzeroberfläche der Auswahl |
Hinweis: Der Filtertyp 'Foto' wird derzeit nur für OneDrive Personal-Konten unterstützt.
Gemeinsame Verwendung von Auswahl und API
Sie können den action-Wert query zusammen mit der Einstellung queryParameters des erweiterten Objekts verwenden, um benutzerdefinierte Eigenschaften der API über das ausgewählte Objekt zurückzugeben.
Zum Beispiel bei Auswahl einer Datei zum Einschließen von Fotodetails (sofern verfügbar):
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "query",
multiSelect: false,
advanced: {
queryParameters: "select=id,name,size,file,folder,photo,@microsoft.graph.downloadUrl",
filter: "folder,.png" /* display folder and files with extension '.png' only */
},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(error) { /* error handler */ }
}
Dies teilt dem Auswahl-SDK mit, dass folgende Eigenschaften in der Antwort ausgewählt werden sollen: id, name, size, file, folder und photo.
Zurückgeben eines Freigabe-Firmenlinks mit Lese-/ Schreibzugriff
Standardmäßig gibt die OneDrive-Dateiauswahl eine schreibgeschützte Freigabe-URL zurück, wenn action auf share festgelegt ist.
Sie können jedoch die Eigenschaft "createLinkParameters" verwenden, um die Parameter zu ändern, die an die Aktion createLink übergeben werden.
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "share",
multiSelect: false,
advanced: {
createLinkParameters: { type: "edit", scope: "organization" }
},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(error) { /* error handler */ }
}
Verwenden eines benutzerdefinierten Umleitungs-URI
Wenn Ihre App eine umfangreiche clientseitige JavaScript-Anwendung ist oder Abfragezeichenfolgeparameter verwendet, um den Status zu verwalten, ist es unter Umständen nicht wünschenswert, die Seite als Umleitungs-URI zu verwenden, von der die Dateiauswahl gestartet wird. Dies erfordert, dass Ihre gesamte App innerhalb des Popup-Fensters geladen wird, was allerdings Leistungsprobleme verursachen kann. Sie können über das erweiterte Objekt einen alternativen Umleitungs-URI angeben, der stattdessen verwendet wird.
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "download",
advanced: {
redirectUri: "https://contoso.com/filePickerRedirect.htm"
},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(error) { /* error handler */ }
}
Verwenden von alternativen API-Endpunkten
Die Microsoft Graph-API bietet einen einheitlichen Zugriff auf Dateien, die in OneDrive Personal, OneDrive for Business und SharePoint Online gespeichert sind. Unter gewissen Umständen kann es jedoch erforderlich sein, eine spezifische SharePoint-Website-URL statt Microsoft Graph zu verwenden.
In diesem Fall kann die App den OneDrive-API-Endpunkt für die SharePoint-Website anstelle des Microsoft Graph-API-Endpunkts angeben. Das OneDrive Picker SDK sorgt für eine Umleitung zum richtigen OAuth-Endpunkt, damit ein Zugriffstoken abgerufen werden kann. Die Zuordnung zwischen den OneDrive-API-Endpunkten und der OAuth-Stelle lautet:
Umleitung zum MSA-OAuth-Endpunkt
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "query",
advanced: {
endpointHint: "api.onedrive.com",
},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(error) { /* error handler */ }
}
Direkte Umleitung zur Dokumentbibliothek; die App steuert den OAuth-Ablauf an anderer Stelle
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "download",
advanced: {
endpointHint: "https://contoso.sharepoint.com/shared%20documents/",
accessToken "INSERT-ACCESS-TOKEN-HERE"
},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(error) { /* error handler */ }
Die Seite, zu der Sie umleiten, muss nur das OneDrive SDK-Skript laden:
<html>
<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>
</html>
Anpassen von Funktionen
Die Dateiauswahl ermöglicht es den Benutzern zwar, Dateien von Office 365 auszuwählen (einschließlich OneDrive und SharePoint-Dokumentbibliotheken), ggf. möchten Sie aber die Quelle einschränken, von der eine Datei geöffnet werden kann. Sie können diese Eigenschaften verwenden, um die Funktionen auf jene einzuschränken, die Sie aktivieren möchten:
| Parametername | Beschreibung |
|---|---|
| disable | Wenn dieser Wert festgelegt ist, wird das Navigationsfenster nicht angezeigt. |
| entryLocation | Legen Sie die Dokumentbibliothek fest, die auf der OneDrive-Auswahloberfläche dargestellt werden soll. |
| sourceTypes | Dateiquellen, von denen der Benutzer im Navigationsbereich auswählen kann. |
Die App könnte sourceTypes wie OneDrive, Recent, Sites oder mehrere Quellen in einem Array [`OneDrive`, `Recent`] angeben. Die App könnte auch einen benutzerdefinierten Eingabeort anstelle des standardmäßigen Eingabeortes angeben (durch Angabe des Objekts entryLocation). Der benutzerdefinierte Eingabeort ist auf eine SharePoint-Dokumentbibliothek beschränkt. Der Standardeingabeort ist das OneDrive for Business des Benutzers.
var odOptions = {
clientId: "INSERT-APP-ID-HERE",
action: "download",
advanced: {
navigation: {
entryLocation: {
sharePoint: {
sitePath: "THE-SITE-PATH",
listPath: "THE-LIST-PATH",
itemPath: "THE-ITEM-PATH"
}
},
sourceTypes: "Sites" /* or an array like ["OneDrive", "Sites"] */
}
},
success: function(files) { /* success handler */ },
cancel: function() { /* cancel handler */ },
error: function(error) { /* error handler */ }