Ouverture des fichiers avec le Kit de développement logiciel (SDK) JavaScript du sélecteur de fichiers OneDrive v7.2
La procédure suivante explique comment intégrer le Kit de développement logiciel (SDK) du sélecteur de fichiers à votre application JavaScript côté client.
1. Inscription de votre application
Pour utiliser le sélecteur OneDrive, vous devez inscrire votre application via la page d’inscriptions Azure App et recevoir un ID d’application. Vous devez également ajouter un URI de redirection valide pour votre application web à l’aide du sélecteur. Cela peut être la page qui héberge le Kit de développement logiciel (SDK) du sélecteur ou une URL personnalisée que vous définissez. Pour plus d’informations, consultez la rubrique Configuration.
2. Ajouter une référence au Kit de développement logiciel (SDK)
Incorporez le Kit de développement logiciel (SDK) JavaScript OneDrive dans votre page.
<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>
3. Lancer le sélecteur de fichiers
Pour ouvrir les fichiers à partir de OneDrive, votre application doit fournir un bouton pour ouvrir le sélecteur de fichiers OneDrive, par programme. Étant donné que ce code ouvre une fenêtre contextuelle dans le navigateur, il doit être appelé dans le cadre d’une action utilisateur explicite pour éviter tout blocage par un bloqueur de fenêtre contextuelle.
Dans le cadre de la méthode OneDrive.open(...), vous spécifiez les options pour le comportement du sélecteur et la façon dont le sélecteur rappellera votre code via un objet options.
<script type="text/javascript">
function launchOneDrivePicker(){
var odOptions = { /* ... specify the desired options ... */ };
OneDrive.open(odOptions);
}
</script>
<button onClick="launchOneDrivePicker()">Open from OneDrive</button>
Remarque : lorsque le sélecteur de OneDrive est ouvert, une nouvelle fenêtre avec votre page s’ouvrira et le SDK utilisera une chaîne de requête pour rediriger la fenêtre vers le sélecteur d’environnement. Si le SDK n’est pas présent sur votre page de chargement (s’il s’agit d’une extraction chargée en réponse à une interaction de l’utilisateur, par exemple), le sélecteur d’environnement ne s’ouvrent pas correctement. Vous pouvez souhaiter utiliser l’
redirectUrioption avancée pour rediriger la fenêtre contextuelle vers une page qui charge SDK sans intervention de l’utilisateur.
Options du sélecteur
Vous pouvez spécifier le comportement du sélecteur de fichiers à l’aide d’un objet avec des paramètres qui contrôlent le comportement du sélecteur. Cet objet inclut également les fonctions de rappel pour le moment où le sélecteur de fichiers est terminé ou rencontre une erreur.
Options de sélecteur de fichiers exemple
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 */ }
}
Paramètres
| Nom du paramètre | Description |
|---|---|
| clientId | L’ID de l’application généré par la console d’inscription de l’application pour votre intégration. |
| action | Le type d’action effectuée avec les fichiers sélectionnés. Vous pouvez spécifier share pour générer une URL partageable, download pour recevoir une URL de courte durée qui télécharge le contenu des fichiers, ou query pour renvoyer des identificateurs qui peuvent être utilisés avec l’API Microsoft Graph ou l’API OneDrive. |
| multiSelect | La valeur par défaut est false, ce qui exige que l’utilisateur sélectionne un seul fichier, ou true afin de permettre à l’utilisateur de sélectionner plusieurs fichiers. |
| viewType | Le type d’élément pouvant être sélectionné. La valeur par défaut est files. Vous pouvez spécifierfolderspour limiter la sélection uniquement aux dossiers ou spécifier all qui autorise la sélection desdeux fichiers et dossiers. |
| accountSwitchEnabled | La valeur par défaut est true, qui fournit l’option d’interface utilisateur « Changer de compte » sur la page du sélecteur de fichiers hébergée. |
| advanced | Un ensemble de propriétés supplémentaires qui peuvent personnaliser davantage le comportement du sélecteur mais qui ne sont pas nécessaires pour la plupart des scénarios. Consultez la rubrique Options avancées pour plus d’informations. |
| success | Appelé lorsque l’utilisateur termine de sélectionner des fichiers et prend un objet response qui inclut la collection de fichiers sélectionnés. Ce paramètre est obligatoire si openInNewWindow est true. |
| cancel | Appelé si l’utilisateur annule le sélecteur. Cette fonction n’utilise aucun paramètre. |
| error | Appelé lorsqu’une erreur s’est produite sur le serveur ou que l’utilisateur n’est pas autorisé à obtenir un lien vers le fichier choisi. Cette fonction utilise un paramètre, un objet error. |
Types d’actions
Utilisez le paramètreaction du sélecteur pour spécifier le type d’URL qui doit être renvoyé une fois que l’utilisateur a sélectionné un fichier ou un dossier. Les valeurs suivantes sont autorisées :
| Valeur | Description |
|---|---|
download |
Renvoie l’ID du fichier, son nom et une URL de téléchargement de courte durée pour les fichiers sélectionnés. |
share |
Renvoie une URL de partage en lecture seule pour les fichiers sélectionnés qui peut être partagée avec d’autres utilisateurs. |
query |
Renvoie les métadonnées uniquement pour les fichiers sélectionnés. Utilisez l’API pour effectuer des actions supplémentaires sur les fichiers en conséquence. |
4. Gestion de l’objet response du sélecteur
Lorsque l’utilisateur a terminé de sélectionner les fichiers, le rappel success reçoit l’objet response.
Cet objet contient des propriétés, inclut la propriété value qui est une collection de Item resource avec un sous-ensemble des propriétés de l’élément.
{
"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"
}
Propriétés response
| Nom de la propriété | Type | Description |
|---|---|---|
| value | Tableau d’éléments driveItem | Métadonnées sur les fichiers qui ont été sélectionnés. |
| webUrl | Url | Renvoyée pour plusieurs scénarios de sélection à partir de comptes OneDrive Personnel. |
| accessToken | chaîne | Le jeton d’accès reçu par le sélecteur de fichiers pour votre application. Il peut être utilisé pour effectuer d’autres demandes à Microsoft Graph sans avoir besoin d’un autre flux d’authentification. |
| apiEndpoint | Url | Le point de terminaison de l’API avec lequel le jeton accessToken peut être utilisé. |
Options avancées
Le sélecteur prend également en charge des scénarios avancés supplémentaires. Ceci permet d’utiliser le sélecteur avec l’API OneDrive pour accomplir des scénarios avancés.
Le paramètre avancé sur l’objet options a les propriétés définies suivantes :
| Nom du paramètre | Description | Scénarios |
|---|---|---|
| queryParameters | Un ensemble de paramètres de requête supplémentaires tel que spécifié par l’API OneDrive qui définissent la façon dont un élément est renvoyé. En règle générale, cela inclut une valeur select et/ou expand. | Interroger un fichier ou un dossier |
| createLinkParameters | Modifiez les paramètres utilisés pour générer un lien pour l’action de partage. | Partager un fichier |
| filter | Un ensemble de types de fichiers peut être appliqué pour afficher uniquement les types spécifiques. Nous prenons en charge le type de système « photo » et « dossier » et les types personnalisés de n’importe quelle extension comme « .docx ». Un paramètre de filtre applicable est « dossier, .png » où chaque filtre est séparé par une ,. |
Afficher des fichiers |
| redirectUri | Par défaut, le sélecteur utilise la page à partir de laquelle il a été lancé comme l’uri de redirection pour l’authentification. Ce n’est pas forcément souhaitable dans tous les scénarios, donc vous pouvez définir une URL personnalisée à utiliser à la place. Cette URL doit être enregistrée sur le portail d’inscription de votre application comme URL de redirection. La page cible doit référencer le Kit de développement logiciel (SDK) du sélecteur OneDrive de la même manière que la page appelante. | OAuth |
| endpointHint | endpointHint est utilisé pour que le Kit de développement logiciel (SDK) redirige l’application vers le point de terminaison OAuth correct en fonction des points de terminaison API OneDrive avec lesquels l’application souhaite communiquer. Les points de terminaison de l’API OneDrive incluent OneDrive Personnel, OneDrive Entreprise ou SharePoint Online. La valeur de endpointHint pourrait être api.onedrive.com pour l’URL OneDrive Personnel, OneDrive Entreprise ou une URL de bibliothèque de documents SharePoint, par exemple,
https://contoso-my.sharepoint.com/personal/foo_contoso_onmicrosoft_com/ ou https://contoso.sharepoint.com/shared%20documents/. Ce n’est pas obligatoire si l’application communique avec l’API Microsoft Graph. |
OAuth |
| accessToken | Un jeton accessToken ayant octroyé l’accès aux points de terminaison de l’API OneDrive pour OneDrive Personnel, OneDrive Entreprise ou SharePoint Online peut être transmis et ignorer le flux OAuth, ce qui vous offre une expérience plus rapide.
endpointHint est requis si un jeton accessToken est présenté. |
OAuth |
| loginHint | Si un utilisateur s’est connecté précédemment à votre application, vous pouvez fournir une valeur loginHint qui permettra l’authentification unique. | OAuth |
| isConsumerAccount | Lors de communications avec l’API Microsoft Graph et le loginHint spécifié, le Kit de développement logiciel (SDK) exige également que l’application indique que l’utilisateur connecté est un compte client (c’est-à-dire, un compte Microsoft) ou un compte professionnel. |
OAuth |
| scopes | Le Kit de développement logiciel (SDK) demandera automatiquement l’étendue Files.Read.All pour les flux d’ouverture, et l’étendue Files.ReadWrite.All pour les flux d’enregistrement. Toutefois, si vous souhaitez demander des autorisations supplémentaires, vous pouvez ajouter des étendues supplémentaires ici. |
OAuth |
| navigation | Dans le Kit de développement logiciel (SDK) du sélecteur 7.2, nous avons introduit une nouvelle interface utilisateur du sélecteur dont les multiples configurations peuvent être définies. Toutes les configurations sont sous l’objet navigation. |
Interface utilisateur du sélecteur |
Remarque : Le type de filtre « photo » actuel est pris en charge uniquement pour les comptes de OneDrive Personnel.
Utilisation conjointe de l’API et du sélecteur
Vous pouvez utiliser la valeur actionquery avec le paramètre queryParameters de l’objet avancée pour renvoyer un jeu personnalisé de propriétés à partir de l’API sur l’objet sélectionné.
Par exemple, lorsqu’un fichier est sélectionné, pour inclure des détails de photo (le cas échéant) :
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 */ }
}
Cela indique au Kit de développement logiciel (SDK) du sélecteur de sélectionner les propriétés id, name, size, file, folder et photo dans la réponse.
Renvoi d’un lien partageable de la société en lecture-écriture
Par défaut, le sélecteur de fichiers OneDrive renvoie une URL de partage en lecture seule lorsque action est définie sur share.
Toutefois, vous pouvez utiliser la propriété createLinkParameters pour modifier les paramètres transmis à createLink action.
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 */ }
}
Utilisation d’un URI de redirection personnalisé
Si votre application est une application JavaScript côté client volumineuse ou qu’elle utilise des paramètres de chaîne de requête pour gérer l’état, il peut être préférable de ne pas utiliser la page de lancement du sélecteur de fichiers comme URI de redirection. Ceci exige que votre application entière soit rechargée à l’intérieur de la fenêtre contextuelle, ce qui peut provoquer des problèmes de performances. Vous pouvez spécifier un autre URI de redirection via l’objet avancé qui est utilisé à la place.
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 */ }
}
Utilisation de points de terminaison d’API différents
L’API Microsoft Graph fournit un accès unifié aux fichiers stockés sur OneDrive Personnel, OneDrive Entreprise et SharePoint Online. Toutefois, dans certains scénarios limités, il peut être nécessaire d’utiliser une URL de site SharePoint spécifique au lieu de Microsoft Graph.
Dans ce cas, l’application peut spécifier le point de terminaison de l’API OneDrive pour le site SharePoint à la place du point de terminaison de l’API Microsoft Graph. Le Kit de développement logiciel (SDK) du sélecteur OneDrive effectue une redirection vers le point de terminaison OAuth correct pour obtenir un jeton d’accès. Le mappage entre les points de terminaison de l’API OneDrive et l’autorité OAuth est le suivant :
| Point de terminaison de l’API | Point de terminaison de l’autorité OAuth | endpointHint |
|---|---|---|
| https://graph.microsoft.com/v1.0/ | https://login.microsoftonline.com/common/oauth2/v2.0/authorize | N/D |
| https://api.onedrive.com/v1.0/ | https://login.live.com/oauth20_authorize.srf | https://api.onedrive.com |
| https://contoso-my.sharepoint.com/personal/ryan_contoso_com/ | https://login.microsoftonline.com/common/oauth2/authorize | https://contoso-my.sharepoint.com/personal/ryan_contoso_com/ |
Redirige vers le point terminaison OAuth MSA
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 */ }
}
Redirige directement vers la bibliothèque de documents, et l’application contrôle le flux OAuth à un autre emplacement.
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 */ }
La page vers laquelle est effectuée la redirection doit uniquement charger le script du Kit de développement logiciel (SDK) OneDrive :
<html>
<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>
</html>
Personnaliser des fonctionnalités
Le sélecteur de fichiers permet aux utilisateurs de sélectionner des fichiers dans Office 365, notamment des bibliothèques de documents OneDrive et SharePoint, mais vous pouvez limiter la source à partir de laquelle un fichier peut être ouvert. Vous pouvez utiliser ces propriétés pour limiter les fonctionnalités uniquement à celles que vous souhaitez activer :
| Nom du paramètre | Description |
|---|---|
| disable | Si la valeur est définie, le volet de navigation n’est pas visible. |
| entryLocation | Définit la bibliothèque de documents affichée dans l’interface utilisateur du sélecteur OneDrive. |
| sourceTypes | Sources de fichiers que l’utilisateur peut sélectionner dans le volet de navigation. |
L’application peut spécifier sourceTypes comme OneDrive, Recent, Sites ou plusieurs sources dans un tableau [`OneDrive`, `Recent`]. L’application peut aussi spécifier un emplacement d’entrée personnalisé à la place de l’emplacement par défaut en spécifiant l’objet entryLocation. L’emplacement d’entrée personnalisé est limité à une bibliothèque de documents SharePoint. L’emplacement d’entrée par défaut est le OneDrive Entreprise de l’utilisateur.
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 */ }