driveItem: createUploadSession

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 de API sequenciais. Ele também permite que a transferência seja retomada se a conexão for interrompida durante o upload.

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 de nuvem nacional.

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos 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.

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 onde 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 upload é concluída e o arquivo final é mostrado na pasta de destino. Você também 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 da solicitação.

Solicitação HTTP

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

Criar arquivo

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

Atualizar arquivo existente

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

Cabeçalhos de solicitação

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 item permite definir os seguintes parâmetros:

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

O exemplo a seguir controla o comportamento quando o nome do arquivo já está em uso. Este 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
}

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

Se for bem-sucedida, a resposta a essa solicitação fornecerá os detalhes de onde o restante das solicitações deve ser enviado como um recurso uploadSession .

Quando uma sessão é criada e gera URLs de upload pré-autenticadas, a URL de upload pode ser usada para concluir o upload dentro de uma janela de tempo suficiente para arquivos grandes.

O recurso uploadSession fornece detalhes sobre onde cada intervalo de bytes do arquivo deve ser carregado e especifica quando a sessão expira. A propriedade expirationDateTime indica a hora em que a sessão atual expirará se nenhuma atividade adicional ocorrer. Isso resulta no seguinte comportamento:

• Você deve carregar o próximo fragmento ou confirmar a sessão antes do tempo especificado na propriedade expirationDateTime .
• Cada fragmento carregado estende o tempo de expiração, o que permite que carregamentos de arquivos grandes sejam concluídos com êxito. O tempo de expiração atualizado é retornado em cada solicitação para carregar um fragmento de arquivo.
• Se nenhum fragmento for recebido e a sessão não for confirmada, todos os fragmentos carregados anteriormente serão descartados.

Esse processo suporta uploads de arquivos grandes e garante que as sessões de upload sejam gerenciadas com eficiência, evitando que dados obsoletos ou abandonados permaneçam no sistema por muito tempo.

Se o fileSize parâmetro for especificado e exceder a cota disponível, uma 507 Insufficient Storage resposta será retornada e a sessão de upload 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. O upload de 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).

Usar um tamanho de fragmento que não se divide igualmente por 320 KiB resulta em erros na confirmação de 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>

Resposta

Quando a solicitação for concluída, o servidor responderá dizendo 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 presuma que nextExpectedRanges retorna 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 propriedade nextExpectedRanges nem sempre lista todos os intervalos ausentes.
• Em gravações de fragmento bem-sucedidas, ele retorna o próximo intervalo para começar (por exemplo, 523-).
• Em falhas em que o cliente enviou um fragmento que o servidor já recebeu, o servidor responde com HTTP 416 Requested Range Not Satisfiable. Para obter uma lista mais detalhada de intervalos ausentes, você pode solicitar o upload status.
• Se você incluir o Authorization cabeçalho ao emitir a chamada PUT, isso poderá resultar em uma HTTP 401 Unauthorized resposta. Inclua apenas o cabeçalho e o Authorization token de portador ao emitir a solicitação POST durante a primeira etapa. Não a inclua ao emitir a chamada PUT.

Concluindo um arquivo

Se deferCommit for false ou não definido, o upload será concluído automaticamente quando o intervalo de bytes final do arquivo for PUT para a URL de upload.

Se deferCommit for true, você poderá concluir explicitamente o upload 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 for concluído, o servidor responderá à solicitação final com um HTTP 201 Created ou HTTP 200 OK. O corpo da resposta também inclui a propriedade padrão definida 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>

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

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 não podem ser excluídos imediatamente após o término do tempo de expiração.

Solicitação

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

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 expiração da sessão de carregamento.

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 upload é preservada até o tempo de expiração, o que permite que seu aplicativo recupere o upload confirmando explicitamente a sessão de upload.

Para confirmar explicitamente a sessão de upload, seu aplicativo deve fazer uma solicitação PUT com um novo recurso driveItem a ser usado ao confirmar a sessão de upload. 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/beta/me/drive/root:/{path_to_file}
Content-Type: application/json
If-Match: {etag or ctag}

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

Observação: Você pode usar os cabeçalhos @microsoft.graph.conflictBehavior e if-match conforme esperado nessa chamada.

Resposta

Se o arquivo puder ser confirmado usando os novos metadados, uma HTTP 201 Created resposta or HTTP 200 OK será retornada com os metadados driveItem para o 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 retirada 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 com 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

Para detalhes sobre como os erros são retornados, confira Respostas de erro.

Conteúdo relacionado

Upload de arquivos grandes