OneDrive y SharePoint en Microsoft Graph
La API de REST de OneDrive es una parte de la API de Microsoft Graph que permite que su aplicación se conecte al contenido almacenado en OneDrive y SharePoint. La API de REST se comparte entre las bibliotecas de documentos de OneDrive, OneDrive para la Empresa y SharePoint, y los grupos de Office, para permitir que su aplicación tenga flexibilidad para leer y almacenar contenido en cualquiera de estas ubicaciones con el mismo código.
Las API de REST forman parte de Microsoft Graph, una API común de los servicios Microsoft.
Para soluciones existentes que usen la API de OneDrive fuera de Microsoft Graph o soluciones que se dirijan a SharePoint Server 2016, vea direct endpoint differences (diferencias de los puntos de conexión directos) para obtener más información al leer esta documentación.
Introducción
Para experimentar rápidamente con Microsoft Graph y tener acceso a los archivos, consulte el Probador de Graph y el Inicio rápido de Microsoft Graph.
La API de REST de OneDrive proporciona algunos tipos de nivel superior que representan los recursos que pueden tratarse en la API:
A continuación se muestra un ejemplo de un recurso 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"
}
}
}
Los datos sobre un recurso se proporcionan de tres maneras:
- Propiedades (como id y name) exponen valores simples.
- Facetas (como file y photo) exponen valores complejos. La presencia de facetas en un elemento indica normalmente comportamientos o capacidades de un elemento y propiedades relacionadas.
- Referencias (como children) indican colecciones de otros recursos.
Pueden adaptarse muchas solicitudes para incluir datos o quitar propiedades sin usar de las respuestas. OneDrive usa parámetros de consulta opcionales para habilitar esta función. En la documentación, cada solicitud proporciona más contexto sobre qué parámetros se admiten.
De manera predeterminada, la mayoría de las propiedades y las facetas se devuelve mientras que todas las referencias se ocultan. Por motivos de eficacia, recomendamos que especifique seleccionar y expandir en los datos que le interesen.
Para obtener información sobre los recursos y facetas, vea Recursos y Facetas.
Recursos raíz de Microsoft Graph
Dentro de Microsoft Graph, las funciones de OneDrive están disponibles desde varios recursos raíz. Estos recursos corresponden al lugar donde las bibliotecas de documentos de SharePoint y OneDrive están disponibles en Office 365. Las siguientes entidades de Microsoft Graph pueden contener una o más unidades:
| Entidad | Ruta de acceso de ejemplo |
|---|---|
| User |
/v1.0/users/{id} o /v1.0/me |
| Group | /v1.0/groups/{id} |
| Site | /v1.0/sites/{id} |
Recursos raíz de OneDrive
Al indicar un recurso raíz de Microsoft Graph, la aplicación puede indicar recursos de OneDrive con las siguientes rutas de acceso:
| Ruta de acceso | Resource |
|---|---|
/drives |
Muestra los recursos drive disponibles para el usuario autenticado. |
/drives/{drive-id} |
Acceso a una unidad específica mediante su identificador. |
/drives/{drive-id}/root/children |
Muestra los elementos de la raíz de una unidad específica. |
/drive/items/{item-id} |
Acceso a driveItem mediante su identificador. |
/drive/special/{special-id} |
Acceso a una carpeta conocida mediante su nombre conocido. |
/shares/{share-id} |
Acceso a driveItem mediante su shareId o una dirección URL para compartir. |
Direccionamiento basado en la ruta de acceso en una unidad
Puede dirigirse a un objeto driveItem mediante un identificador único o donde ese elemento exista en la jerarquía de la unidad (es decir, la ruta de acceso de usuario). En una solicitud de API, pueden usarse dos puntos para cambiar entre el espacio de la ruta de API y el espacio de la ruta de usuario. La sintaxis es válida para cualquier driveItem al que se haga referencia mediante el espacio de API.
También puede volver al espacio de ruta de API usando dos puntos al final del espacio de ruta del sistema de archivos. Asegúrese de que los datos de usuario dentro de la dirección URL siguen los requisitos de direccionamiento y codificación de la ruta de acceso.
| Ruta de acceso | Resource |
|---|---|
/drive/root:/path/to/file |
Acceso a driveItem mediante la ruta de acceso debajo de la raíz. |
/drive/items/{item-id}:/path/to/file |
Acceso a driveItem mediante su ruta de acceso relativa a otro elemento. |
/drive/root:/path/to/folder:/children |
Muestra los elementos secundarios al tener acceso mediante la ruta de acceso relativa a la raíz de la unidad. |
/drive/items/{item-id}:/path/to/folder:/children |
Muestra los elementos secundarios al tener acceso mediante la ruta de acceso relativa a otro elemento. |
Carpetas compartidas y elementos remotos
OneDrive Personal permite que un usuario agregue uno o más elementos compartidos desde otra unidad a su OneDrive.
Estos elementos compartidos aparecen como un driveItem en la colección children con una faceta remoteItem.
Además, los escenarios donde los elementos se devuelven desde fuera de la unidad de destino también incluirán una faceta remoteItem. Estos elementos también pueden devolverse desde búsqueda, archivos recientes, compartidos conmigo.
Para obtener más información sobre cómo trabajar con carpetas compartidas y objetos remotos, vea Elementos remotos y carpetas compartidas.
Uso compartido y permisos
Una de las acciones más comunes en OneDrive y SharePoint es compartir elementos con otras personas. OneDrive permite que su aplicación pueda crear vínculos para compartir, agregar permisos y enviar invitaciones a los elementos almacenados en una unidad.
OneDrive también permite que su aplicación pueda tener acceso a contenido compartido directamente desde el vínculo para compartir.
Para obtener más información sobre cómo compartir y consumir contenido compartido, vea Sharing items in OneDrive (Compartir elementos en OneDrive).
Webhooks y notificaciones
OneDrive admite el envío de notificaciones de inserción de estilo webhook cuando se cambia el contenido de un OneDrive. La aplicación puede usar estas notificaciones para realizar un seguimiento de los cambios prácticamente en tiempo real en lugar de sondear el servidor para obtener los cambios.
Notas de programación
Compatibilidad de API
OneDrive seguirá evolucionando y obteniendo funciones adicionales. La ruta de acceso de la API incluye un número de versión para proteger su aplicación de cambios importantes. Cuando se necesita un cambio importante, el número de versión de la API se incrementará. Las aplicaciones existentes que llamen al número de versión original no se verán afectadas por el cambio. Vea la directiva de compatibilidad de Microsoft Graph para obtener información sobre la duración de compatibilidad de una versión de la API.
Un cambio importante es un cambio con el formato de una solicitud o respuesta que quita o modifica un comportamiento documentado existente o quita un elemento de una definición de recurso. No es un cambio importante agregar acciones adicionales, propiedades, facetas o referencias a un recurso.
Es posible que la API exponga características adicionales sin documentar de vez en cuando. Estas características no deben usarse hasta que estén documentadas. No presuponga que el comportamiento actual que se desvía de la documentación continuará.
Seguiremos realizando cambios sin importancia en la versión existente de la API, incluida la adición de facetas, propiedades y recursos a la API. Por lo tanto, cualquier código que llame a la API necesita:
- Adaptarse a las propiedades adicionales que se agreguen a las respuestas JSON. Pueden ignorarse.
- No tener ninguna dependencia en el orden de propiedades devueltas en las respuestas JSON.
- Usar solo valores enumerados, propiedades, recursos y rutas de API documentadas. No se garantiza que los valores no documentados sean coherentes.
- Todas las direcciones URL devueltas por la API de OneDrive deben tratarse como direcciones URL opacas. Su aplicación no debe realizar ninguna suposición sobre el formato o los parámetros de estas direcciones URL. Están sujetas a cambios sin previo aviso.
Limitación
OneDrive tiene límites vigentes para garantizar que las personas y las aplicaciones no afectan de manera negativa a la experiencia de otros usuarios. Cuando una actividad supera los límites de OneDrive, las solicitudes de API se rechazarán durante un período de tiempo. OneDrive también puede devolver un encabezado Retry-After con el número de segundos que su aplicación debe esperar antes de enviar más solicitudes.
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
Trabajar con blocs de notas de OneNote
Nota: Aunque OneDrive almacena blocs de notas de OneNote, no debe usar la API de OneDrive para trabajar con ellos. En su lugar, use la API de OneNote.
Validación continua de documentación
Como parte de nuestro compromiso de ofrecer una documentación de alta calidad, hemos desarrollado un proceso a través del cual se prueban los ejemplos de nuestra documentación para ver su validez como parte de cada comprobación. Denominamos a esto validación continua de documentación.
Cada vez que se realiza un cambio en nuestra documentación, validamos que todo funcione como se ha documentado en el servicio. Cuando creamos una nueva compilación del servicio, validamos que los ejemplos de nuestra documentación también sigan funcionando. Esto nos ayuda a garantizar que todo lo que documentamos funciona y que lo hace según lo esperado, incluso cuando existen nuevas actualizaciones.
Para obtener la información de compilación más reciente, vea la página de estado de compilación de AppVeyor para nuestro repositorio de documentación.
Temas relacionados
En los temas siguientes se incluye información general de alto nivel de otros conceptos que se aplican a la API de OneDrive.