Agregar acciones de apertura y vista previa personalizadas a los archivos con los controladores de archivos 2.0

Artículo
04/08/2023

Los controladores de archivos son un tipo de complemento de Microsoft 365 que integra tipos de archivo personalizados en el servicio, lo que le permite proporcionar experiencias enriquecidas para cualquier formato de propietario.

Con los controladores de archivos, puede habilitar las siguientes experiencias de usuario en las bibliotecas de documentos de OneDrive para la Empresa y SharePoint:

Iconos de archivo personalizados (para las extensiones de archivo de propietario)
Crear nuevos archivos en el explorador (para las extensiones de archivo de propietario)
Vista previa de archivos (para las extensiones de archivo de propietario)
Función de edición y visualización enriquecida (todas las extensiones de archivo)
Personalizar acciones que se inicien en su aplicación (todas las extensiones de archivo)
Admitir la selección múltiple y actuar en carpetas (solo acciones personalizadas)

Consulte las soluciones de ejemplo del controlador de archivos para obtener detalles adicionales.

Importante

Las configuraciones del controlador de archivos se almacenan en caché en todo el sistema para obtener un rendimiento óptimo. Los cambios de configuración pueden tardar entre 24 y 48 horas en surtir efecto. Para más información sobre cómo configurar los controladores de archivo, vea Registro.

Cambios de los controladores de archivos 2.0

La actualización 2.0 de los controladores de archivos permite escenarios adicionales para SharePoint Online y OneDrive para la Empresa.

Use la API de Microsoft Graph para obtener un acceso más sólido a los archivos, incluidos los metadatos de archivos, permisos y uso compartido.
Agregue botones de acción personalizados que inicien el complemento del controlador de archivos, con texto personalizado e iconos.

Qué tiene un controlador de archivos

Un controlador de archivos se compone de los siguientes componentes:

Punto de conexión del controlador de archivos. Una aplicación hospedada por el proveedor que permite la experiencia del controlador de archivos. Este punto de conexión puede proporcionar opcionalmente una experiencia para crear, previsualizar y editar archivos que están registrados con su controlador de archivos.
Manifiesto del controlador de archivos. Un conjunto de metadatos que define la interacción entre Office 365 y el punto de conexión del controlador de archivos.
Aplicación registrada en Azure Active Directory. Esta aplicación se usa para autorizar el acceso a los archivos seleccionados mediante Microsoft Graph, y es el lugar donde está registrado el manifiesto del controlador de archivos.

Punto de conexión del controlador de archivos

El punto de conexión del controlador de archivos es una aplicación hospedada en la nube que contiene la lógica funcional para crear, previsualizar, abrir y guardar archivos del tipo que controla. Puede hospedarse en cualquier pila, incluidas las pilas que no son de Microsoft. Los controladores de archivos usan Azure Active Directory para obtener acceso autorizado a los recursos de Office 365, de manera que la aplicación necesita registrarse con Azure AD. Para obtener más información sobre cómo registrar una aplicación con Azure AD, vea Registrar su aplicación en Microsoft Graph.

Para obtener una lista completa de los controladores de archivo, vea la lista de muestras disponibles.

Manifiesto del controlador de archivos

El manifiesto define la interacción entre Office 365 y el punto de conexión del controlador de archivos. El manifiesto está registrado con Azure Active Directory, mediante la colección addIns para un objeto de aplicación en el directorio. Para registrar o actualizar el registro del manifiesto del controlador de archivos, vea How to: Register a file handler manually (Cómo: Registrar un controlador de archivos manualmente).

Un manifiesto del controlador de archivos de ejemplo:

{
    "id": "guid",
    "type": "FileHandler",
    "properties": [
        { "key": "version", "value": "2" },
        { "key": "appIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "fileTypeDisplayName", "value": "Contoso Document File" },
        { "key": "fileTypeIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "actionMenuDisplayName", "value": "Contoso Actions" },
        { "key": "actions", "value": "json" }
    ]
}

Cada manifiesto del controlador de archivos incluye los siguientes pares clave-valor como parte de la matriz properties:

Nombre de la propiedad	Tipo	Descripción
version	String	Especifica la versión del controlador de archivos. Este valor debe establecerse en `2`. Necesario para los controladores de archivos 2.0.
appIcon	Cadena, JSON codificado	Una colección de direcciones URL de iconos en diferentes formatos que se usan para representar la aplicación de controladores de archivos. Opcional.
fileTypeDisplayName	String	La descripción de la configuración regional predeterminada para el tipo de archivo. Opcional.
fileTypeIcon	Cadena, JSON codificado	Una colección de direcciones URL de iconos en diferentes formatos que se usan para representar tipos de archivos que controla este controlador de archivos. Opcional.
actionMenuDisplayName	Cadena	Opcional. Una cadena para mostrar en la configuración regional predeterminada que se usa cuando las acciones asociadas a este controlador de archivos se contraen en un menú.
actions	Cadena, JSON codificado	Una colección de acciones implementadas mediante esta extensión de controlador de archivos. Vea especificar acciones para obtener más información. Obligatorio.

Controladores de archivos en tiempo de ejecución

El complemento del controlador de archivos se invoca mediante la URL de punto de conexión especificada en el manifiesto del controlador de archivos para la acción invocada. Para entender lo que sucede, vamos a echar un vistazo al escenario donde un usuario hace clic para previsualizar un archivo. Si hay un controlador de archivos registrado para ese tipo de archivo, Office 365 invoca la aplicación del controlador de archivos realizando una solicitud POST en la URL especificada para la acción preview. En el cuerpo de la solicitud POST, Office 365 incluirá los parámetros de activación que especifican el archivo que se ha seleccionado. Las demás acciones, incluidas newFile, open y custom se invocan de la misma manera.

Parámetros de activación

En los escenarios anteriores, la aplicación del controlador de archivos necesita detalles, denominados parámetros de activación, sobre el archivo, el inquilino, el cliente de Office 365, etc., para trabajar con el archivo seleccionado. Office 365 incluye estos detalles como datos de formulario enviados en la solicitud POST al punto de conexión del controlador de archivos asociado a la acción del usuario. Estos parámetros se incluyen en la solicitud con el tipo MIME application/x-www-form-urlencoded y están codificados con la dirección URL en el cuerpo de la solicitud.

Se proporcionan los siguientes parámetros en los parámetros de activación:

Nombre del parámetro	Tipo	Descripción
cultureName	string	El identificador de la configuración regional para el idioma para mostrar actual del usuario.
client	string	La aplicación de Office 365 desde la que se ha invocado el controlador de archivos; por ejemplo, "SharePoint" o "OneDrive".
userId	string	El correo electrónico de UPN o inicio de sesión del usuario que ha invocado el controlador de archivos.
domainHint	string	Una cadena de sugerencia de dominio que indica `organizations` o `consumers`.
items	Colección de cadenas JSON de direcciones URL	Una colección de direcciones URL de Microsoft Graph a los elementos seleccionados.

Estos valores están codificados en la solicitud POST como valores de formulario.

Aquí se muestra una solicitud de ejemplo que se enviará al punto de conexión del controlador de archivos:

POST https://contoso.com/_api/filehandlers/preview
Content-Type: application/x-www-form-urlencoded

cultureName=en-us&client=OneDrive&userId=rgregg%40contoso.com&items=%5B%22https%3A%2F%2Fgraph.microsoft.com%2Fv1.0%2Fme%2Fdrive%2Fitems%2F4D679BEA-6F9B-4106-AB11-101DDE52B06E%22%5D

Nota: Las direcciones URL devueltas en la colección de elementos pueden ser muy largas (pero más cortas que la longitud máxima de dirección URL de 2048 caracteres). Cada dirección URL contiene un token insertado en la dirección URL que permite que la aplicación del controlador de archivos obtenga acceso al contenido sin un ámbito de permisos de plena confianza. En cambio, el punto de conexión del controlador de archivos debe garantizar que espera que las direcciones URL largas se devuelvan y controlen correctamente.

Para los desarrolladores de ASP.NET, puede tener acceso a estos valores con la colección Request.Form, por ejemplo:

var itemsJson = Request.Form["items"];
var itemUrls = JsonConvert.DecodeObject<string[]>(items);

Los parámetros de activación deben almacenarse en caché cuando se presenta la solicitud, con una caché del lado servidor o mediante cookies en la respuesta. Para la solicitud inicial del controlador de archivos, es probable que la aplicación del controlador de archivos necesite redirigir al usuario para recuperar un objeto accessToken mediante la experiencia de OAuth2 de Azure Active Directory. Los parámetros de activación se perderán si no se conservan antes de que se produzca este redireccionamiento.

Puede ver un ejemplo de cómo usar un objeto de modelo de datos y el método del controlador para almacenar en caché los parámetros de activación en una cookie, en los ejemplos de C# o TypeScript vinculados a continuación en las soluciones de ejemplo.

Soluciones de ejemplo para controladores de archivos

Autenticación sin interrupciones con los controladores de archivos 2.0

Después de que el controlador de archivos haya recibido una solicitud con los parámetros de activación, necesitará recuperar un token de acceso para realizar llamadas API a Microsoft Graph. La aplicación necesitará llamar al punto de conexión de autenticación de Azure Active Directory para recuperar un token de acceso para el usuario que ha iniciado sesión. Para permitir el inicio de sesión único y evitar pedir al usuario que seleccione una cuenta, puede usar el parámetro login_hint y proporcionar el valor del parámetro de activación userId.

En algunos escenarios, es posible que el controlador de archivos pida al usuario iniciar sesión. Si el controlador de archivos se ejecuta como una acción preview, no se puede redirigir a la experiencia de inicio de sesión dentro de un IFRAME y tendrá que incluir la experiencia de inicio de sesión del controlador de archivos en un elemento emergente.

Disponibilidad del controlador de archivos

En la tabla siguiente se muestran los servicios de Office 365 que admiten controladores de archivos.

Nombre del servicio	Controladores de archivos 2.0	Controladores de archivos 1.0
SharePoint Online	Disponible de manera generalizada (GA)	GA
OneDrive para la Empresa	GA	GA
OneDrive Personal	No disponible	No disponible
Outlook Web App	No disponible	GA

Compartir a través de