Carregar, transferir e gerir ficheiros

Aplica-se a: Programador

Utilize o ficheiro do Microsoft Graph e as APIs DriveItem para gerir ficheiros dentro de contentores do SharePoint Embedded.

Conclua Primeiro Criar e gerir contentores para que tenha um ID de contentor.

Compreender o armazenamento de ficheiros

Um contentor do SharePoint Embedded é o limite de armazenamento para o conteúdo da sua aplicação.

Cada contentor expõe o conteúdo do ficheiro através do armazenamento de ficheiros do Microsoft Graph e das APIs DriveItem.

Utilize o seu modelo de dados de aplicação para decidir que objeto de negócio é proprietário de cada contentor, que pastas a sua aplicação cria, que utilizadores ou serviços podem ler e escrever e quais os IDs de ficheiro que a sua aplicação armazena.

Para arquitetura, veja Arquitetura da aplicação SharePoint Embedded.

Utilizar as APIs de armazenamento de ficheiros do Microsoft Graph

Comece com estas referências do Microsoft Graph:

Importante

Utilize o DriveItem do Microsoft Graph documentado e as APIs de armazenamento de ficheiros. Não invente nomes de API de ficheiro específicos do SharePoint Embedded.

Pré-requisitos

Antes de gerir ficheiros, certifique-se de que:

  • A sua aplicação pode adquirir tokens do Microsoft Graph.
  • A aplicação tem FileStorageContainer.Selected consentimento.
  • A aplicação tem permissões de tipo de contentor para as operações pretendidas.
  • O contentor de destino existe.
  • Para chamadas delegadas, o utilizador é membro do contentor.
  • A sua aplicação armazena o ID de contentor e os IDs de DriveItem de que necessita.

Mapear IDs de contentor para unidades

A origem de pré-visualização indica que o ponto final de pré-visualização do Graph utiliza um driveIde, para o SharePoint Embedded, o ID da unidade é o ID de contentor que começa com b!.

Na sua aplicação:

  1. Armazene o ID de contentor devolvido quando o contentor é criado.

  2. Utilize o ID do contentor ao chamar APIs DriveItem que requerem um identificador de unidade.

  3. Armazene os IDs de itens devolvidos pelas operações de criação de pastas ou carregamentos.

  4. Evite reconstruir IDs a partir de URLs.

Carregar arquivos

Utilize padrões de carregamento do Microsoft Graph para DriveItems.

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

Para ficheiros maiores (mais de 250 MB), utilize uma sessão de carregamento conforme documentado pelo Microsoft Graph e envie o ficheiro em segmentos de intervalo de bytes (por exemplo, múltiplos de 320 KB) até que o carregamento seja concluído.

No fluxo de carregamento:

  1. Validar o acesso de escrita.
  2. Escolha uma pasta de destino no contentor.
  3. Crie pastas primeiro se o caminho não existir.
  4. Carregue bytes de ficheiro com o método Graph adequado.
  5. Armazene o ID de DriveItem devolvido.
  6. Apresentar nome de ficheiro, tamanho e status.

Dica

Mantenha os metadados empresariais na base de dados da aplicação e mantenha o conteúdo do ficheiro no SharePoint Embedded.

Baixar arquivos

Utilize as capacidades de transferência do DriveItem do Microsoft Graph para conteúdos de ficheiros.

No fluxo de transferência:

  1. Validar o acesso de leitura.
  2. Resolva o ID do contentor e o ID do DriveItem.
  3. Peça o conteúdo do ficheiro ou transfira o URL com as APIs DriveItem.
  4. Stream o conteúdo ao utilizador ou serviço.
  5. Processe a expiração dos URLs de transferência de curta duração.
  6. Registe de acordo com os seus requisitos de auditoria.

Criar pastas

Utilize as APIs de criação de pastas DriveItem para organizar o conteúdo.

Crie pastas para estrutura de conteúdo previsível, fases de fluxo de trabalho, carregamentos relacionados e itens principais estáveis para URLs de início do Office.

Ao criar pastas:

  1. Verifique se a pasta existe.
  2. Crie apenas o segmento de caminho em falta.
  3. Armazene a pasta DriveItem ID, se necessário.
  4. Aplicar regras de nomenclatura de forma consistente.

Atualizar conteúdo do ficheiro

Utilize os padrões de atualização do DriveItem do Microsoft Graph ou carregue padrões de sessão para substituir conteúdo.

Antes de substituir o conteúdo:

  • Confirme a permissão de escrita.
  • Leia os metadados atuais se forem necessárias verificações de simultaneidade.
  • Preserve o ID do DriveItem, onde for suportado.
  • Atualize os metadados da aplicação após o Graph ser bem-sucedido.

Os ficheiros do Office armazenados no SharePoint Embedded têm o controlo de versões ativado automaticamente para ficheiros Word, Excel e PowerPoint.

Consulte Abrir ficheiros do Office a partir da sua aplicação para obter o comportamento do Office.

Mudar o nome ou mover itens

Utilize operações documentadas de atualização e movimentação do DriveItem, sempre que suportadas.

Um fluxo seguro deve ler o DriveItem atual, confirmar a pasta de destino, aplicar a operação, atualizar o caminho armazenado ou o nome a apresentar e manter o ID do DriveItem como referência durável sempre que possível.

Eliminar ficheiros

Utilize operações de eliminação quando um ficheiro já não deve aparecer na experiência de conteúdo ativo.

Antes de eliminar:

  • Confirme a intenção do utilizador.
  • Confirme a permissão de escrita ou eliminação.
  • Decida se a sua aplicação precisa de eliminação recuperável.
  • Atualize o estado da aplicação apenas depois de o Graph devolver êxito.

Restaurar ficheiros

Utilize as capacidades de restauro de ficheiros do Microsoft Graph e do SharePoint documentadas para DriveItems e a experiência de serviço.

Um fluxo de restauro deve identificar o item ou versão eliminado, confirmar a permissão, executar o restauro, atualizar a lista de itens e comunicar a localização restaurada.

Observação

recycleBinItem: o restauro suporta driveItemId como uma chave alternativa (outubro de 2025). Se souber o ID do driveItem original, pode restaurar a reciclagem CorrespondenteBinItem diretamente sem enumerar primeiro a reciclagem.

Observação

Para obter os detalhes exatos do pedido e da resposta da operação de ficheiro, utilize a documentação do DriveItem do Microsoft Graph.

Ligar ao Office e experiências de pré-visualização

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

Validar operações de ficheiros

Criar um teste rápido:

  1. Crie um contentor de teste.
  2. Crie uma pasta.
  3. Carregue um ficheiro.
  4. Leia os metadados driveItem devolvidos.
  5. Transfira o ficheiro.
  6. Substitua o conteúdo.
  7. Mude o nome do ficheiro.
  8. Exclua o arquivo.
  9. Restaure-o se for suportado.
  10. Limpe o contentor de teste.

Resolver problemas de operações de ficheiros

Sintoma Verificar
Falha no carregamento WriteContent permissão e função de escritor do utilizador.
Falha na transferência ReadContent permissão e função de Leitor de utilizador.
Falha na criação de pastas ID da pasta principal e permissões de escrita.
Falha na pré-visualização Suporte de tipo de ficheiro e geração de URL de pré-visualização.
O início do Office abre o modo incorreto Inicie o parâmetro URL action ou o esquema de URI do Office.
O acesso difere por utilizador O acesso delegado interseciona as permissões da aplicação com a associação.

Próximas etapas

Ative as experiências de início do Office em Abrir ficheiros do Office a partir da sua aplicação.

  • Last updated on