Carregar, baixar e gerenciar arquivos

Aplica-se a: Desenvolvedor

Use as APIs de arquivo do Microsoft Graph e DriveItem para gerenciar arquivos dentro de contêineres do SharePoint Embedded.

Concluído: Crie e gerencie contêineres primeiro para que você tenha uma ID de contêiner.

O SharePoint Embedded oferece ao aplicativo um repositório de documentos somente API com recursos internos do Microsoft 365. O gerenciamento de arquivos é totalmente programático por meio do Microsoft Graph, sem nenhuma interface do usuário do SharePoint. O ciclo de vida completo inclui upload e download, pastas, controle de versão, uma lixeira e restauração de conteúdo em 93 dias. O conteúdo é pesquisável por meio da API de Pesquisa da Microsoft e herda a conformidade do locatário com o Microsoft Purview. Os usuários finais do seu aplicativo não precisam de uma licença do Microsoft 365 para operações básicas de arquivo.

Entender o armazenamento de arquivos

Um contêiner do SharePoint Embedded é o limite de armazenamento para o conteúdo do aplicativo.

Cada contêiner expõe o conteúdo do arquivo por meio do armazenamento de arquivos do Microsoft Graph e das APIs DriveItem.

Use seu modelo de dados de aplicativo para decidir qual objeto de negócios possui cada contêiner, quais pastas seu aplicativo cria, quais usuários ou serviços podem ler e gravar e quais IDs de arquivo seu aplicativo armazena.

Para arquitetura, consulte Arquitetura de aplicativos do SharePoint Embedded.

Usar APIs de armazenamento de arquivos do Microsoft Graph

Comece com estas referências do Microsoft Graph:

• tipo de recurso fileStorageContainer
• tipo de recurso DriveItem
• Visão geral do armazenamento de arquivos do Microsoft Graph

Pré-requisitos

Antes de gerenciar arquivos, verifique se:

• Seu aplicativo pode adquirir tokens do Microsoft Graph.
• O aplicativo tem FileStorageContainer.Selected consentimento.
• O aplicativo tem permissões de tipo de contêiner para as operações pretendidas.
• O contêiner de destino existe.
• Para chamadas delegadas, o usuário é um membro do contêiner.
• Seu aplicativo armazena a ID do contêiner e as IDs DriveItem necessárias.

Mapear IDs de contêiner para unidades

As APIs DriveItem do Microsoft Graph usam um driveIdarquivo . Para o SharePoint Embedded, a ID da unidade é a ID do contêiner que começa com b!.

Em seu aplicativo:

1. Armazene a ID do contêiner retornada quando o contêiner for criado.
2. Use a ID do contêiner ao chamar APIs DriveItem que exigem um identificador de unidade.
3. IDs de item da loja retornadas por operações de upload ou criação de pasta.
4. Evite reconstruir IDs de URLs.

Carregar arquivos

Use padrões de upload do Microsoft Graph para DriveItems.

Para arquivos pequenos (até 250 MB), use a API de upload simples documentada para DriveItems com um único PUT para o conteúdo do item.

Para arquivos maiores (mais de 250 MB), use uma sessão de upload conforme documentado pelo Microsoft Graph e envie o arquivo em blocos de intervalo de bytes (por exemplo, múltiplos de 320 KB) até que o upload seja concluído.

No seu fluxo de upload:

1. Validar o acesso de gravação.
2. Escolha uma pasta de destino no contêiner.
3. Crie pastas primeiro se o caminho não existir.
4. Carregue os bytes do arquivo com o método do Graph apropriado.
5. Armazena a ID DriveItem retornada.
6. Exibir nome, tamanho e status do arquivo.

Baixar arquivos

Usar os recursos de download do Microsoft Graph DriveItem para conteúdo de arquivo.

No seu fluxo de download:

1. Validar o acesso de leitura.
2. Resolva a ID do contêiner e a ID do DriveItem.
3. Solicite o conteúdo do arquivo ou baixe a URL usando as APIs DriveItem.
4. Stream o conteúdo para o usuário ou serviço.
5. Lida com a expiração para URLs de download de curta duração.
6. Faça o log de acordo com seus requisitos de auditoria.

Criar pastas

Use APIs de criação de pasta DriveItem para organizar o conteúdo.

Crie pastas para estrutura de conteúdo previsível, estágios de fluxo de trabalho, uploads relacionados e itens pai estáveis para URLs de inicialização do Office.

Ao criar pastas:

1. Verifique se a pasta existe.
2. Crie somente o segmento de caminho que está faltando.
3. Armazene a pasta ID do DriveItem, se necessário.
4. Aplicar regras de nomenclatura de forma consistente.

Atualizar o conteúdo do arquivo

Use o Microsoft Graph DriveItem atualizar ou carregar padrões de sessão para substituir o conteúdo.

Antes de substituir o conteúdo:

• Confirme a permissão de gravação.
• Leia os metadados atuais se forem necessárias verificações de simultaneidade.
• Preserve a ID DriveItem quando tiver suporte.
• Atualize os metadados do aplicativo após o Graph ser bem-sucedido.

Os arquivos do Office armazenados no SharePoint Embedded têm o controle de versão habilitado automaticamente para o Word, Excel e PowerPoint.

Consulte Abrir arquivos do Office a partir do seu aplicativo para obter o comportamento do Office.

Renomear ou mover itens

Usar operações de atualização e movimentação de DriveItem documentadas quando houver suporte.

Leia o DriveItem atual, confirme a pasta de destino, aplique a operação, atualize o caminho armazenado ou o nome de exibição e mantenha a ID do DriveItem como a referência durável quando possível.

Excluir arquivos

Use operações de exclusão quando um arquivo não aparecer mais na experiência de conteúdo ativo.

Antes de excluir:

• Confirme a intenção do usuário.
• Confirme a permissão de gravação ou exclusão.
• Decida se o seu aplicativo precisa de exclusão temporária.
• Atualize o estado do aplicativo somente depois que o Graph retornar êxito.

Restaurar arquivos

Use os recursos de restauração de arquivos do Microsoft Graph e do SharePoint documentados para DriveItems e a experiência de serviço.

Identifique o item ou a versão excluída, confirme a permissão, realize a restauração, atualize a lista de itens e comunique o local restaurado.

Conectar-se ao Office e visualizar experiências

Após o upload, adicione experiências mais ricas:

• Abrir arquivos do Office do seu aplicativo para o comportamento de inicialização do Word, Excel e PowerPoint.
• Visualize os arquivos no seu aplicativo para visualizações do navegador.
• Pesquisar contêineres e arquivos para descoberta.

Validar operações de arquivo

Crie um teste de fumaça:

1. Crie um contêiner de teste.
2. Crie uma pasta.
3. Carregar um arquivo.
4. Leia os metadados DriveItem retornados.
5. Baixe o arquivo.
6. Substitua o conteúdo.
7. Renomeie o arquivo.
8. Exclua o arquivo.
9. Restaure-o se tiver suporte.
10. Limpe o recipiente de teste.

Solucionar problemas com operações de arquivo

Próximas etapas

Habilite experiências de inicialização do Office em Abra arquivos do Office do seu aplicativo.