Agregar acciones de apertura y vista previa personalizadas a los archivos con los controladores de archivos 2.0Adding custom preview, open, and actions to files with File Handlers 2.0

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.File Handlers are a type of Microsoft 365 add-in that integrates custom file types into the service allowing you to provide rich experiences for any proprietary format.

Con los controladores de archivos, puede habilitar las siguientes experiencias de usuario en las bibliotecas de documentos de OneDrive para la Empresa y SharePoint:With File Handlers, you can enable the following user experiences in OneDrive for Business and SharePoint document libraries:

  • Iconos de archivo personalizados (para las extensiones de archivo de propietario)Customized file icons (for proprietary file extensions)
  • Crear nuevos archivos en el explorador (para las extensiones de archivo de propietario)Create new files in the browser (for proprietary file extensions)
  • Vista previa de archivos (para las extensiones de archivo de propietario)File preview (for proprietary file extensions)
  • Función de edición y visualización enriquecida (todas las extensiones de archivo)Rich view/edit capability (all file extensions)
  • Personalizar acciones que se inicien en su aplicación (todas las extensiones de archivo)Custom actions that launch into your app (all file extensions)
  • Admitir la selección múltiple y actuar en carpetas (solo acciones personalizadas)Support multiple selection and acting on folders (custom actions only)

Consulte las soluciones de ejemplo del controlador de archivos para obtener detalles adicionales.Check out the file handler example solutions for additional details.

Importante

Las configuraciones del controlador de archivos se almacenan en caché en todo el sistema para obtener un rendimiento óptimo.File Handler configurations are aggressively cached throughout the system for optimal performance. Los cambios de configuración pueden tardar entre 24 y 48 horas en surtir efecto.It may take 24-48 hours for any configuration changes to take effect. Para más información sobre cómo configurar los controladores de archivo, vea Registro.See Registering for information about how to configure file handlers.

Cambios de los controladores de archivos 2.0What's changed with File Handlers 2.0

La actualización 2.0 de los controladores de archivos permite escenarios adicionales para SharePoint Online y OneDrive para la Empresa.The 2.0 upgrade to file handlers enables additional scenarios for SharePoint Online and OneDrive for Business.

  • 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.Use Microsoft Graph API for more robust access to files, including file metadata, permissions, and sharing.
  • Agregue botones de acción personalizados que inicien el complemento del controlador de archivos, con texto personalizado e iconos.Add custom action buttons that launch your file handler add-in, with custom text and icons.

Qué tiene un controlador de archivosWhat's in a file handler

Un controlador de archivos se compone de los siguientes componentes:A file handler is comprised of the following components:

  • 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.File handler endpoint. A provider-hosted app that enables the experience of your file handler. This end point can optionally provide an experience for creating, previewing, and editing files that are registered with your file handler.
  • 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.File handler manifest. A set of metadata that defines the interaction between Office 365 and your file handler endpoint.
  • 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.Application registered in Azure Active Directory. This application is used to authorize your access to selected files via Microsoft Graph, and is where the file handler manifest is registered.

Punto de conexión del controlador de archivosFile handler endpoint

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 más información sobre cómo registrar una aplicación con Azure AD, vea Registrar su aplicación en Microsoft Graph.The file handler endpoint is a cloud-hosted app that contains the functional logic for creating, previewing, opening, and saving files of the type that it handles. It can be hosted on any stack, including non-Microsoft stacks. File handlers uses Azure Active Directory to gain authorized access to Office 365 resources, so your application needs to be registered with Azure AD. For more information about registering an application with Azure AD, see Registering your app for Microsoft Graph.

Para obtener una lista completa de los controladores de archivo, vea la lista de muestras disponibles.For a complete examples of a file handler, see the list of available samples.

Manifiesto del controlador de archivosFile handler manifest

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).The manifest defines the interaction between Office 365 and the file handler endpoint. The manifest is registered with Azure Active Directory, using the addIns collection for an application object in the directory. To register or update the registration for your file handler manifest, see How to: Register a file handler manually.

Un manifiesto del controlador de archivos de ejemplo:An example file handler manifest:

{
    "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:Each file handler manifest includes the following key-value pairs as part of the properties array:

Nombre de la propiedadProperty Name TipoType DescripciónDescription
versionversion CadenaString Especifica la versión del controlador de archivos. Este valor debe establecerse en 2. Necesario para los controladores de archivos 2.0.Specify the version of the file handler. This value must be set to 2. Required for file handlers 2.0.
appIconappIcon Cadena, JSON codificadoString, encoded JSON Una colección de direcciones URL de iconos en diferentes formatos que se usan para representar la aplicación de controladores de archivos.A collection of icon URLs in different formats that are used to represent the file handler application. Opcional.Optional.
fileTypeDisplayNamefileTypeDisplayName StringString La descripción de la configuración regional predeterminada para el tipo de archivo. Opcional.The default locale description for the file type. Optional.
fileTypeIconfileTypeIcon Cadena, JSON codificadoString, encoded JSON 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.A collection of icon URLs in different formats that are used to represent file types handled by this file handler. Opcional.Optional.
actionMenuDisplayNameactionMenuDisplayName CadenaString Opcional.Optional. 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ú.A display string in the default locale that is used when the actions associated with this file handler are collapsed into a menu.
actionsactions Cadena, JSON codificadoString, encoded JSON Una colección de acciones implementadas mediante esta extensión de controlador de archivos. Vea especificar acciones para obtener más información. Necesario.A collection of actions implemented by this file handler extension. See specifying actions for more information. Required.

Controladores de archivos en tiempo de ejecuciónFile handlers at runtime

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.The file handler add-in is invoked via the endpoint URL specified in the file handler manifest for the invoked action. To understand what happens, let's take a look at the scenario where a user clicks to preview a file. If there is a registered file handler for that file type, Office 365 invokes the file handler app by making a POST request to the URL specified for the preview action. In the body of the POST request, Office 365 will include the activation parameters that specify the file that was selected. The other actions, including newFile, open, and custom are invoked the same way.

Parámetros de activaciónActivation parameters

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.In the previous scenarios, your file handler app requires details, called activation parameters, about the file, tenant, Office 365 client, etc., to work with the selected file. Office 365 includes these details as form data sent in the POST request to the file handler endpoint associated with the user's action. These parameters are included in the request with the MIME type application/x-www-form-urlencoded and are URL encoded in the body of the request.

Se proporcionan los siguientes parámetros en los parámetros de activación:The following parameters are provided in the activation parameters:

Nombre del parámetroParameter Name TipoType DescripciónDescription
cultureNamecultureName stringstring El identificador de la configuración regional para el idioma para mostrar actual del usuario.The locale identifier for the user's current display language.
clientclient stringstring La aplicación de Office 365 desde la que se ha invocado el controlador de archivos; por ejemplo, "SharePoint" o "OneDrive".The Office 365 application from which the file handler was invoked; for example "SharePoint" or "OneDrive".
userIduserId stringstring El correo electrónico de UPN o inicio de sesión del usuario que ha invocado el controlador de archivos.The UPN/login email for the user who invoked the file handler.
domainHintdomainHint stringstring Una cadena de sugerencia de dominio que indica organizations o consumers.A domain hint string that indicates either organizations or consumers.
itemsitems Colección de cadenas JSON de direcciones URLJSON string collection of URLs Una colección de direcciones URL de Microsoft Graph a los elementos seleccionados.A collection of Microsoft Graph URLs to the selected item(s).

Estos valores están codificados en la solicitud POST como valores de formulario.These values are encoded in the POST request as form values.

Aquí se muestra una solicitud de ejemplo que se enviará al punto de conexión del controlador de archivos:Here is an example request that will be sent to the file handler endpoint:

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).Note: The URLs returned in the items collection may be very long (but less than the maximum URL length of 2048 characters). 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.Each URL contains a token embedded in the URL that allows the file handler app to access the content without a full-trust permission scope. 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.However, your file handler endpoint should ensure it expects long URLs to be returned and handles them correctly.

Para los desarrolladores de ASP.NET, puede tener acceso a estos valores con la colección Request.Form, por ejemplo:For ASP.NET developers, you can access these values using the Request.Form collection, for example:

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.The activation parameters should be cached when the request comes in, either using a server-side cache or via cookies on the response. For the initial file handler request, it's likely that the file handler app will need to redirect the user to retrieve an accessToken via Azure Active Directory OAuth2 experience. The activation parameters will be lost if not persisted before this redirect occurs.

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.You can see an example of using a data model object and handler method for caching the activation parameters in a cookie, in either the C# or TypeScript examples linked below in the example solutions.

Soluciones de ejemplo para controladores de archivosFile Handler example solutions

Autenticación sin interrupciones con los controladores de archivos 2.0Seamless authentication with file handlers 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.After your file handler has received a request with activation parameters, it will need to retrieve an access token to make API calls to 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.Your app will need to call the Azure Active Directory authentication endpoint to retrieve an access token for the signed in user. 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.To enable single sign-on and avoid prompting the user to select an account, you can use the login_hint parameter and provide the value of the userId activation parameter.

En algunos escenarios, es posible que el controlador de archivos pida al usuario iniciar sesión.In some scenarios, your file handler may need to prompt the user to sign-in. 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.If your file handler is running as a preview action, you cannot redirect to the sign-in experience inside an IFRAME and will need to popup the sign-in experience for your file handler.

Disponibilidad del controlador de archivosFile handler availability

En la tabla siguiente se muestran los servicios de Office 365 que admiten controladores de archivos.The following table lists the Office 365 services that support file handlers.

Nombre del servicioService name Controladores de archivos 2.0File handlers 2.0 Controladores de archivos 1.0File handlers 1.0
SharePoint OnlineSharePoint Online Disponible de manera generalizada (GA)Generally available (GA) GAGA
OneDrive para la EmpresaOneDrive for Business GAGA GAGA
OneDrive PersonalOneDrive personal No disponibleNot available No disponibleNot available
Outlook Web AppOutlook Web App No disponibleNot available GAGA