Abrir archivos de Office desde la aplicación

Se aplica a: Desarrollador

Abra archivos de Office desde la aplicación SharePoint Embedded mediante metadatos de Microsoft Graph DriveItem y patrones de inicio de Office compatibles con Microsoft 365.

Complete Primero la carga, descarga y administración de archivos para que la aplicación tenga archivos para iniciar.

Al almacenar archivos de Office en un contenedor de SharePoint Embedded, la aplicación se vincula a una pila de colaboración completa sin crear ninguna. Los archivos de Word, Excel y PowerPoint admiten la coautoría en tiempo real, el autoguardado, el historial de versiones automático y el uso compartido a través de vínculos compartibles y @mentions, con niveles de acceso de ámbito. No es necesario crear un motor de colaboración. La edición se abrirá en Office para la Web (en una nueva pestaña o ventana del explorador) o en clientes de escritorio de Office, para que los usuarios dejen la interfaz de usuario de la aplicación para editar; inserte una vista previa de solo lectura cuando necesite ver en línea en la aplicación. Para obtener el contexto de decisión, consulte Agregar la coautoría de Office sin crearla.

Descripción de las experiencias de Office

Las experiencias de archivo de Office de SharePoint Embedded funcionan de forma similar a las experiencias de archivo de Microsoft 365. Las experiencias admitidas incluyen:

• Abrir documentos de Office en Office para la Web.
• Abrir documentos de Office en clientes de escritorio de Office.
• Ver y editar archivos.
• Autoguardado para archivos de Word, Excel y PowerPoint.
• Historial de versiones de los documentos de Office.
• La coautoría.
• Uso compartido y vínculos compartibles.
• Comentarios y menciones, con limitaciones documentadas.
• Rutas de navegación en clientes de Office que asocian un archivo a la aplicación.

Controlar la integración de Office

La integración de Office está habilitada de forma predeterminada para los tipos de contenedor de SharePoint Embedded. Los usuarios autorizados pueden abrir archivos compatibles en Office para la Web y clientes de escritorio de Office, incluso a través de experiencias de Office fuera de la interfaz de usuario personalizada de la aplicación. Si la aplicación requiere acceso a archivos para permanecer dentro de experiencias controladas por la aplicación, puede deshabilitar la integración de Office para el tipo de contenedor estableciendo la isOfficeRestricted propiedad en fileStorageContainerTypeSettingstrue.

isOfficeRestricted actualmente solo está disponible a través del punto de conexión beta de Microsoft Graph. Aún no está disponible en la versión 1.0. Para obtener la definición de propiedad, consulte el tipo de recurso fileStorageContainerTypeSettings.

Establecer settings.isOfficeRestricted con la API de Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} en el punto de conexión beta.

PATCH https://graph.microsoft.com/beta/storage/fileStorage/containerTypes/{containerTypeId}
Content-Type: application/json

{
  "settings": {
    "isOfficeRestricted": true
  }
}

Cuando la integración de Office está deshabilitada, los usuarios no pueden iniciar archivos desde contenedores afectados en Office para la Web o en los clientes de escritorio de Office. Antes de habilitar esta restricción, asegúrese de que la aplicación proporcione o dirija a los usuarios a una experiencia alternativa adecuada para ver o editar archivos.

Requisitos previos

Antes de iniciar archivos de Office, asegúrese de lo siguiente:

• El archivo se almacena en un contenedor de SharePoint Embedded.
• La aplicación puede leer los metadatos de DriveItem para el archivo.
• El usuario tiene permiso para ver o editar el archivo.
• El tipo de archivo es compatible con el cliente de Office de destino.
• La aplicación controla los redireccionamientos del explorador o el comportamiento de la nueva ventana.

Obtener la dirección URL web de DriveItem

Cuando la aplicación recupera un elemento de unidad de Microsoft Graph, la respuesta puede incluir webUrl.

Para los tipos de archivo de Office compatibles, webUrl apunta a una dirección URL que abre el documento en Office para la Web.

Una dirección URL web de Office admitida tiene esta forma:

https://host/:w:r/contentstorage/sitecollection/_layouts/15/doc2.aspx?sourcedoc=guid&file=filename.docx&action=default&mobileredirect=true

Para obtener detalles de la solicitud, consulte Obtener un recurso de DriveItem.

Iniciar Office para la Web

Use DriveItem webUrl cuando la aplicación deba abrir Office en el explorador.

1. Leer el elemento de unidad del archivo seleccionado.
2. Confirme que la respuesta incluya webUrl.
3. Abra la dirección URL en una pestaña del explorador, una ventana o una superficie de navegación controlada por aplicación.
4. Conserva el contexto de la aplicación para que los usuarios puedan volver después de editar.
5. Controle los errores de acceso denegado comprobando los permisos de archivo y la pertenencia a los contenedores.

Configurar la experiencia de inicio predeterminada

De forma predeterminada, la dirección URL de Office incluye action=default.

Para forzar un modo, actualice el parámetro de consulta con este patrón:

System.UriBuilder builder = new System.UriBuilder(webUrl);
System.Collections.Specialized.NameValueCollection queryDictionary = System.Web.HttpUtility.ParseQueryString(builder.Query);
queryDictionary["action"] = "view";
builder.Query = queryDictionary.ToString();
string modifiedWebUrl = builder.ToString();

Use lo siguiente:

• action=view para visualización de solo lectura.
• action=edit para editar cuando el usuario tiene permiso de edición.
• action=default cuando Office debe elegir el comportamiento predeterminado.

Para conocer los valores admitidos action , consulte Acciones de la interfaz de plataforma abierta de la aplicación web.

Abrir archivos en clientes de escritorio de Office

Use esquemas de URI de Office cuando la aplicación deba abrir clientes de escritorio directamente.

El formato es:

<scheme-name>:<command-name>|<command-argument-descriptor>|<command-argument>

Los valores comunes incluyen:

Ejemplos:

ms-word:ofv|u|https://contoso.com/document.docx
ms-powerpoint:ofe|u|https://contoso.com/presentation.pptx

Compilación de una URL de cliente de escritorio

Dado que webUrl apunta a documentos de Office de Office Online, cree el URI de escritorio en dos pasos:

1. Obtén la webUrl información de la carpeta principal.
2. Anexe el nombre de archivo.

Patrón de ejemplo:

ms-word:ofe|u|{folder.WebUrl}/{item.Name}

Forma resultante:

ms-word:ofe|u|https://contoso.sharepoint.com/contentstorage/CSP_1234765465/Document%20Library/MyDocument.docx

Para obtener detalles sobre el esquema, consulte Esquemas de URI de Office.

Configurar comportamiento de redirección

Use la configuración de redireccionamiento para dirigir a los usuarios de vuelta a la aplicación cuando Microsoft 365 no pueda abrir un archivo en un visor compatible.

ApplicationRedirectUrl Configura la dirección URL de redireccionamiento de la aplicación en el tipo de contenedor. Úselo para la ruta de la aplicación que controla los escenarios de devolución de archivos para su carga de trabajo.

La urlTemplate configuración controla a dónde envía Microsoft 365 a los usuarios para los archivos que no tengan un visor admitido. Los archivos compatibles del visor web de Office, como Word, Excel y PowerPoint, se abren en el visor web de Office. Los archivos PDF se abren en el visor incrustado. Otros tipos de archivo redirigen cuando urlTemplate está configurado. Si urlTemplate no está configurado, Microsoft 365 enviará a los usuarios a una página de ayuda de Microsoft.

Establecer settings.urlTemplate con la API de Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} . Use una dirección URL absoluta https:// válida que no se resuelva en una dirección de bucle invertido.

PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}
Content-Type: application/json

{
  "settings": {
    "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}"
  }
}

Microsoft 365 resuelve los tokens admitidos, codifica sus valores en la URL y los sustituye en la plantilla. Por ejemplo, los tokens admitidos pueden incluir {tenant-id}, {drive-id}, {folder-id}, {item-id}, {site-domain}{list-id}, y {site-url}.

Cuando la aplicación reciba una urlTemplate redirección, autentique al usuario, analice los valores de token y use Microsoft Graph para recuperar el archivo. Si necesita la dirección URL del archivo canónico, use la propiedad DriveItem webDavUrl en lugar de webUrl.

Al diseñar redirecciones:

• Usa una dirección URL de producción estable para la aplicación.
• Usa las direcciones URL de desarrollo solo para trabajo local o de prueba.
• Mantenga los URI de redireccionamiento de Microsoft Entra ID alineados con las rutas de la aplicación.
• Asegúrese de que los usuarios vuelvan al contexto correcto en la aplicación después de las acciones de Office.
• Evite la reescritura de direcciones URL que elimine los parámetros de consulta de Office necesarios.
• Comprobar urlTemplate después de las actualizaciones porque los valores no válidos se almacenan como null.

Admitir el uso compartido y la coautoría

Las experiencias de Office incluyen características de colaboración.

Los usuarios pueden compartir documentos, crear vínculos para compartir, trabajar en coautoría en tiempo real, ver indicadores de presencia, usar comentarios y usar menciones cuando sea compatible.

Cuando un usuario crea un vínculo para compartir, elige a quién concede acceso:

Usar el historial de versiones

El control de versiones se habilita automáticamente para los archivos de Word, Excel y PowerPoint almacenados en aplicaciones de SharePoint Embedded.

Los usuarios pueden ver los cambios, comparar versiones, restaurar versiones anteriores, recuperarse de errores y revisar los cambios de las sesiones de coautoría.

Usar propiedades de ruta de navegación

Los clientes de Office pueden mostrar elementos de estilo ruta de navegación que asocian archivos de Office a la aplicación.

Los patrones de ruta de navegación se crean a partir de las propiedades del contenedor configuradas para la aplicación.

Use el canal actual de actualización para las Aplicaciones de Microsoft 365 para que los usuarios reciban el comportamiento de ruta de navegación de Office más reciente y las mejoras futuras de las aplicaciones de Office.

Para obtener información sobre los canales de actualización de Office, consulte Información general sobre los canales de actualización de las Aplicaciones Microsoft 365.

Validar el inicio de Office

Pruebe cada ruta de inicio:

1. Cargar un documento de Word en un contenedor.
2. Leer el elemento de unidad y capturar webUrl.
3. Abrir webUrl con action=default.
4. Modifique la cadena de consulta a action=view.
5. Modifique la cadena de consulta a action=edit.
6. Cree un esquema de URI de Office para el inicio en el escritorio.
7. Confirme los permisos, bloquee la edición cuando corresponda.
8. Confirmar el comportamiento de Autoguardado y del historial de versiones.
9. Confirme que el usuario puede volver a la aplicación.

Solución de problemas de inicio de Office

Pasos siguientes

Agregue vistas previas incrustadas en los archivos de vista previa de la aplicación.