OneDrive y SharePoint en Microsoft GraphOneDrive and SharePoint in Microsoft Graph

Estado de compilación y validación de la documentaciónDocumentation validation and build status

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.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. 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.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.

Las API de REST forman parte de Microsoft Graph, una API común de los servicios Microsoft.These REST APIs are a part of the Microsoft Graph, a common API for Microsoft services.

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.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.

IntroducciónGetting started

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

La API de REST de OneDrive proporciona algunos tipos de nivel superior que representan los recursos que pueden tratarse en la API:OneDrive's REST API provides a few top-level types that represent addressable resources in the API:

A continuación se muestra un ejemplo de un recurso driveItem.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"
    }
  }
}

Los datos sobre un recurso se proporcionan de tres maneras:Data about a resource is provided in three ways:

  • Propiedades (como id y name) exponen valores simples.Properties (like id and name) expose simple values.
  • Facetas (como file y photo) exponen valores complejos.Facets (like file and photo) expose complex values. La presencia de facetas en un elemento indica normalmente comportamientos o capacidades de un elemento y propiedades relacionadas.The presence of facets on an item generally indicate behaviors or capabilities of an item and related properties.
  • Referencias (como children) indican colecciones de otros recursos.References (like items) point to collections of other resources.

Pueden adaptarse muchas solicitudes para incluir datos o quitar propiedades sin usar de las respuestas.Many requests can be tailored to include additional data or remove unused properties from the responses. OneDrive usa parámetros de consulta opcionales para habilitar esta función.OneDrive uses optional query parameters to enable this functionality. En la documentación, cada solicitud proporciona más contexto sobre qué parámetros se admiten.Throughout the documentation, each request provides more context about which parameters are supported.

De manera predeterminada, la mayoría de las propiedades y las facetas se devuelve mientras que todas las referencias se ocultan.By default, most properties and facets are returned while all references are hidden. Por motivos de eficacia, recomendamos que especifique seleccionar y expandir en los datos que le interesen.For efficiency, we recommend that you specify select and expand to only return the data you care about.

Para obtener información sobre los recursos y facetas, vea Recursos y Facetas.For details about resources and facets, see Resources and Facets.

Recursos raíz de Microsoft GraphMicrosoft Graph root resources

Dentro de Microsoft Graph, las funciones de OneDrive están disponibles desde varios recursos raíz.Within the Microsoft Graph, the OneDrive functionality is available from several root resources. Estos recursos corresponden al lugar donde las bibliotecas de documentos de SharePoint y OneDrive están disponibles en Office 365.These resources correspond to where OneDrive and SharePoint document libraries are available within Office 365. Las siguientes entidades de Microsoft Graph pueden contener una o más unidades:The follow entities in Microsoft Graph may contain one or more drives:

EntidadEntity Ruta de acceso de ejemploExample (path)
UserUser /v1.0/users/{id} o /v1.0/me/v1.0/users/{id} or /v1.0/me
GroupGroup /v1.0/groups/{id}
SiteSite /v1.0/sites/{id}

Recursos raíz de OneDriveOneDrive root resources

Al indicar un recurso raíz de Microsoft Graph, la aplicación puede indicar recursos de OneDrive con las siguientes rutas de acceso:When addressing a Microsoft Graph root resource, your app can address OneDrive resources using the following paths:

Ruta de accesoPath ResourceResource
/drives Muestra los recursos drive disponibles para el usuario autenticado.List drive resources available to the authenticated user.
/drives/{drive-id} Acceso a una unidad específica mediante su identificador.Access a specific site by its ID.
/drives/{drive-id}/root/children Muestra los elementos de la raíz de una unidad específica.List items in the root of a specific drive.
/drive/items/{item-id} Acceso a driveItem mediante su identificador.Access a specific site by its ID.
/drive/special/{special-id} Acceso a una carpeta conocida mediante su nombre conocido.Access a special (named) folder in the user's OneDrive by its known name.
/shares/{share-id} Acceso a driveItem mediante su shareId o una dirección URL para compartir.Access a driveItem by its shareId or a sharing URL.

Direccionamiento basado en la ruta de acceso en una unidadPath-based addressing within a drive

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).A driveItem can be addressed by either a unique identifier or where that item exists in the drive's hierarchy (i.e. user path). 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.Within an API request, a colon can be used to shift between API path space and user path space. La sintaxis es válida para cualquier driveItem al que se haga referencia mediante el espacio de API.This syntax is valid for any driveItem addressed via the API space.

También puede volver al espacio de ruta de API usando dos puntos al final del espacio de ruta del sistema de archivos.You can also transition back to API path space by using a colon at the end of the file system path space. 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.Ensure user data within the URL follows the addressing and path encoding requirements.

Ruta de accesoPath ResourceResource
/drive/root:/path/to/file Acceso a driveItem mediante la ruta de acceso debajo de la raíz.Access a driveItem by path under the root.
/drive/items/{item-id}:/path/to/file Acceso a driveItem mediante su ruta de acceso relativa a otro elemento.Access a driveItem by its path relative to another item.
/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.List children when accessing by path relative to the drive root.
/drive/items/{item-id}:/path/to/folder:/children Muestra los elementos secundarios al tener acceso mediante la ruta de acceso relativa a otro elemento.List the children of a DriveItem by path relative to another item.

Carpetas compartidas y elementos remotosShared folders and remote items

OneDrive Personal permite que un usuario agregue uno o más elementos compartidos desde otra unidad a su OneDrive.OneDrive personal users can add one or more shared items from another drive to their own OneDrive. Estos elementos compartidos aparecen como un driveItem en la colección children con una faceta remoteItem.These shared items appear as a DriveItem in the children collection with a remoteItem facet.

Además, los escenarios donde los elementos se devuelven desde fuera de la unidad de destino también incluirán una faceta remoteItem.In addition, scenarios where items are returned from outside the target drive will also include a remoteItem facet. Estos elementos también pueden devolverse desde búsqueda, archivos recientes, compartidos conmigo.These items may also be returned from search, recent files, shared with me.

Para obtener más información sobre cómo trabajar con carpetas compartidas y objetos remotos, vea Elementos remotos y carpetas compartidas.For more information about working with shared folders and remote items, see Remote items and shared folders.

Uso compartido y permisosSharing and permissions

Una de las acciones más comunes en OneDrive y SharePoint es compartir elementos con otras personas.One of the most common actions for OneDrive and SharePoint document libraries is sharing content with other people. OneDrive permite que su aplicación pueda crear vínculos para compartir, agregar permisos y enviar invitaciones a los elementos almacenados en una unidad.Microsoft Graph allows your app to create sharing links, add permissions and send invitations to items in a drive.

OneDrive también permite que su aplicación pueda tener acceso a contenido compartido directamente desde el vínculo para compartir.Microsoft Graph also provides a way for your app to access shared content directly from a sharing link.

Para obtener más información sobre cómo compartir y consumir contenido compartido, vea Sharing items in OneDrive (Compartir elementos en OneDrive).For more details on how to share and consume shared content, see Sharing items in OneDrive.

Webhooks y notificacionesWebhooks and notifications

OneDrive admite el envío de notificaciones de inserción de estilo webhook cuando se cambia el contenido de un OneDrive.OneDrive supports sending webhook-style push notifications when the contents of a OneDrive is changed. 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.Your app can use these notifications to track changes in near real-time instead of polling the server for changes.

Notas de programaciónProgramming notes

Compatibilidad de APIAPI compatibility

OneDrive seguirá evolucionando y obteniendo funciones adicionales.OneDrive will continue to evolve and gain additional functionality. La ruta de acceso de la API incluye un número de versión para proteger su aplicación de cambios importantes.The API path includes a version number to protect your app against breaking changes. Cuando se necesita un cambio importante, el número de versión de la API se incrementará.When a breaking change is required, the API version number will be incremented. Las aplicaciones existentes que llamen al número de versión original no se verán afectadas por el cambio.Existing apps calling the original version number will remain unaffected by the change. 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.See the Microsoft Graph support policy for information about how long a version of the API is supported.

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.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. No es un cambio importante agregar acciones adicionales, propiedades, facetas o referencias a un recurso.It is not a breaking change to add additional actions, properties, facets, or references to a resource.

Es posible que la API exponga características adicionales sin documentar de vez en cuando.It is possible that the API will expose additional undocumented features from time to time. Estas características no deben usarse hasta que estén documentadas.These features should not be utilized until they are documented. No presuponga que el comportamiento actual que se desvía de la documentación continuará.Do not assume that current behavior that deviates from the documentation will persist.

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.We will continue to make non-breaking changes to the existing version of the API, including adding facets, properties, and resources to the API. Por lo tanto, cualquier código que llame a la API necesita:As such, any code calling the API needs to:

  • Adaptarse a las propiedades adicionales que se agreguen a las respuestas JSON.Be resilient to additional properties being added to JSON responses. Pueden ignorarse.Ignoring them is OK.
  • No tener ninguna dependencia en el orden de propiedades devueltas en las respuestas JSON.Have no dependency on the order of properties returned in JSON responses.
  • Usar solo valores enumerados, propiedades, recursos y rutas de API documentadas.Use documented API paths, resources, properties, and enumerated values only. No se garantiza que los valores no documentados sean coherentes.Non-documented values are not guaranteed to remain consistent.
  • Todas las direcciones URL devueltas por la API de OneDrive deben tratarse como direcciones URL opacas.All URLs returned by OneDrive API should be treated as opaque URLs. Su aplicación no debe realizar ninguna suposición sobre el formato o los parámetros de estas direcciones URL.Your app should not make any assumptions about format or parameters in these URLs. Están sujetas a cambios sin previo aviso.Features are subject to change without notice.

LimitaciónThrottling

OneDrive tiene límites vigentes para garantizar que las personas y las aplicaciones no afectan de manera negativa a la experiencia de otros usuarios.OneDrive has limits in place to make sure that individuals and apps do not adversely affect the experience of other users. Cuando una actividad supera los límites de OneDrive, las solicitudes de API se rechazarán durante un período de tiempo.When an activity exceeds OneDrive's limits, API requests will be rejected for a period of time. 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.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

Trabajar con blocs de notas de OneNoteWorking with OneNote Notebooks

Nota: Aunque OneDrive almacena blocs de notas de OneNote, no debe usar la API de OneDrive para trabajar con ellos.Note: Although OneDrive stores OneNote notebooks, you shouldn't use the OneDrive API to work with OneNote notebooks. En su lugar, use la API de OneNote.Instead, use the OneNote API.

Validación continua de documentaciónContinuous documentation validation

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.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. Denominamos a esto validación continua de documentación.We call this continuous documentation validation.

Cada vez que se realiza un cambio en nuestra documentación, validamos que todo funcione como se ha documentado en el servicio.Each time a change to our documentation is made, we validate that everything works as documented in the service. Cuando creamos una nueva compilación del servicio, validamos que los ejemplos de nuestra documentación también sigan funcionando.When we create a new build of the service, we validate that the examples in our documentation also continue to work. Esto nos ayuda a garantizar que todo lo que documentamos funciona y que lo hace según lo esperado, incluso cuando existen nuevas actualizaciones.This helps us ensure that everything we document works and works as expected even as new updates are made available.

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.For the latest build details, check out the AppVeyor build status page for our documentation repository.

En los temas siguientes se incluye información general de alto nivel de otros conceptos que se aplican a la API de OneDrive.The following topics contain high-level overviews of other concepts that apply to the OneDrive API.