OneDrive et SharePoint dans Microsoft Graph
L’API REST OneDrive est une partie de l’API Microsoft Graph qui permet à votre application de se connecter au contenu stocké dans OneDrive et SharePoint. L’API REST est partagée par OneDrive, OneDrive Entreprise, les bibliothèques de documents SharePoint et les groupes Office pour permettre à votre application de lire et de stocker le contenu dans ces emplacements en utilisant le même code.
Les API REST font partie de Microsoft Graph, une API commune pour les services Microsoft.
Pour les solutions existantes qui utilisent l’API OneDrive API en dehors de Microsoft Graph ou les solutions qui ciblent SharePoint Server 2016, voir différences entre les points de terminaison directs pour lire cette documentation plus en contexte.
Prise en main
Pour expérimenter rapidement Microsoft Graph et l’accès aux fichiers, reportez-vous à l’afficheur Graph et à Démarrage rapide de Microsoft Graph.
L’API REST OneDrive fournit plusieurs types de niveau supérieur qui représentent les ressources pouvant être gérées dans l’API :
Voici un exemple de ressource driveItem.
{
"@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"
}
}
}
Les données relatives à une ressource sont fournies de trois façons :
- Les propriétés (comme id et name) exposent des valeurs simples.
- Les Facettes (comme file et photo) exposent des valeurs complexes. En général, la présence de facettes sur un élément indique les comportements ou les fonctions d’un élément et les propriétés associées.
- Les Références (comme enfants) renvoient aux collections d’autres ressources.
De nombreuses requêtes peuvent être adaptées pour inclure des données supplémentaires ou supprimer des propriétés inutilisées dans les réponses. OneDrive utilise des paramètres de requête facultatifs pour activer cette fonctionnalité. Dans la documentation, chaque requête fournit davantage de contexte relativement aux paramètres pris en charge.
Par défaut, la plupart des propriétés et des facettes sont renvoyées alors que toutes les références sont masquées. Pour gagner en efficacité, nous vous recommandons de spécifier select et expand pour les données qui vous intéressent.
Pour plus d’informations sur les ressources et les facettes, voir Ressources et Facettes.
Ressources racine de Microsoft Graph
Dans Microsoft Graph, la fonctionnalité OneDrive est disponible à partir de plusieurs ressources racine. Ces ressources correspondent à l’emplacement où les bibliothèques de documents OneDrive et SharePoint sont disponibles dans Office 365. Les entités suivantes de Microsoft Graph peuvent contenir un ou plusieurs lecteurs :
| Entité | Exemple de chemin d’accès |
|---|---|
| User | /v1.0/users/{id} ou /v1.0/me |
| Group | /v1.0/groups/{id} |
| Site | /v1.0/sites/{id} |
Ressources racine de OneDrive
Lors de l’adressage d’une ressource de racine Microsoft Graph, votre application peut adresser des ressources OneDrive à l’aide des chemins suivants :
| Chemin | Ressource |
|---|---|
/drives |
Répertorier les ressources drive disponibles pour l’utilisateur authentifié. |
/drives/{drive-id} |
Accéder à un lecteur (drive) spécifique par son ID. |
/drives/{drive-id}/root/children |
Répertorier les éléments situés à la racine d’un lecteur drive spécifique. |
/drive/items/{item-id} |
Accéder à un objet driveItem par son ID. |
/drive/special/{special-id} |
Accéder à un dossier connu par son nom connu. |
/shares/{share-id} |
Accéder à un objet driveItem via son ID partagé (sharedId) ou une URL de partage. |
Adressage à partir du chemin d’accès au sein d’un lecteur
Un objet driveItem peut être adressé par un identificateur unique ou par sa position dans la hiérarchie du lecteur (c’est-à-dire le chemin d’accès utilisateur). Dans une requête d’API, vous pouvez utiliser un signe deux-points pour basculer entre l’espace du chemin d’accès de l’API et l’espace du chemin d’accès utilisateur. La syntaxe suivante est valide pour n’importe quel objet driveItem adressé via l’espace API.
Vous pouvez également revenir à l’espace du chemin d’accès de l’API en plaçant un signe deux-points à la fin de l’espace du chemin d’accès du système de fichiers. Assurez-vous que les données utilisateur au sein de l’URL suivent les conditions requises d’adressage et de codage des chemins d’accès.
| Chemin | Ressource |
|---|---|
/drive/root:/path/to/file |
Accéder à un objet driveItem par le chemin d’accès sous la racine. |
/drive/items/{item-id}:/path/to/file |
Accéder à un objet driveItem par son chemin d’accès relatif à un autre élément. |
/drive/root:/path/to/folder:/children |
Répertorier les enfants lors d’un accès par un chemin relatif à la racine du lecteur. |
/drive/items/{item-id}:/path/to/folder:/children |
Répertorier les enfants lors d’un l’accès par un chemin relatif à un autre élément. |
Dossiers partagés et éléments distants
Les utilisateurs personnels OneDrive peuvent ajouter à leur propre lecteur OneDrive un ou plusieurs éléments partagés à partir d’un autre lecteur.
Ces éléments partagés apparaissent comme un objet driveItem dans la collection children ayant une facette remoteItem.
En outre, les scénarios avec lesquels les éléments sont renvoyés de l’extérieur du lecteur cible incluent également une facette remoteItem. Ces éléments peuvent également être renvoyés par les objets recherche, fichiers récents, partagé avec moi.
Pour plus d’informations sur l’utilisation des dossiers partagés et des éléments distants, consultez la rubrique relative aux éléments distants et dossiers partagés.
Partage et autorisations
Le partage d’éléments avec d’autres utilisateurs et l’une des opérations les plus courantes pour OneDrive et SharePoint. OneDrive permet à votre application de créer des liens de partage, d’ajouter des autorisations et d’envoyer des invitations à des éléments stockés sur un lecteur.
OneDrive permet également à votre application d’accéder au contenu partagé directement à partir du lien de partage.
Pour plus d’informations sur le partage et l’utilisation du contenu partagé, reportez-vous à la rubrique sur le partage d’éléments dans OneDrive.
Webhooks et notifications
OneDrive prend en charge l’envoi de notifications push de type webhook lorsque le contenu d’un lecteur OneDrive est modifié. Votre application peut utiliser ces notifications pour suivre les modifications en temps quasi-réel au lieu d’interroger le serveur pour connaître les modifications.
Notes de programmation
Compatibilité de l’API
OneDrive continue à évoluer et à intégrer des fonctionnalités supplémentaires. Le chemin d’accès de l’API comprend un numéro de version permettant de protéger votre application contre les modifications avec rupture. Lorsqu’une modification avec rupture est requise, le numéro de version de l’API est incrémenté. Les applications existantes qui appellent le numéro de version d’origine ne sont pas affectées par la modification. Pour plus d’informations sur la durée de prise en charge d’une version de l’API, reportez-vous à la rubrique sur la politique de support de Microsoft Graph.
Une modification avec rupture est une modification de format d’une requête ou d’une réponse qui supprime ou modifie un comportement constaté ou supprime un élément de la définition d’une ressource. L’ajout d’actions, de propriétés, de facettes ou de références à une ressource ne constitue pas une modification avec rupture.
Il est possible que l’API présente des fonctionnalités supplémentaires ne faisant l’objet d’aucune documentation de temps à autre. Ces fonctionnalités ne doivent pas être utilisées avant d’avoir fait l’objet d’une documentation. Ne supposez pas qu’un comportement actuel qui s’écarte de la documentation va se maintenir.
En effet, nous continuons à apporter des modifications sans rupture à la version existante de l’API, notamment en y ajoutant des facettes, des propriétés et des ressources. Ainsi, tout code appelant l’API doit :
- Être résilient lorsque des propriétés supplémentaires sont ajoutées à des réponses JSON. Il est acceptable de les ignorer.
- N’avoir aucune dépendance à l’ordre des propriétés renvoyées dans les réponses JSON.
- Utiliser uniquement les chemins, ressources, propriétés et valeurs énumérées de l’API. Il n’est pas garanti que les valeurs non incluses dans la documentation demeurent cohérentes.
- Toutes les URL renvoyées par l’API OneDrive doivent être considérées comme des URL opaques. Votre application ne doit pas citer de format ou de paramètres dans ces URL. En effet, elles peuvent faire l’objet de modifications sans préavis.
Limitation
Des limites ont été définies dans OneDrive pour veiller à ce que les utilisateurs et les applications n’aient pas un impact négatif sur l’expérience d’autres utilisateurs. Lorsqu’une activité dépasse les limites de OneDrive, les requêtes de l’API sont rejetées pendant une période donnée. OneDrive peut également renvoyer un en-tête Retry-After indiquant le nombre de secondes que votre application doit attendre avant d’envoyer d’autres requêtes.
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Utilisation des blocs-notes OneNote
Remarque : OneDrive stocke les blocs-notes OneNote, mais vous ne devez pas utiliser l’API OneDrive pour travailler sur ces blocs-notes. Utilisez l’API OneNote.
Validation continue de la documentation
Dans le cadre de notre engagement à fournir une documentation de haute qualité, nous avons développé un processus qui teste la validité des exemples de notre documentation lors de chaque archivage. Nous appelons ce processus la validation continue de la documentation.
Chaque fois qu’une modification est apportée à notre documentation, nous vérifions que tout fonctionne comme indiqué dans la documentation du service. Lorsque nous créons une nouvelle version du service, nous vérifions que les exemples de notre documentation continuent également à fonctionner. Nous nous assurons ainsi que tous les éléments inclus dans la documentation fonctionnent comme prévu à chaque mise à jour mise à disposition.
Pour obtenir des détails sur les dernières versions, consultez la page d’état AppVeyor associée à notre référentiel de documentation.
Rubriques connexes
Les rubriques suivantes contiennent des aperçus généraux d’autres concepts qui s’appliquent à l’API OneDrive.