Carga, descarga y administración de archivos

Se aplica a: Desarrollador

Use las API de archivos y DriveItem de Microsoft Graph para administrar archivos dentro de contenedores de SharePoint Embedded.

Complete Primero Crear y administrar contenedores para que tenga un identificador de contenedor.

Descripción del almacenamiento de archivos

Un contenedor de SharePoint Embedded es el límite de almacenamiento del contenido de la aplicación.

Cada contenedor expone contenido de archivo a través del almacenamiento de archivos de Microsoft Graph y las API driveItem.

Use el modelo de datos de la aplicación para decidir qué objeto empresarial posee cada contenedor, qué carpetas crea la aplicación, qué usuarios o servicios pueden leer y escribir y qué identificadores de archivo almacena la aplicación.

Para la arquitectura, vea Arquitectura de aplicaciones incrustadas de SharePoint.

Uso de las API de almacenamiento de archivos de Microsoft Graph

Comience con estas referencias de Microsoft Graph:

Importante

Use las API documentadas driveItem y de almacenamiento de archivos de Microsoft Graph. No invente nombres de API de archivo específicos de SharePoint Embedded.

Requisitos previos

Antes de administrar los archivos, asegúrese de lo siguiente:

  • La aplicación puede adquirir tokens de Microsoft Graph.
  • La aplicación tiene FileStorageContainer.Selected consentimiento.
  • La aplicación tiene permisos de tipo contenedor para las operaciones previstas.
  • El contenedor de destino existe.
  • En el caso de las llamadas delegadas, el usuario es miembro del contenedor.
  • La aplicación almacena el identificador de contenedor y los identificadores de DriveItem que necesita.

Asignación de identificadores de contenedor a unidades

El origen de la vista previa señala que el punto de conexión de vista previa de Graph usa un driveIdy, para SharePoint Embedded, el identificador de unidad es el identificador de contenedor que comienza por b!.

En la aplicación:

  1. Almacene el identificador de contenedor devuelto cuando se crea el contenedor.

  2. Use el identificador de contenedor al llamar a las API de DriveItem que requieren un identificador de unidad.

  3. Almacene los identificadores de elemento devueltos por las operaciones de carga o creación de carpetas.

  4. Evite reconstruir los identificadores a partir de direcciones URL.

Cargar archivos

Use patrones de carga de Microsoft Graph para DriveItems.

Para archivos pequeños (hasta 250 MB), use la API de carga simple documentada para DriveItems con un solo PUT contenido del elemento.

Para archivos más grandes (más de 250 MB), use una sesión de carga documentada por Microsoft Graph y envíe el archivo en fragmentos de intervalo de bytes (por ejemplo, múltiplos de 320 KB) hasta que se complete la carga.

En el flujo de carga:

  1. Validar el acceso de escritura.
  2. Elija una carpeta de destino en el contenedor.
  3. Cree carpetas primero si la ruta de acceso no existe.
  4. Cargue los bytes de archivo con el método Graph adecuado.
  5. Almacene el identificador de DriveItem devuelto.
  6. Mostrar el nombre, el tamaño y el estado del archivo.

Sugerencia

Mantenga los metadatos empresariales en la base de datos de la aplicación y mantenga el contenido del archivo en SharePoint Embedded.

Se descargan los archivos

Use las funcionalidades de descarga de DriveItem de Microsoft Graph para el contenido de archivos.

En el flujo de descarga:

  1. Validar el acceso de lectura.
  2. Resuelva el identificador de contenedor y el identificador de DriveItem.
  3. Solicite el contenido del archivo o descargue la dirección URL mediante las API de DriveItem.
  4. Stream el contenido al usuario o servicio.
  5. Controlar la expiración de las direcciones URL de descarga de corta duración.
  6. Registre según sus requisitos de auditoría.

Crear carpetas

Use las API de creación de carpetas DriveItem para organizar el contenido.

Cree carpetas para la estructura de contenido predecible, las fases de flujo de trabajo, las cargas relacionadas y los elementos primarios estables para las direcciones URL de inicio de Office.

Al crear carpetas:

  1. Compruebe si la carpeta existe.
  2. Cree solo el segmento de ruta de acceso que falta.
  3. Almacene la carpeta DriveItem ID si es necesario.
  4. Aplicar reglas de nomenclatura de forma coherente.

Actualizar el contenido del archivo

Use patrones de actualización o carga de sesión de DriveItem de Microsoft Graph para reemplazar el contenido.

Antes de reemplazar el contenido:

  • Confirme el permiso de escritura.
  • Lea los metadatos actuales si se necesitan comprobaciones de simultaneidad.
  • Conserve el identificador de DriveItem donde se admite.
  • Actualice los metadatos de la aplicación después de que Graph se realice correctamente.

Los archivos de Office almacenados en SharePoint Embedded tienen el control de versiones habilitado automáticamente para los archivos de Word, Excel y PowerPoint.

Consulte Open Office files from your app for Office behavior (Abrir archivos de Office desde la aplicación para el comportamiento de Office).

Cambiar el nombre o mover elementos

Use operaciones documentadas de actualización y traslado de DriveItem cuando sea compatible.

Un flujo seguro debe leer el objeto DriveItem actual, confirmar la carpeta de destino, aplicar la operación, actualizar la ruta de acceso almacenada o el nombre para mostrar y mantener el identificador de DriveItem como referencia duradera cuando sea posible.

Eliminar archivos

Use operaciones de eliminación cuando un archivo ya no debería aparecer en la experiencia de contenido activo.

Antes de eliminar:

  • Confirme la intención del usuario.
  • Confirme el permiso de escritura o eliminación.
  • Decida si la aplicación necesita eliminación temporal.
  • Actualice el estado de la aplicación solo después de que Graph devuelva correctamente.

Restaurar archivos

Use las funcionalidades de restauración de archivos de Microsoft Graph y SharePoint documentadas para DriveItems y la experiencia del servicio.

Un flujo de restauración debe identificar el elemento o la versión eliminados, confirmar el permiso, realizar la restauración, actualizar la lista de elementos y comunicar la ubicación restaurada.

Nota:

recycleBinItem: la restauración admite driveItemId como clave alternativa (octubre de 2025). Si conoce el identificador del driveItem original, puede restaurar el elemento recycleBinItem correspondiente directamente sin enumerar primero la papelera de reciclaje.

Nota:

Para obtener los detalles exactos de la solicitud y respuesta de la operación de archivo, use la documentación de Microsoft Graph DriveItem.

Conexión a Office y experiencias en versión preliminar

Después de la carga, agregue experiencias más enriquecidas:

Validación de operaciones de archivo

Cree una prueba de humo:

  1. Cree un contenedor de prueba.
  2. Cree una carpeta.
  3. Cargue un archivo.
  4. Lee los metadatos de DriveItem devueltos.
  5. Descargue el archivo.
  6. Reemplace el contenido.
  7. Cambie el nombre del archivo.
  8. Elimine el archivo.
  9. Restaurarlo si se admite.
  10. Limpie el contenedor de prueba.

Solución de problemas de operaciones de archivos

Síntoma Cheque
Error de carga WriteContent permiso y rol de escritor de usuario.
Error en la descarga ReadContent permiso y rol lector de usuario.
Se produce un error en la creación de carpetas Identificador de carpeta principal y permisos de escritura.
Se produce un error en la versión preliminar Compatibilidad con el tipo de archivo y generación de direcciones URL de vista previa.
El inicio de Office abre el modo incorrecto Parámetro de dirección URL action de inicio o esquema de URI de Office.
El acceso difiere según el usuario El acceso delegado interseca los permisos de aplicación con la pertenencia.

Pasos siguientes

Habilite las experiencias de inicio de Office en archivos de Open Office desde la aplicación.

  • Last updated on