Adicionar visualização, abertura e ações personalizadas a arquivos com manipuladores de arquivos 2.0

Artigo
04/08/2023

Os manipuladores de arquivos são um tipo de add-in Microsoft 365 que integra tipos de arquivos personalizados ao serviço, permitindo que você forneça experiências ricas para qualquer formato proprietário.

Com os manipuladores de arquivos, você pode habilitar as seguintes experiências de usuário nas bibliotecas de documentos OneDrive for Business e SharePoint:

Ícones de arquivo personalizados (para extensões de arquivo de proprietário)
Criar novos arquivos no navegador (para extensões de arquivo de proprietário)
Visualização de arquivo (para extensões de arquivo de proprietário)
Capacidade avançada para exibir/editar (todas as extensões de arquivo)
Ações personalizadas que iniciam no seu aplicativo (todas as extensões de arquivo)
Tem suporte a seleção múltipla e age em pastas (somente para ações personalizadas)

Confira as soluções de exemplo de manipulador de arquivos para obter mais detalhes.

Importante

As configurações do manipulador de arquivos são agressivamente colocadas em cache em todo o sistema para um ótimo desempenho. Pode levar de 24 a 48 horas para que qualquer mudança de configuração tenha efeito. Consulte Registro para obter informações sobre como configurar os manipuladores de arquivos.

Mudanças nos manipuladores de arquivo 2.0

A atualização 2.0 dos manipuladores de arquivos possibilita novos cenários do SharePoint Online e do OneDrive for Business.

Use a API do Microsoft Graph para acessar arquivos de forma mais robusta, como arquivos de metadados, permissões e compartilhamento.
Adicione botões de ação personalizada que iniciam o suplemento do manipulador de arquivo, com texto personalizado e ícones.

O que há em um manipulador de arquivos

Um manipulador de arquivos é composto dos seguintes componentes:

Ponto de extremidade do manipulador de arquivos. Um aplicativo hospedado pelo provedor que habilita a experiência do seu manipulador de arquivos. Este ponto de extremidade pode, opcionalmente, fornecer uma experiência de criação, visualização e edição de arquivos que são registrados com seu manipulador de arquivos.
Manifesto do manipulador de arquivos. Um conjunto de metadados que define a interação entre o Office 365 e seu ponto de extremidade do manipulador de arquivos.
Aplicativo registrado no Azure Active Directory. Este aplicativo é usado para autorizar o acesso a arquivos selecionados pelo Microsoft Graph e é onde o manifesto do manipulador de arquivos está registrado.

Ponto de extremidade do manipulador de arquivos

O ponto de extremidade do manipulador de arquivos é um aplicativo hospedado na nuvem que contém a lógica funcional de criação, visualização, abertura e salva arquivos do tipo que ele manipula. Ele pode ser hospedado em qualquer pilha, inclusive pilhas que não são da Microsoft. Os manipuladores de arquivos usam o Azure Active Directory para ter acesso autorizado aos recursos do Office 365, por isso, seu aplicativo precisa ser registrado com o Azure AD. Confira mais informações sobre como registrar um aplicativo com o Azure AD em Registrar seu aplicativo do Microsoft Graph.

Para um exemplo completo de um manipulador de arquivos, veja a lista de amostras disponíveis.

Manifesto do manipulador de arquivos

O manifesto define a interação entre o Office 365 e o ponto de extremidade do manipulador de arquivos. O manifesto está registrado no Azure Active Directory, usando a coleção addIns de um objeto de aplicativo no diretório. Para registrar ou atualizar o registro do seu manifesto de manipulador de arquivos, confira Como: registrar um manipulador de arquivos manualmente.

Um exemplo de manipulador de arquivos:

{
    "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 manifesto do manipulador de arquivos inclui os seguintes pares de valor de chave como parte da matriz properties:

Nome da propriedade	Tipo	Descrição
version	String	Especifica a versão do manipulador de arquivos. Esse valor deve ser definido como `2`. Obrigatório para manipuladores de arquivos 2.0.
appIcon	Cadeia de caracteres, JSON codificado	Um conjunto de URLs de ícone em formatos diferentes, usados para representar o aplicativo manipulador de arquivos. Opcional.
fileTypeDisplayName	String	A descrição da localidade padrão para o tipo de arquivo. Opcional.
fileTypeIcon	Cadeia de caracteres, JSON codificado	Um conjunto de URLs de ícone em formatos diferentes, usado para representar tipos de arquivo manipulados por esse manipulador de arquivos. Opcional.
actionMenuDisplayName	String	Opcional. Uma cadeia de caracteres de exibição na localidade padrão, usada quando as ações associadas a esse manipulador de arquivos são recolhidas em um menu.
actions	Cadeia de caracteres, JSON codificado	Uma coleção de ações implementada por esta extensão de manipulador de arquivos. Confira mais informações em Especificação de ações. Obrigatório.

Manipuladores de arquivos em tempo de execução

O suplemento de manipulador arquivos é invocado por meio da URL do ponto de extremidade especificada no manifesto do manipulador de arquivos da ação invocada. Para entender o que acontece, vamos dar uma olhada no cenário no qual um usuário clica para visualizar um arquivo. Se houver um manipulador de arquivos registrado desse tipo de arquivo, o Office 365 invoca o aplicativo do manipulador de arquivos, fazendo uma solicitação POST para a URL especificada da ação de visualização. No corpo da solicitação POST, o Office 365 incluirá os parâmetros de ativação que especificam o arquivo que foi selecionado. Outras ações, incluindo newFile, open e custom são invocados da mesma maneira.

Parâmetros de ativação

Em cenários anteriores, o aplicativo do manipulador de arquivos requer detalhes, parâmetros de ativação chamados, sobre o arquivo, o locatário, o cliente do Office 365, etc., para trabalhar com o arquivo selecionado. O Office 365 inclui esses detalhes como dados de formulário na solicitação POST para o ponto de extremidade do manipulador de arquivos associado com a ação do usuário. Esses parâmetros são incluídos na solicitação com o tipo MIME application/x-www-form-urlencoded e são codificados por URL no corpo da solicitação.

Os parâmetros a seguir são fornecidos nos parâmetros de ativação:

Nome do Parâmetro	Tipo	Descrição
cultureName	string	O identificador de localidade para o idioma de exibição atual do usuário.
client	string	O aplicativo do Office 365 a partir do qual o manipulador de arquivos foi invocado, por exemplo, "SharePoint" ou "OneDrive".
userId	string	O UPN/email de logon do usuário que invocou o manipulador de arquivos.
domainHint	string	Uma cadeia de dica de domínio que indica `organizations` ou `consumers`.
items	Coleção de cadeia de caracteres JSON de URLs	Uma coleção de URLs do Microsoft Graph para os itens selecionados.

Esses valores são codificados na solicitação POST como valores de formulário.

Aqui está um exemplo de solicitação que será enviado para o ponto de extremidade do manipulador de arquivos:

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

Observação: as URLs retornadas no conjunto de itens podem ser muito longas (mas menores do que o comprimento máximo de URL de 2048 caracteres). Cada URL contém um token inserido na URL que permite que o aplicativo manipulador de arquivos acesse o conteúdo sem um escopo de permissão de confiança total. No entanto, o ponto de extremidade do manipulador de arquivos deve assegurar o retorno de URLs longas, e manipulá-las corretamente.

Para desenvolvedores ASP.NET, é possível acessar esses valores usando o conjunto Request.Form, por exemplo:

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

Os parâmetros de ativação devem ser armazenados em cache quando a solicitação chega, seja usando um cache do lado do servidor ou via cookies na resposta. Para a solicitação inicial do manipulador de arquivos, é provável que o aplicativo do manipulador de arquivos precisará redirecionar o usuário para recuperar um accessToken por meio da experiência do Azure Active Directory OAuth2. Os parâmetros de ativação serão perdidos se não forem persistentes antes que este redirecionamento ocorra.

Você pode ver um exemplo do uso de um objeto de modelo de dados e um método de manipulador para armazenar em cache parâmetros de ativação em um cookie, nos exemplos em C# ou TypeScript relacionados abaixo no exemplo de soluções.

Soluções de exemplo do manipulador de arquivos

Autenticação perfeita com manipuladores de arquivos 2.0

Depois de receber uma solicitação com parâmetros de ativação de seu manipulador de arquivos, ele precisará recuperar um token de acesso para fazer chamadas de API para o Microsoft Graph. Seu aplicativo precisará chamar o ponto de extremidade de autenticação do Azure Active Directory para recuperar um token de acesso do usuário conectado. Para habilitar o logon único e evitar solicitar que o usuário selecione uma conta, você pode usar o login_hint parâmetro e fornecer o valor do parâmetro de ativação userId.

Em alguns cenários, talvez seu manipulador de arquivos precise solicitar o logon do usuário. Se o seu manipulador de arquivos estiver em execução como uma ação preview, não será possível redirecionar para a experiência de entrada dentro de um IFRAME, e será necessário mostrar a experiência de entrada como um pop-up para seu manipulador de arquivo.

Disponibilidade do manipulador de arquivos

A tabela a seguir lista os serviços do Office 365 que oferecem suporte aos manipuladores de arquivos.

Nome do serviço	Manipuladores de arquivos 2.0	Manipuladores de arquivos 1.0
SharePoint Online	Geralmente disponível (GA)	GA
OneDrive for Business	GA	GA
OneDrive Pessoal	Não disponível	Não disponível
Outlook Web App	Não disponível	GA

Compartilhar via