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 carregamento permite que a aplicação carregue intervalos do ficheiro em pedidos de API sequenciais. Também permite que a transferência seja retomada se a ligação for removida durante o carregamento.

Para carregar um ficheiro através de uma sessão de carregamento:

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

Esta API está disponível nas seguintes implementações de cloud nacionais.

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja 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. Este pedido cria uma localização de armazenamento temporária onde os bytes do ficheiro são guardados até que o ficheiro completo seja carregado. Quando o último byte do ficheiro é carregado, a sessão de carregamento é concluída e o ficheiro final é apresentado na pasta de destino. Também pode adiar a criação final do ficheiro no destino até fazer explicitamente um pedido para concluir o carregamento ao definir a propriedade deferCommit nos argumentos do pedido.

Solicitação HTTP

Para carregar um novo ficheiro, tem de indicar o ID principal e o novo nome de ficheiro no pedido. No entanto, uma atualização só requer que o ID do item seja atualizado.

Criar novo ficheiro

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 ficheiro 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, pode especificar propriedades no corpo do pedido para fornecer mais informações sobre o ficheiro que está a ser 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 seguinte controla o comportamento quando o nome do ficheiro já está a ser utilizado. Este exemplo também especifica que o ficheiro final não deve ser criado até que seja feito um pedido de conclusão explícito.

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

Solicitação

A resposta a este pedido fornece os detalhes da uploadSession recentemente criada, que inclui o URL utilizado para carregar as partes do ficheiro.

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 este pedido fornece os detalhes de onde os restantes pedidos devem ser enviados como um recurso uploadSession .

Quando uma sessão é criada e gera URLs de carregamento pré-autenticados, o URL de carregamento pode ser utilizado para concluir o carregamento dentro de um período de tempo suficiente para ficheiros grandes.

O recurso uploadSession fornece detalhes sobre onde cada intervalo de bytes do ficheiro deve ser carregado e especifica quando a sessão expira. A propriedade expirationDateTime indica o momento em que a sessão atual expira se não ocorrer mais atividade. Isto resulta no seguinte comportamento:

• Tem de carregar o fragmento seguinte ou consolidar a sessão antes da hora especificada na propriedade expirationDateTime .
• Cada fragmento carregado prolonga o tempo de expiração, o que permite que carregamentos de ficheiros grandes sejam concluídos com êxito. O tempo de expiração atualizado é devolvido em todos os pedidos para carregar um fragmento de ficheiro.
• Se não forem recebidos fragmentos e a sessão não for consolidada, todos os fragmentos carregados anteriormente serão eliminados.

Este processo suporta carregamentos de ficheiros grandes e garante que as sessões de carregamento são geridas de forma eficiente ao impedir que os dados obsoletos ou abandonados fiquem demasiado tempo no sistema.

Se o fileSize parâmetro for especificado e exceder a quota disponível, é devolvida uma 507 Insufficient Storage resposta e a sessão de carregamento não é 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 da ordem resulta num 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).

A utilização de um tamanho de fragmento que não divide uniformemente por 320 KiB resulta em erros ao consolidar alguns ficheiros.

Exemplo

Neste exemplo, a aplicação está a carregar os primeiros 26 bytes de um ficheiro 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 o pedido estiver concluído, o servidor responderá se 202 Accepted existirem mais intervalos de bytes que precisem de 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. Poderá ver vários intervalos especificados, indicando partes do ficheiro 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 devolve intervalos de tamanho adequado para um intervalo de bytes a carregar. A propriedade nextExpectedRanges indica intervalos do ficheiro que não foram recebidos e não um padrão para a forma como a sua aplicação deve carregar o ficheiro.

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 em falta.
• Em escritas de fragmentos com êxito, devolve o intervalo seguinte a partir do (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 dos intervalos em falta, pode pedir o carregamento status.
• Se incluir o cabeçalho ao Authorization emitir a chamada PUT, poderá resultar numa HTTP 401 Unauthorized resposta. Inclua apenas o token de Authorization cabeçalho e portador ao emitir o pedido POST durante o primeiro passo. Não a inclua ao emitir a chamada PUT.

Concluindo um arquivo

Se deferCommit for false ou anular a definição, o carregamento será concluído automaticamente quando o intervalo de bytes final do ficheiro for PUT para o URL de carregamento.

Se deferCommit for true, pode concluir explicitamente o carregamento de duas formas:

• 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 carregamento estiver concluído, o servidor responde ao pedido final com um HTTP 201 Created ou HTTP 200 OK. O corpo da resposta também inclui a propriedade predefinida definida para o driveItem que representa o ficheiro 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 ficheiros temporários podem não ser eliminados imediatamente após o 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 em falta que têm de 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 ficheiro é 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é à hora de expiração, o que permite que a aplicação recupere o carregamento ao consolidar explicitamente a sessão de carregamento.

Para consolidar explicitamente a sessão de carregamento, a sua aplicação tem de fazer um pedido PUT com um novo recurso driveItem para ser utilizado ao consolidar 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/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 ficheiro puder ser consolidado com os novos metadados, é devolvida uma HTTP 201 Created resposta ou HTTP 200 OK com os metadados driveItem para o ficheiro 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, não deve utilizar uma estratégia de recuo exponencial, mas limitar o número de tentativas de repetição efetuadas.
• 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