Abrir archivos de Office desde la aplicación

Se aplica a: Desarrollador

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

Complete primero Cargar, descargar y administrar archivos para que la aplicación tenga archivos para iniciarse.

Descripción de las experiencias de Office

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

• Abrir documentos de Office en Office para la Web.
• Abrir documentos de Office en clientes de escritorio de Office.
• Visualización y edición de archivos.
• AutoGuardar para archivos de Word, Excel y PowerPoint.
• Historial de versiones de documentos de Office.
• Coautoría.
• Compartir y compartir vínculos.
• Comentarios y menciones, con limitaciones documentadas.
• Rutas de navegación en clientes de Office que asocian un archivo a la aplicación.

Nota:

No se puede ver ni acceder a los documentos almacenados en un contenedor archivado. La aplicación debe controlar el estado archivado mostrando un error adecuado y guiando a los usuarios en los pasos siguientes, como reactivar el contenedor.

Requisitos previos

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

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

Obtención de la dirección URL web de DriveItem

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

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

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

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

Para obtener más información sobre la solicitud, consulte Obtención de un recurso DriveItem.

Iniciar Office para la Web

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

1. Lea driveItem para el archivo seleccionado.
2. Confirme que la respuesta incluye webUrl.
3. Abra la dirección URL en una pestaña del explorador, una ventana o una superficie de navegación controlada por la aplicación.
4. Conservar el contexto de la aplicación para que los usuarios puedan volver después de la edición.
5. Controle los errores de acceso denegado comprobando los permisos de archivo y la pertenencia al contenedor.

Nota:

Los archivos de Office usan Autoguardar cuando los usuarios editan archivos de Word, Excel y PowerPoint almacenados en SharePoint Embedded.

Configuración de 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 la 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 ver los valores admitidos action , consulte Acciones de web Application Open Platform Interface.

Abrir archivos en clientes de escritorio de Office

Use esquemas uri de Office cuando la aplicación debe abrir clientes de escritorio directamente.

El formato es:

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

Entre los valores comunes se incluyen:

Segmento	Valor
Nombre del esquema	ms-word, ms-excel o ms-powerpoint
Comando Abrir vista de archivo	ofv
Comando Abrir edición de archivo	ofe
Descriptor de dirección URL	u

Ejemplos:

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

Nota:

El URI debe abrirse en una ventana en blanco o en una nueva pestaña.

Creación de una dirección URL de cliente de escritorio

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

1. Obtenga de webUrl la carpeta primaria.
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 más información sobre el esquema, consulte Esquemas de URI de Office.

Configuración del comportamiento de redireccionamiento

Use la configuración de redireccionamiento para enrutar a los usuarios 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. Úsela para la ruta de la aplicación que controla los escenarios de devolución de archivos para la carga de trabajo.

La urlTemplate configuración controla dónde Microsoft 365 envía usuarios para archivos sin un visor compatible. Los archivos de visor web de Office admitidos, 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 a través urlTemplate de cuando se configura. Si urlTemplate no está configurado, Microsoft 365 envía usuarios a una página de ayuda de Microsoft.

Establezca settings.urlTemplate con Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} API. 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 mediante url y los sustituye en la plantilla. Los tokens comunes incluyen {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 del 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:

• Use una dirección URL de producción estable para la aplicación.
• Use direcciones URL de desarrollo solo para el trabajo local o de prueba.
• Mantenga Microsoft Entra ID URI de redireccionamiento alineados con las rutas de la aplicación.
• Valide 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 quita los parámetros de consulta de Office necesarios.
• Compruebe urlTemplate después de las actualizaciones porque los valores no válidos se almacenan como null.

Compatibilidad con 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 que se puedan compartir, coautor en tiempo real, ver indicadores de presencia, usar comentarios y usar menciones cuando se admitan.

Cuando un usuario crea un vínculo de uso compartido, elige a quién concede acceso:

Ámbito de uso compartido	Quién puede usar el vínculo
Cualquiera	Cualquier persona que reciba el vínculo, incluidas las personas ajenas a su organización, tanto si lo envía directamente como si se reenvía.
Personas de su organización	Cualquier persona de la organización que tenga el vínculo, ya sea que se envíe directamente o se reenvíe.
Usuarios específicos	Solo las personas que especifique. Si se reenvía la invitación, solo las personas que ya tienen acceso pueden usar el vínculo.
Personas que tienen acceso ya existente	People que ya tienen acceso al archivo o carpeta. Este ámbito no cambia los permisos existentes.

Nota:

Las menciones requieren que los usuarios de destino tengan asignada una licencia de Microsoft 365. Las menciones están restringidas a las personas dentro de la organización del inquilino de consumo y excluyen a los invitados y usuarios de otros inquilinos en la configuración multiinquilino.

Uso del 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 cambios, comparar versiones, restaurar versiones anteriores, recuperarse de errores y revisar los cambios de las sesiones de coautoría.

Uso de propiedades de ruta de navegación

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

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

Use Canal actual para obtener patrones de ruta de navegación y futuras mejoras de 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 para Aplicaciones Microsoft 365.

Validación del inicio de Office

Pruebe cada ruta de acceso de inicio:

1. Cargue un documento Word en un contenedor.
2. Lea DriveItem y capture webUrl.
3. Abra 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 del escritorio.
7. Confirme que los permisos bloquean la edición cuando corresponda.
8. Confirme el comportamiento del 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

Síntoma	Cheque
La dirección URL se abre en la vista en lugar de editar	action parámetro y permiso de edición de usuario.
El cliente de escritorio no se abre	Esquema de URI de Office, directiva de explorador y comportamiento de nueva pestaña.
El usuario no puede coautor	Tipo de archivo, permisos y compatibilidad con el cliente de Office.
Las menciones no encuentran un usuario	Limitaciones de licencias y pertenencia a inquilinos de Microsoft 365.
La ruta de navegación no tiene el aspecto correcto	Propiedades de contenedor y canal de actualización de Office.
El redireccionamiento vuelve a una ruta incorrecta	ApplicationRedirectUrl y el control de rutas de la aplicación.

Pasos siguientes

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