Abrir arquivos do Office a partir do seu aplicativo

Aplica-se a: Desenvolvedor

Abra arquivos do Office do seu aplicativo incorporado do SharePoint usando os metadados DriveItem do Microsoft Graph e os padrões de inicialização do Office compatíveis com o Microsoft 365.

Concluído: carregue, baixe e gerencie os arquivos primeiro para que seu aplicativo tenha arquivos para iniciar.

Quando você armazena arquivos do Office em um contêiner do SharePoint Embedded, seu aplicativo é vinculado a uma pilha de colaboração completa sem criar uma. Os arquivos do Word, Excel e PowerPoint dão suporte à coautoria em tempo real, ao Salvamento Automático, ao histórico de versão automático e ao compartilhamento por meio de links compartilháveis e@mentions, com níveis de acesso no escopo. Você não precisa criar um mecanismo de colaboração. A edição é aberta no Office para a Web (em uma nova guia ou janela do navegador) ou em clientes da área de trabalho do Office, para que os usuários deixem a interface do usuário do seu aplicativo para editar; insira uma visualização somente leitura quando precisar de exibição embutida no aplicativo. Para o contexto de decisão, consulte Adicionar a coautoria do Office sem criá-lo.

Entender as experiências do Office

As experiências de arquivo do Office inseridas no SharePoint funcionam de maneira semelhante às experiências de arquivo do Microsoft 365. As experiências com suporte incluem:

• Abrindo documentos do Office no Office para a Web.
• Abrindo documentos do Office em clientes da área de trabalho do Office.
• Exibir e editar arquivos.
• Salvamento Automático para arquivos do Word, Excel e PowerPoint.
• Histórico de versões de documentos do Office.
• Coautoria.
• Compartilhamento e links compartilháveis.
• Comentários e menções, com limitações documentadas.
• Trilhas estruturais em clientes do Office que associam um arquivo ao seu aplicativo.

Pré-requisitos

Antes de iniciar os arquivos do Office, verifique se:

• O arquivo é armazenado em um contêiner do SharePoint Embedded.
• O aplicativo pode ler os metadados DriveItem do arquivo.
• O usuário tem permissão para exibir ou editar o arquivo.
• O tipo de arquivo é suportado pelo cliente do Office de destino.
• Seu aplicativo lida com redirecionamentos do navegador ou comportamento de nova janela.

Obter a URL da Web do DriveItem

Quando seu aplicativo recupera um DriveItem do Microsoft Graph, a resposta pode incluir webUrl.

Para tipos de arquivo do Office com suporte, webUrl aponta para uma URL que abre o documento no Office para a Web.

Uma URL da Web do Office com suporte tem esta forma:

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

Para obter detalhes da solicitação, consulte Obter um recurso DriveItem.

Iniciar o Office para a Web

Use o DriveItem webUrl quando o aplicativo precisar abrir o Office no navegador.

1. Leia o DriveItem do arquivo selecionado.
2. Confirme se a resposta inclui webUrl.
3. Abra a URL em uma guia do navegador, janela ou superfície de navegação controlada pelo aplicativo.
4. Preserve o contexto do aplicativo para que os usuários possam retornar após a edição.
5. Lidar com erros de acesso negado verificando as permissões de arquivo e a associação de contêiner.

Configurar a experiência de inicialização padrão

Por padrão, a URL do Office inclui action=default.

Para forçar um modo, atualize o parâmetro de consulta com este padrão:

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:

• action=view para exibição somente leitura.
• action=edit para editar quando o usuário tiver permissão de edição.
• action=default quando o Office deve escolher o comportamento padrão.

Para obter valores com suporte action , consulte Ações da Interface de Plataforma Aberta do Aplicativo Web.

Abrir arquivos em clientes de área de trabalho do Office

Use esquemas de URI do Office quando seu aplicativo deve abrir clientes de área de trabalho diretamente.

O formato é:

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

Os valores comuns incluem:

Exemplos:

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

Criar uma URL de cliente de área de trabalho

Como webUrl aponta para o Office Online para documentos do Office, crie o URI da área de trabalho em duas etapas:

1. Obter o webUrl da pasta pai.
2. Acrescente o nome do arquivo.

Padrão de exemplo:

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 obter detalhes do esquema, consulte Esquemas de URI do Office.

Configurar comportamento de redirecionamento

Use as configurações de redirecionamento para direcionar os usuários de volta ao seu aplicativo quando o Microsoft 365 não conseguir abrir um arquivo em um visualizador compatível.

ApplicationRedirectUrl configura a URL de redirecionamento do aplicativo no tipo de contêiner. Use-o para a rota do aplicativo que lida com cenários de retorno de arquivo para sua carga de trabalho.

A urlTemplate configuração controla para onde o Microsoft 365 envia usuários para arquivos sem um visualizador compatível. Arquivos compatíveis com o visualizador da Web do Office, como o Word, Excel e PowerPoint, são abertos no visualizador da Web do Office. Arquivos PDF abertos no visualizador incorporado. Outros tipos de arquivo são redirecionados quando urlTemplate ele é configurado. Se urlTemplate não estiver configurado, o Microsoft 365 enviará os usuários para uma página de ajuda da Microsoft.

Definido settings.urlTemplate com a API do Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} . Use uma URL absoluta https:// válida que não seja resolvida para um endereço de loopback.

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}"
  }
}

O Microsoft 365 resolve tokens compatíveis, codifica seus valores por URL e os substitui no modelo. Por exemplo, os tokens suportados podem incluir {tenant-id}, {drive-id}, {folder-id}, {item-id}{site-domain}, , {list-id}, e {site-url}.

Quando o aplicativo receber um urlTemplate redirecionamento, autentique o usuário, analise os valores do token e use o Microsoft Graph para recuperar o arquivo. Se você precisar da URL do arquivo canônico, use a propriedade DriveItem webDavUrl em vez de webUrl.

Ao criar redirecionamentos:

• Use uma URL de produção estável para seu aplicativo.
• Use URLs de desenvolvimento somente para trabalho local ou de avaliação.
• Mantenha os URIs de redirecionamento do Microsoft Entra ID alinhados com as rotas do aplicativo.
• Valide se os usuários retornam ao contexto correto no aplicativo após as ações do Office.
• Evite a reescrita de URL que remove os parâmetros de consulta necessários do Office.
• Verifique urlTemplate após as atualizações, pois os valores inválidos são armazenados como null.

Suporte ao compartilhamento e à coautoria

As experiências do Office incluem recursos de colaboração.

Os usuários podem compartilhar documentos, criar links compartilháveis, trabalhar em coautoria em tempo real, ver indicadores de presença, usar comentários e usar menções quando há suporte.

Quando um usuário cria um link de compartilhamento, ele escolhe a quem ele concede acesso:

Usar o histórico de versões

O controle de versão é habilitado automaticamente para arquivos do Word, Excel e PowerPoint armazenados em aplicativos incorporados do SharePoint.

Os usuários podem ver alterações, comparar versões, restaurar versões anteriores, recuperar-se de erros e revisar alterações de sessões de coautoria.

Usar propriedades estruturais

Os clientes do Office podem exibir elementos no estilo de trilha que associam arquivos do Office ao seu aplicativo.

Os padrões de trilha são criados a partir das propriedades de contêiner configuradas para seu aplicativo.

Use o canal de atualização do Canal Atual para o Microsoft 365 Apps para que os usuários recebam o comportamento mais recente da trilha do Office e aprimoramentos futuros do aplicativo do Office.

Para obter informações sobre o canal de atualização do Office, consulte Visão geral dos canais de atualização do Microsoft 365 Apps.

Validar lançamento do Office

Teste cada caminho de inicialização:

1. Carregar um documento do Word em um contêiner.
2. Leia o DriveItem e capture webUrlarquivos .
3. Abrir webUrl com action=default.
4. Modifique a cadeia de caracteres de consulta para action=view.
5. Modifique a cadeia de caracteres de consulta para action=edit.
6. Crie um esquema de URI do Office para iniciar a área de trabalho.
7. Confirmar permissões, bloquear edição quando apropriado.
8. Confirme o Salvamento Automático e o comportamento do histórico de versão.
9. Confirme se o usuário pode retornar ao seu aplicativo.

Solucionar problemas de inicialização do Office

Próximas etapas

Adicione visualizações incorporadas em Visualizar arquivos em seu aplicativo.