driveItem: createUploadSession

  • Artigo

Namespace: microsoft.graph

Crie uma sessão de upload para permitir que seu aplicativo carregue arquivos até o tamanho máximo de arquivo. Uma sessão de upload permite que seu aplicativo carregue intervalos do arquivo em solicitações sequenciais de API. As sessões de carregamento também permitem que a transferência seja retomada se uma conexão for descartada enquanto o carregamento estiver em andamento.

Para carregar um arquivo usando uma sessão de upload:

  1. Criar uma sessão de upload
  2. Carregar bytes na sessão de upload

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet
✅ ✅ ✅ ✅

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões privilegiadas mais altas
Delegado (conta corporativa ou de estudante) Files.ReadWrite Files.ReadWrite.All, Sites.ReadWrite.All
Delegado (conta pessoal da Microsoft) Files.ReadWrite Files.ReadWrite.All
Aplicativo Sites.ReadWrite.All Indisponível.

Criar uma sessão de upload

Para iniciar o upload de um arquivo grande, seu aplicativo deve primeiro solicitar uma nova sessão de upload. Essa solicitação cria um local de armazenamento temporário em que os bytes do arquivo são salvos até que o arquivo completo seja carregado. Quando o último byte do arquivo é carregado, a sessão de carregamento é concluída e o arquivo final é mostrado na pasta de destino. Como alternativa, você pode adiar a criação final do arquivo no destino até fazer explicitamente uma solicitação para concluir o upload, definindo a propriedade deferCommit nos argumentos de solicitação.

Solicitação HTTP

Para carregar um novo arquivo, você deve fornecer a ID pai e o novo nome do arquivo na solicitação. No entanto, uma atualização requer apenas a ID do item que será atualizado.

Criar um novo arquivo

POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession

Atualizar o arquivo existente

POST /drives/{driveId}/items/{itemId}/createUploadSession
POST /groups/{groupId}/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{itemId}/createUploadSession
POST /me/drive/items/{parentItemId}:/{fileName}:/createUploadSession
POST /sites/{siteId}/drive/items/{itemId}/createUploadSession
POST /users/{userId}/drive/items/{itemId}/createUploadSession

Cabeçalhos de solicitação

Nome Valor Descrição
if-match etag Se esse cabeçalho de solicitação estiver incluído e a eTag (ou cTag) fornecida não corresponder à etag atual no item, uma 412 Precondition Failed resposta de erro será retornada.
if-none-match etag Se esse cabeçalho de solicitação for incluído e a eTag (ou cTag) fornecida corresponder à etag atual no item, uma 412 Precondition Failed resposta de erro será retornada.

Corpo da solicitação

Nenhum corpo de solicitação é obrigatório. No entanto, você pode especificar propriedades no corpo da solicitação para fornecer mais informações sobre o arquivo que está sendo carregado e personalizar a semântica da operação de carregamento.

Por exemplo, a propriedade do item permite definir os seguintes parâmetros:

{
  "@microsoft.graph.conflictBehavior": "fail (default) | replace | rename",
  "description": "description",
  "driveItemSource": { "@odata.type": "microsoft.graph.driveItemSource" },
  "fileSize": 1234,
  "name": "filename.txt",
  "mediaSource": { "@odata.type": "microsoft.graph.mediaSource" }
}

O exemplo a seguir controla o comportamento se o nome do arquivo já estiver tomado. O exemplo também especifica que o arquivo final não deve ser criado até que uma solicitação de conclusão explícita seja feita.

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename"
  },
  "deferCommit": true
}

Cabeçalhos de solicitação opcionais

Nome Valor Descrição
if-match etag Se esse cabeçalho de solicitação estiver incluído e a eTag (ou cTag) fornecida não corresponder à etag atual no item, uma 412 Precondition Failed resposta de erro será retornada.

Parâmetros

Parâmetro Tipo Descrição
deferCommit Booliano Se definido como true, a criação final do arquivo no destino exigirá uma solicitação explícita.
item driveItemUploadableProperties Dados sobre o arquivo sendo carregado.

Solicitação

A resposta a essa solicitação fornece os detalhes do uploadSession recém-criado, que inclui a URL usada para carregar as partes do arquivo.

Observação: O {item-path} deve conter o nome do item especificado no corpo da solicitação.

POST /me/drive/items/{itemID}:/{item-path}:/createUploadSession
Content-Type: application/json

{
  "item": {
    "@microsoft.graph.conflictBehavior": "rename",
    "name": "largefile.dat"
  }
}

Resposta

A resposta a essa solicitação, se tiver êxito, fornecerá os detalhes sobre o local para onde o restante das solicitações deve ser enviado como um recurso UploadSession.

Esse recurso fornece detalhes sobre onde o intervalo de bytes do arquivo deve ser carregado e quando a sessão de carregamento expira.

Se o fileSize parâmetro for especificado e exceder a cota disponível, uma 507 Insufficent Storage resposta será retornada e a sessão de carregamento não será criada.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "uploadUrl": "https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337",
  "expirationDateTime": "2015-01-29T09:21:55.523Z"
}

Carregar bytes na sessão de upload

Para carregar o arquivo, ou uma parte do arquivo, o aplicativo faz uma solicitação PUT ao valor de uploadUrl recebido na de createUploadSession. Você pode carregar o arquivo inteiro ou dividi-lo em vários intervalos de byte, desde que o máximo de bytes em qualquer solicitação específica seja menor que 60 MiB.

Os fragmentos do arquivo devem ser carregados sequencialmente em ordem. Carregar fragmentos fora de ordem resulta em um erro.

Observação: se seu aplicativo dividir um arquivo em vários intervalos de byte, o tamanho de cada intervalo de bytes DEVE ser um múltiplo de 320 KiB (327.680 bytes).

O uso de um tamanho de fragmento que não é dividido uniformemente por 320 KiB resulta em erros que cometem alguns arquivos.

Exemplo

Neste exemplo, o aplicativo está carregando os primeiros 26 bytes de um arquivo de 128 bytes.

  • O cabeçalho Content-Length especifica o tamanho da solicitação atual.
  • O cabeçalho Content-Range indica o intervalo de bytes no arquivo geral que essa solicitação representa.
  • O tamanho total do arquivo precisa ser conhecido antes que você possa carregar seu primeiro fragmento.
PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 26
Content-Range: bytes 0-25/128

<bytes 0-25 of the file>

Observação

  • Para carregar arquivos grandes usando SDKs, consulte Carregar arquivos grandes usando os SDKs do Microsoft Graph.
  • Seu aplicativo deve garantir que o tamanho total do arquivo especificado no cabeçalho Intervalo de Conteúdo seja o mesmo para todas as solicitações. Se um intervalo de bytes declarar um tamanho de arquivo diferente, a solicitação falhará.

Resposta

Quando a solicitação for concluída, o servidor responderá com 202 Accepted se houver mais intervalos de bytes que precisam ser carregados.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["26-"]
}

O aplicativo pode usar o valor de nextExpectedRanges para determinar onde iniciar o próximo intervalo de bytes. Você pode ver vários intervalos especificados, indicando partes do arquivo que o servidor ainda não recebeu. Isso é útil quando você precisa retomar uma transferência que foi interrompida, e seu cliente não tem certeza sobre o estado no serviço.

Você sempre deve determinar o tamanho dos intervalos de byte de acordo com as práticas recomendadas a seguir. Não suponha que nextExpectedRanges retornará intervalos de tamanho adequado para um intervalo de bytes a ser carregado. A propriedade nextExpectedRanges indica intervalos do arquivo que não foram recebidos e não um padrão de como seu aplicativo deve carregar o arquivo.

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": [
  "12345-55232",
  "77829-99375"
  ]
}

Comentários

  • A nextExpectedRanges propriedade nem sempre lista todos os intervalos ausentes.
  • Em gravações de fragmento bem-sucedidas, ele retornará o próximo intervalo a ser iniciado (por exemplo, "523-").
  • Em falhas quando o cliente enviou um fragmento que o servidor já havia recebido, o servidor responde com HTTP 416 Requested Range Not Satisfiable. Você pode solicitar o status do upload para obter uma lista mais detalhada dos intervalos que estão faltando.
  • Se você incluir o cabeçalho autorização ao emitir a PUT chamada, ele poderá resultar em uma HTTP 401 Unauthorized resposta. Envie apenas o cabeçalho de autorização e o token de portador ao emitir o POST durante a primeira etapa. Não inclua quando você emitir a PUT chamada.

Concluindo um arquivo

Se deferCommit for falso ou não configurado, o carregamento será concluído automaticamente quando o intervalo de bytes final do arquivo for colocado na URL de carregamento.

Se deferCommit for verdadeiro, você pode concluir explicitamente o carregamento de duas maneiras:

  • Após o intervalo de bytes final do arquivo ser colocado na URL de carregamento, envie uma solicitação final de POST para a URL de carregamento com conteúdo de comprimento zero (no momento, com suporte somente no OneDrive for Business e no SharePoint).
  • Após o intervalo de bytes final do arquivo ser COLOCADO na URL de carregamento, envie uma solicitação final de PUT na mesma maneira que você resolveria erros de carregamento (no momento, com suporte somente no OneDrive for Business e no SharePoint).

Quando o upload é concluído, o servidor responde à solicitação final com um HTTP 201 Created ou HTTP 200 OK. O corpo da resposta também incluirá o conjunto de propriedades padrão para o driveItem que representa o arquivo concluído.

PUT https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 21
Content-Range: bytes 101-127/128

<final bytes of the file>

Observação

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

POST https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337
Content-Length: 0

Observação

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

Tratamento de conflitos de carregamento

Se ocorrer um conflito depois do carregamento do arquivo (por exemplo, um item com o mesmo nome foi criado durante a sessão de carregamento), será retornado um erro quando o último intervalo de bytes for carregado.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error":
  {
    "code": "nameAlreadyExists",
    "message": "Another file exists with the same name as the uploaded session. You can redirect the upload session to use a new filename by calling PUT with the new metadata and @microsoft.graph.sourceUrl attribute.",
  }
}

Cancelar a sessão de upload

Para cancelar uma sessão de upload, envie uma solicitação DELETE para o URL de upload. Isso limpa o arquivo temporário que contém os dados anteriormente carregados. Isso deve ser usado em cenários em que o upload é interrompido, por exemplo, se o usuário cancelar a transferência.

Os arquivos temporários e a sessão de carregamento que os acompanha são automaticamente limpos decorrido o valor de expirationDateTime. Os arquivos temporários podem não ser excluídos imediatamente após a decorrido o tempo de expiração.

Solicitação

DELETE https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF866337

Observação

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content

Retomando um upload em andamento

Se uma solicitação de upload for desconectada ou falhar antes de ser concluída, todos os seus bytes serão ignorados. Isso pode ocorrer quando a conexão entre seu aplicativo e o serviço é interrompida. Se isso ocorrer, seu aplicativo ainda poderá retomar a transferência do fragmento anteriormente concluído.

Para descobrir quais intervalos de bytes foram recebidos anteriormente, seu aplicativo pode solicitar o status de uma sessão de upload.

Exemplo

Confira o status do upload enviando uma solicitação GET para uploadUrl.

GET https://sn3302.up.1drv.com/up/fe6987415ace7X4e1eF86633784148bb98a1zjcUhf7b0mpUadahs

O servidor responde com uma lista de intervalos de bytes ausentes que precisam ser carregados e o tempo de validade da sessão de carregamento.

Observação

HTTP/1.1 200 OK
Content-Type: application/json

{
  "expirationDateTime": "2015-01-29T09:21:55.523Z",
  "nextExpectedRanges": ["12345-"]
}

Carregar os dados restantes

Agora que o seu aplicativo sabe de onde começar o upload, retome o upload seguindo as etapas em Carregar bytes na sessão de upload.

Tratar erros de carregamento

Quando o último intervalo de bytes de um arquivo é carregado, é possível que ocorra um erro. Isso pode acontecer devido a um conflito de nomes ou a uma limitação de cota excedida. A sessão de carregamento é preservada até o tempo de validade, o que permite que seu aplicativo recupere o upload cometendo explicitamente a sessão de carregamento.

Para confirmar manualmente a sessão de carregamento, o aplicativo deve fazer uma solicitação PUT com um novo recurso driveItem, que será usado ao confirmar a sessão de carregamento. Essa nova solicitação deve corrigir a origem do erro que gerou o erro de carregamento original.

Para indicar que o aplicativo está confirmando uma sessão de carregamento existente, a solicitação PUT deve incluir a propriedade @microsoft.graph.sourceUrl com o valor de sua URL de sessão de carregamento.

PUT https://graph.microsoft.com/v1.0/me/drive/root:/{path_to_parent}
Content-Type: application/json
If-Match: {etag or ctag}

{
  "name": "largefile.vhd",
  "@microsoft.graph.conflictBehavior": "rename",
  "@microsoft.graph.sourceUrl": "{upload session URL}"
}

Resposta

Se o arquivo puder ser confirmado usando os novos metadados, uma HTTP 201 Created ou HTTP 200 OK resposta será retornada com os metadados item do arquivo carregado.

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "912310013A123",
  "name": "largefile.vhd",
  "size": 128,
  "file": { }
}

Práticas recomendadas

  • Retome ou repita uploads que falharam devido a interrupções de conexão ou erros 5xx, como:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Use uma estratégia de retirada exponencial se erros de servidor 5xx forem retornados ao retomar ou repetir solicitações de upload.
  • Para outros erros, você não deve usar uma estratégia de back off exponencial, mas limitar o número de tentativas de repetição feitas.
  • Lide com erros 404 Not Found ao fazer uploads retomáveis reiniciando o upload inteiro. Isso indica que a sessão de carregamento não existe mais.
  • Use transferências de arquivos retomáveis para arquivos com mais de 10 MiB (10.485.760 bytes).
  • Um tamanho de intervalo de bytes de 10 MiB para conexões estáveis de alta velocidade é ideal. Para conexões mais lentas ou menos confiáveis, você pode obter melhores resultados de um tamanho de fragmento menor. O tamanho do fragmento recomendado é entre 5 e 10 MiB.
  • Use um tamanho de intervalo de bytes que seja múltiplo de 320 KiB (327.680 bytes). Uma falha ao usar um tamanho de fragmento que seja múltiplo de 320 KiB pode resultar na falha de transferências de arquivos grandes após o carregamento do último intervalo de bytes.

Respostas de erros

Consulte o artigo Respostas de Erro para obter detalhes sobre como os erros são retornados.

Conteúdo relacionado

Upload de arquivos grandes