Prácticas recomendadas para descubrir archivos y detectar cambios a escala

SharePoint y OneDrive almacenan millones de archivos. Es fundamental usar los patrones de llamadas correctos al intentar comprender todos los archivos y cambios a escala. Históricamente, hay muchas API para tener acceso a los archivos en un nivel atómico. Muchas de estas API no son eficientes a gran escala, pero funcionan bien para una sola interacción de usuario. En esta guía se explica cómo supervisar a un inquilino de Office 365 o OneDrive para que la aplicación se integre con Office 365 con el máximo rendimiento y eficiencia. Las aplicaciones que suelen tener este tipo de necesidad son motores de sincronización, proveedores de copias de seguridad, indizadores de búsqueda, motores de clasificación y proveedores de prevención de pérdida de datos.

Obtención de los permisos adecuados

Para crear confianza con los usuarios, es importante usar el conjunto mínimo correcto de ámbitos de permisos necesarios para que una aplicación funcione. La mayoría de las aplicaciones de análisis querrán funcionar con permisos de aplicación, lo que indica que la aplicación se ejecuta independientemente de cualquier usuario en particular. Para obtener acceso a los archivos, debe solicitar el ámbito Files.Read.All o Files.ReadWrite.All. Para obtener acceso a los recursos de SharePoint, incluida la lista de todas las colecciones de sitios, es adecuado Sites.Read.All o Sites.ReadWrite.All. Para procesar los permisos correctamente, también tendrá que solicitar Sites.FullControl.All.

Tipos de autorización, ámbitos de permisos y usuarios

Al configurar los permisos de una aplicación en Microsoft Azure puede elegir entre permisos de la aplicación y permisos delegados. Como se indicó anteriormente, la mayoría de las aplicaciones de examen querrán permisos de aplicación. Los permisos delegados requieren que la aplicación funcione en el contexto de un usuario que ha iniciado sesión en lugar de globalmente. En el modelo delegado, usted está restringido al contenido al que el usuario actual tiene acceso.

Un aspecto importante de los permisos a tener en cuenta es que cuando un administrador concede permisos a una aplicación que solicita permisos de aplicación (en lugar de permisos delegados), la concesión de permisos se asocia con el inquilino y la aplicación, en lugar del usuario administrador. Aunque se requiere que un administrador conceda el acceso, la concesión de acceso no concede ningún permiso administrativo especial a la aplicación, más allá del acceso a los ámbitos de recursos solicitados por la aplicación.

Patrón de llamada recomendado

Para las aplicaciones que procesan grandes cantidades de datos de SharePoint y OneDrive, debe seguir un patrón de llamada coherente como el siguiente.

1. Descubrir: configure las ubicaciones que desea examinar.
2. Rastrear: descubra y procese todo el conjunto de archivos que le interesan.
3. Notificar: supervisar los cambios realizados en esos archivos mediante notificación.
4. Cambios de proceso: vuelva a procesar solo los archivos que han cambiado mediante la consulta delta.

El patrón será similar al siguiente diagrama. En este artículo se detallan los pasos para la implementación.

Cada uno de estos elementos puede tener varios mecanismos para realizarlos en la API de Microsoft Graph y en las API SharePoint existentes. El objetivo de este artículo es ofrecerle la mejor manera disponible a día de hoy para completar cada tarea.

Descubrir ubicaciones para examinar

La configuración de las ubicaciones que desea que la aplicación analice es hoy en día un proceso manual. En muchos casos, querrá proporcionar una experiencia de aplicación orientada al usuario para este paso; cómo expone esta funcionalidad y si está expuesta a todos los usuarios o simplemente a los administradores es su decisión. Querrá determinar qué usuarios de OneDrive y qué colecciones de sitios de SharePoint y subsitios está analizando.

La configuración de cada usuario de OneDrive contiene una única unidad que puede supervisar. Las colecciones de los sitios SharePoint y subsitios pueden tener varias unidades, una para cada biblioteca de documentos del sitio. Puede descubrir cada unidad de un sitio mediante el punto de conexión de la unidad de disco. Por ejemplo, para obtener todas las unidades en el sitio raíz del inquilino, puede usar:

https://graph.microsoft.com/v1.0/sites/root/drives

La unidad de disco es el punto de partida para las actividades de archivos a gran escala. Usará estas unidades para obtener listas completas de archivos, conectar webhooks para notificaciones y usar la consulta delta para obtener conjuntos de cambios en los elementos de las unidades.

Cómo buscar colecciones de sitios de SharePoint y unidades de OneDrive para la Empresa

Con Microsoft Graph con permisos de aplicación, puede obtener la lista completa de colecciones de sitios, incluidos los sitios que contienen unidades de OneDrive para la Empresa. Para obtener esta lista, use la siguiente llamada API:

GET /sites

La API de enumeración de sitios también admite la consulta delta para obtener información sobre los nuevos sitios creados o los cambios en la estructura del sitio. Actualmente, el soporte de consultas delta para la enumeración de sitios se está implementando en la versión beta de Microsoft Graph. Siga leyendo para obtener más información acerca de la consulta delta.

Para recibir notificaciones sobre las nuevas colecciones de sitios, puede suscribirse a enlaces web mediante el punto de conexión a las suscripciones de Microsoft Graph. El recurso de destino de estas notificaciones es /sites. Recibirá notificaciones cuando se creen o eliminen nuevas colecciones de sitios, así como cuando se creen subsitios o listas.

Rastreo y proceso mediante consulta delta

Para obtener la lista inicial de archivos en una unidad, realice una sola llamada de consulta delta sin parámetros. La consulta delta proporciona a las aplicaciones un rastreo inicial de todo el contenido y, a continuación, los cambios posteriores desde un punto en el tiempo. La consulta delta devuelve el vínculo necesario para obtener cambios futuros cada vez que se llama.

Por ejemplo, si desea obtener todos los archivos de la biblioteca de documentos predeterminada en un sitio SharePoint, puede usar esta consulta:

/sites/{siteId}/drive/root/delta

Esta API devuelve páginas de resultados que representan todos los archivos de la unidad. Después de recuperar todas las páginas de los archivos mediante el valor devuelto @odata.nextLink, puede volver a realizar la consulta delta con el valor devuelto @odata.deltaLink para obtener los cambios desde la última vez que llamó a la consulta delta. Recuerde siempre mantener la dirección URL devuelta por @odata.deltaLink para que pueda comprobar de forma eficaz los cambios más adelante.

Los vínculos devueltos por la consulta delta tendrán este aspecto:

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(driveItem)",
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?$select=*%2csharepointIds&token=MzslMjM0OyUyMzE7MzsyM2YwNDVhMS1lNmRmLTQ1N2MtOGQ5NS1hNmViZDVmZWRhNWQ7NjM2NzExNzY2MzIxMDcwMDAwOzE5ODAzMzU5ODslMjM7JTIzOyUyMzQ",
    "value": [
        {
            "@odata.type": "#microsoft.graph.driveItem",
            "createdDateTime": "2017-07-27T02:41:36Z",
…
}

Para obtener un ejemplo más detallado, consulte la documentación de consulta delta.

La consulta delta devuelve una matriz de driveItems. Si sabe con antelación que desea información específica, puede incluirla en una instrucción seleccionada con la consulta delta. Además, puede realizar un seguimiento de la llamada delta con una solicitud para un driveItem específico en caso de que la necesite. La consulta delta aún ayudará a reducir el número de elementos en los que debe consultar los cambios, lo que hará que la aplicación sea más eficiente.

Recibir notificaciones de cambios mediante webhooks

Para aprovechar mejor la consulta delta para los cambios que se están produciendo en una unidad, necesita una estrategia eficaz para saber cuándo volver y pedir los cambios. En el pasado, es posible que haya escrito la aplicación para sondear OneDrive y SharePoint en algún intervalo fijo y enumerar los cambios usted mismo. Con la consulta delta, la parte de enumeración se realiza por usted, por lo que solo necesita saber cuándo volver. Los webhooks permiten evitar el sondeo del servicio y, en su lugar, recibir una notificación cuando ha cambiado algo que le interese. El sondeo del servicio repetidamente o a tasas elevadas hace que la aplicación se limite debido a patrones de llamadas excesivos.

Los webhooks se adjuntan mediante la API de suscripciones para Microsoft Graph. Puede encontrar la documentación completa de los webhooks de Microsoft Graph y la API de suscripciones en el sitio de Microsoft Graph.

Deberá crear una suscripción asociada a un recurso específico (en este caso, una unidad). Las unidades admiten el tipo de cambio "actualizar" para webhooks. Una "actualización" indica que el contenido dentro de la unidad ha cambiado o que se ha agregado o eliminado contenido nuevo. Las suscripciones de webhook tienen un tiempo de espera asociado que debe actualizarse periódicamente. Consulta la documentación mencionada anteriormente sobre cómo actualizar las suscripciones. Se recomienda usar la consulta delta con el último token de cambio inmediatamente después de suscribirse a webhooks para asegurarse de que no se pierda ningún cambio que haya ocurrido entre el rastreo inicial y la configuración de los webhooks.

Incluso con webhooks que envían notificaciones de aplicación, es posible que desee proporcionar una consulta delta periódica para asegurarse de que no se pierde ningún cambio si parece que ha pasado mucho tiempo desde que se recibió una notificación. Se recomienda realizar esta comprobación periódica no más de una vez al día. La consulta delta aún le permite ponerse al día fácilmente y no perderse ningún cambio en el sistema.

Recibir notificaciones de webhook para eventos de seguridad

Soporte técnico de OneDrive y SharePoint para enviar notificaciones de aplicación de eventos de seguridad. Para suscribirse a estos eventos, deberá agregar el encabezado "prefer:includesecuritywebhooks" a la solicitud para registrar un webhook. Una vez registrado el webhook, recibirá notificaciones cuando cambien los permisos de un elemento. Este encabezado se aplica a SharePoint y OneDrive para la Empresa, pero no a las cuentas de OneDrive de usuario.

Procesar cambios

Después de que la aplicación reciba una notificación a través de un webhook, debe confirmar la notificación enviando inmediatamente un código 202 – Aceptado de nuevo en Microsoft Graph. Debe enviar este código antes de comenzar cualquier procesamiento que consuma mucho tiempo. Al no hacerlo, se envían reintentos adicionales, que la aplicación puede ver como notificaciones falsas.

Realice un seguimiento de la confirmación con una consulta delta para los cambios más recientes y debe actualizar la aplicación. Si espera patrones de tráfico intenso en una unidad determinada, considere la posibilidad de llamar a una consulta delta a un intervalo reducido en lugar de después de cada notificación de cambio. Además, asegúrese de almacenar el nuevo valor devuelto en el parámetro deltaLink para obtener un nuevo token para llamar de nuevo a la API.

Si el procesamiento requiere descargar el contenido de un archivo individual, puede usar la propiedad cTag para determinar si el contenido del archivo ha cambiado desde la última vez que lo descargó. Una vez que sepa que desea descargar el archivo, puede obtener acceso a la propiedad /content del objeto DriveItem devuelto en una respuesta de consulta delta.

Analizar las jerarquías de permisos

De forma predeterminada, en la respuesta de la consulta de diferencias se incluirá la información de uso compartido para los elementos aunque hereden sus permisos de su elemento primario y que no tengan cambios en el uso compartido directo. Tenga en cuenta que la respuesta de consulta delta solo incluye elementos con cambios directos en su contenido o metadatos y la jerarquía primaria de los elementos modificados. Por lo general, esto hace que se haga una llamada de seguimiento para obtener los detalles de los permisos de cada elemento, en lugar de solo los de aquellos cuya información compartida ha cambiado. Puede optimizar su comprensión de cómo se producen los cambios de permisos agregando el encabezado "Prefer: hierarchicalsharing" a la solicitud de consulta diferencial.

Cuando se proporciona el encabezado "Prefer: hierarchicalsharing", se devolverá información de uso compartido para la raíz de la jerarquía de permisos, así como los elementos que tienen explícitamente cambios compartidos. En los casos en los que el cambio de uso compartido se vaya a quitar el uso compartido de un elemento, encontrará una faceta de aspecto compartido vacío para diferenciar entre los elementos que heredan de su primario y los que son únicos, pero que no tienen vínculos para compartir. También verá esta faceta de uso compartido vacía en la raíz de una jerarquía de permisos que no se comparte para establecer el ámbito inicial.

En la mayoría de los escenarios de análisis, puede que esté interesado específicamente en los cambios en los permisos. Para que quede claro en la respuesta a la consulta diferencial los cambios que se producen al cambiar los permisos, puede proporcionar el encabezado "Prefer: hierarchicalsharing". Cuando se proporciona este encabezado, todos los elementos que aparecen en la respuesta de consulta delta debido a cambios de permisos tendrán la anotación OData "@microsoft.graph.sharedChanged":"True" presente al llamar a Microsoft Graph, cuando se use la API de SharePoint o OneDrive directamente, la anotación será "@oneDrive.sharedChanged":"True". Como en los webhooks de seguridad, esta característica se aplica a SharePoint y OneDrive para la Empresa, pero no a las cuentas de OneDrive de usuario.

¿Qué sucede cuando está limitado?

En algunos escenarios, la aplicación puede obtener una respuesta 429 o 503 de Microsoft Graph. Esto indica que la solicitud está limitada actualmente. Una cosa a tener en cuenta es que SharePoint limita las aplicaciones en función del uso de una aplicación con cada inquilino de cliente. Si se atiende una solicitud de un recurso en un espacio empresarial, se le darán menos recursos para realizar una llamada a otro recurso para ese mismo espacio empresarial. En última instancia, puede haber varias razones por las que la aplicación recibe una respuesta de limitación y es fundamental que la aplicación responda correctamente en estas situaciones.

Para recuperarse de recibir un código de respuesta 429 o 503, inténtelo de nuevo después de esperar la duración especificada en el campo Retry-After en el encabezado de respuesta. Si persiste la limitación, el valor Retry-After puede ser más largo con el tiempo, lo que permite que el sistema se recupere. Las aplicaciones que no respetan los reintentos después de la duración antes de llamar se bloquearán debido a patrones de llamadas abusivos.

Al esperar la recuperación 429 o 503, debe asegurarse de pausar todas las solicitudes que esté realizando al servicio. Esto es especialmente importante en escenarios multiproceso. Realizar llamadas adicionales mientras recibe respuestas de limitaciones extenderá el tiempo que tarda la aplicación en dejar de estar limitada.

Para obtener información más detallada sobre cómo funcionan los recursos de Microsoft Graph con la limitación, consulte la guía de limitación de Microsoft Graph.