Abrir ficheiros do Office a partir da sua aplicação

Aplica-se a: Programador

Abra ficheiros do Office a partir da sua aplicação SharePoint Embedded com os metadados do DriveItem do Microsoft Graph e os padrões de início do Office suportados pelo Microsoft 365.

Conclua Carregar, transferir e gerir ficheiros primeiro para que a sua aplicação tenha ficheiros para iniciar.

Compreender as experiências do Office

As experiências de ficheiros do Office do SharePoint Embedded funcionam de forma semelhante às experiências de ficheiros do Microsoft 365. As experiências suportadas incluem:

• Abrir documentos do Office no Office para a Web.
• Abrir documentos do Office em clientes de ambiente de trabalho do Office.
• Ver e editar ficheiros.
• Guardar Automaticamente para ficheiros Word, Excel e PowerPoint.
• Histórico de versões para documentos do Office.
• Coautoria.
• Partilha e ligações partilháveis.
• Comentários e menções, com limitações documentadas.
• Trilhos em clientes do Office que associam um ficheiro à sua aplicação.

Observação

Os documentos armazenados num contentor arquivado não podem ser visualizados ou acedidos. A sua aplicação tem de processar o estado arquivado ao mostrar um erro adequado e ao orientar os utilizadores nos próximos passos, como reativar o contentor.

Pré-requisitos

Antes de iniciar ficheiros do Office, certifique-se de que:

• O ficheiro é armazenado num contentor do SharePoint Embedded.
• A aplicação pode ler os metadados do DriveItem para o ficheiro.
• O utilizador tem permissão para ver ou editar o ficheiro.
• O tipo de ficheiro é suportado pelo cliente do Office de destino.
• A sua aplicação processa redirecionamentos do browser ou comportamento de janela nova.

Obter o URL Web do DriveItem

Quando a sua aplicação obtém um DriveItem do Microsoft Graph, a resposta pode incluir webUrl.

Para tipos de ficheiro do Office suportados, webUrl aponta para um URL que abre o documento no Office para a Web.

Um URL da Web do Office suportado 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 do pedido, veja Obter um recurso DriveItem.

Iniciar Office para a Web

Utilize o DriveItem webUrl quando a sua aplicação abrir o Office no browser.

1. Leia o DriveItem do ficheiro selecionado.
2. Confirme se a resposta inclui webUrl.
3. Abra o URL num separador do browser, janela ou superfície de navegação controlada por aplicações.
4. Preserve o contexto da aplicação para que os utilizadores possam regressar após a edição.
5. Processe erros de acesso negado ao verificar as permissões de ficheiro e a associação ao contentor.

Observação

Os ficheiros do Office utilizam a funcionalidade Guardar Automaticamente quando os utilizadores editam ficheiros Word, Excel e PowerPoint armazenados no SharePoint Embedded.

Configurar a experiência de início predefinida

Por predefinição, o 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 visualização só de leitura.
• action=edit para edição quando o utilizador tem permissão de edição.
• action=default quando o Office deve escolher o comportamento predefinido.

Para obter os valores suportados action , veja Web Application Open Platform Interface actions (Ações da Interface De Plataforma Aberta da Aplicação Web).

Abrir ficheiros em clientes de ambiente de trabalho do Office

Utilize esquemas de URI do Office quando a sua aplicação deve abrir clientes de ambiente de trabalho diretamente.

O formato é:

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

Os valores comuns incluem:

Segmento	Valor
Nome do esquema	ms-word, ms-excel ou ms-powerpoint
Comando Abrir Vista de Ficheiro	ofv
Comando Abrir Edição de Ficheiro	ofe
Descritor de URL	u

Exemplos:

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

Observação

O URI tem de ser aberto numa janela em branco ou num novo separador.

Criar um URL de cliente de ambiente de trabalho

Uma vez webUrl que aponta para documentos do Office Online para o Office, crie o URI de ambiente de trabalho em dois passos:

1. Obtenha o webUrl da pasta principal.
2. Acrescente o nome do ficheiro.

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 sobre o esquema, veja Esquemas de URI do Office.

Configurar o comportamento de redirecionamento

Utilize as definições de redirecionamento para encaminhar os utilizadores de volta para a sua aplicação quando o Microsoft 365 não consegue abrir um ficheiro num visualizador suportado.

ApplicationRedirectUrl configura o URL de redirecionamento da aplicação no tipo de contentor. Utilize-a para a rota da aplicação que processa cenários de devolução de ficheiros para a carga de trabalho.

A urlTemplate definição controla onde o Microsoft 365 envia aos utilizadores ficheiros sem um visualizador suportado. Os ficheiros de visualizador Web do Office suportados, como Word, Excel e PowerPoint, são abertos no visualizador Web do Office. Os ficheiros PDF são abertos no visualizador incorporado. Outros tipos de ficheiro são redirecionados urlTemplate quando estão configurados. Se urlTemplate não estiver configurado, o Microsoft 365 envia os utilizadores para uma página de ajuda da Microsoft.

Defina settings.urlTemplate com a Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} API. Utilize um URL absoluto https:// válido que não resolve a 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 os tokens suportados, codifica os respetivos valores e substitui-os pelo modelo. Os tokens comuns incluem {tenant-id}, {drive-id}, {folder-id}, {item-id}, {site-domain}, e {site-url}{list-id}.

Quando a aplicação receber um urlTemplate redirecionamento, autentique o utilizador, analise os valores do token e utilize o Microsoft Graph para obter o ficheiro. Se precisar do URL do ficheiro canónico, utilize a propriedade DriveItem webDavUrl em vez de webUrl.

Quando cria redirecionamentos:

• Utilize um URL de produção estável para a sua aplicação.
• Utilize URLs de desenvolvimento apenas para trabalhos locais ou de avaliação.
• Mantenha Microsoft Entra ID URIs de redirecionamento alinhados com as rotas da aplicação.
• Confirme que os utilizadores regressam ao contexto na aplicação correto após as ações do Office.
• Evite a reescrita de URL que remove os parâmetros de consulta do Office necessários.
• Verifique urlTemplate depois das atualizações porque os valores inválidos são armazenados como null.

Suporte para partilha e cocriação

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

Os utilizadores podem partilhar documentos, criar ligações partilháveis, cocriar em tempo real, ver indicadores de presença, utilizar comentários e utilizar menções sempre que suportado.

Quando um utilizador cria uma ligação de partilha, escolhe a quem concede acesso:

Âmbito de partilha	Quem pode utilizar a ligação
Qualquer pessoa	Qualquer pessoa que receba a ligação, incluindo pessoas fora da sua organização, quer a envie diretamente ou seja reencaminhada.
Somente pessoas em sua organização	Qualquer pessoa na sua organização que tenha a ligação, seja enviada diretamente ou reencaminhada.
Pessoas específicas	Apenas as pessoas que especificar. Se o convite for reencaminhado, apenas as pessoas que já têm acesso podem utilizar a ligação.
Pessoas com acesso existente	People que já têm acesso ao ficheiro ou pasta. Este âmbito não altera as permissões existentes.

Observação

As menções exigem que os utilizadores de destino tenham uma licença do Microsoft 365 atribuída. As menções estão restritas a pessoas dentro da organização do inquilino que consomem e excluem convidados e utilizadores de outros inquilinos em definições multi-inquilino.

Utilizar o histórico de versões

O controlo de versões é ativado automaticamente para ficheiros Word, Excel e PowerPoint armazenados em aplicações do SharePoint Embedded.

Os utilizadores podem ver alterações, comparar versões, restaurar versões anteriores, recuperar de erros e rever as alterações das sessões de cocriação.

Utilizar propriedades de trilho

Os clientes do Office podem apresentar elementos de estilo breadcrumb que associam ficheiros do Office à sua aplicação.

Os padrões de trilho são construídos a partir de propriedades de contentor configuradas para a sua aplicação.

Utilize o Canal Atual para obter padrões de trilho e futuros melhoramentos de aplicações do Office.

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

Validar a iniciação do Office

Testar cada caminho de iniciação:

1. Carregue um documento Word para um contentor.
2. Leia o DriveItem e capture webUrl.
3. Abra webUrl com action=default.
4. Modifique a cadeia de consulta para action=view.
5. Modifique a cadeia de consulta para action=edit.
6. Crie um esquema de URI do Office para iniciar o ambiente de trabalho.
7. Confirme se as permissões bloqueiam a edição quando apropriado.
8. Confirme o comportamento da gravação automática e do histórico de versões.
9. Confirme que o utilizador pode regressar à sua aplicação.

Resolver problemas de iniciação do Office

Sintoma	Verificar
O URL é aberto na vista em vez de editar	action permissão de edição de parâmetros e utilizadores.
O cliente de ambiente de trabalho não abre	Esquema de URI do Office, política de browser e comportamento de novo separador.
O utilizador não pode cocriar	Tipo de ficheiro, permissões e suporte de cliente do Office.
As menções não encontram um utilizador	Limitações de licenças e associações de inquilinos do Microsoft 365.
O trilho não parece certo	Propriedades do contentor e canal de atualização do Office.
Redirecionamento regressa à rota errada	ApplicationRedirectUrl e processamento de rotas de aplicações.

Próximas etapas

Adicione pré-visualizações incorporadas em Ficheiros de pré-visualização na sua aplicação.