Uploads recuperáveis

Esta página descreve como fazer uma solicitação de upload retomável para a API Google Photos Library pelo protocolo REST. Esse protocolo permite retomar uma operação de upload após uma falha de comunicação interrompe o fluxo de dados.

Se você é um desenvolvedor que usa bibliotecas de cliente, observe que algumas delas fornecem suporte nativo para uploads retomáveis.

Use a opção de upload retomável se:

  • Você está fazendo upload de arquivos grandes.
  • A probabilidade de interrupção da rede ou alguma outra falha de transmissão é alta (por exemplo, se você estiver enviando um arquivo de um aplicativo móvel).

Os uploads retomáveis também podem reduzir o uso de largura de banda quando há uma rede porque não é preciso reiniciar os uploads de arquivos grandes na desde o início.

Etapa 1: iniciar uma sessão de upload

Iniciar uma sessão de upload retomável enviando uma solicitação POST para https://photoslibrary.googleapis.com/v1/uploads: Como usar o upload retomável URL retornado nessa solicitação, faça o upload do arquivo.

A solicitação POST deve incluir os seguintes cabeçalhos:

Campos de cabeçalho
Content-Length Defina como 0 porque o corpo da solicitação está vazio.
X-Goog-Upload-Command Defina como start.
X-Goog-Upload-Content-Type Defina como o tipo MIME do arquivo, por exemplo, image/jpeg:
X-Goog-Upload-Protocol Defina como resumable.
X-Goog-Upload-Raw-Size Defina como o número total de bytes dos dados do arquivo a ser transferidos.

Aqui está um cabeçalho de solicitação POST:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: bytes-of-file

Etapa 2: salvar o URL da sessão

Se for bem-sucedida, a solicitação POST retornará um código de status HTTP 200 OK, incluindo no cabeçalho a seguir.

X-Goog-Upload-URL: url-to-make-uploads-to
X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes

O campo de cabeçalho x-goog-upload-chunk-granularity contém o alinhamento de bytes. e a granularidade do tamanho de todos os blocos de dados enviados pelo cliente. Se o upload for feito em vários blocos, todos os uploads, exceto o último; deve ser feito em múltiplos desse valor. Ou seja, os bytes de upload do arquivo precisa estar alinhada ao valor. Na última parte, é possível fazer upload dos arquivos bytes.

O campo de cabeçalho X-Goog-Upload-URL contém um URL exclusivo que deve ser usado para conclua o upload com todas as solicitações restantes. Copie e salve URL de sessão retomável para que seja possível usá-lo nas solicitações subsequentes.

Etapa 3: fazer upload do arquivo

Há duas formas de fazer o upload de um arquivo com uma sessão retomável:

  1. Em uma única solicitação: Essa abordagem geralmente é a melhor, porque requer menos solicitações e, portanto, tem melhor desempenho.

  2. Em várias partes: Nessa abordagem, os uploads são feitos em várias solicitações ao dividir os dados. Os dados são divididos múltiplos de x-goog-upload-chunk-granularity. Se necessário, as solicitações em partes podem ser repetidas.

    use esta abordagem nos casos a seguir:

    • Você precisa reduzir a quantidade de dados transferidos em cada solicitação. Você poderá precisar fazer isso quando houver um limite de tempo fixo para solicitações individuais.
    • Você precisa fornecer um indicador personalizado mostrando o upload o progresso.
    • Você precisa saber quando é seguro descartar dados.

Solicitação única

Para fazer upload do arquivo em uma única solicitação, faça o seguinte:

  1. Crie uma solicitação POST para o URL da sessão retomável.
  2. Adicione os dados do arquivo ao corpo da solicitação.

  3. Adicione os cabeçalhos HTTP a seguir:

    • Content-Length: defina como o número de bytes no .
    • Defina X-Goog-Upload-Command como upload, finalize.

  4. Envie a solicitação.

Se a solicitação de upload for interrompida ou você receber uma 5xx resposta, siga o procedimento em Como retomar uma upload interrompido.

Se a solicitação for bem-sucedida, você receberá um status HTTP 200 OK e um token de upload no corpo da resposta. Criar o item de mídia usando esse token de upload.

Vários pedaços

Para fazer upload do arquivo em várias partes, faça o seguinte:

  1. Crie uma solicitação POST para o URL da sessão retomável.

  2. Adicione os dados de cada parte ao corpo da solicitação.

    Exceto pela parte final que conclui o upload, crie a outros pedaços em múltiplos do tamanho aceito de partes. Mantenha o o maior tamanho possível, para que o upload seja eficiente.

  3. Adicione os cabeçalhos HTTP a seguir:

    • Content-Length: defina como o número de bytes no bloco.
    • Defina X-Goog-Upload-Command como upload. Para a última parte, defina como upload, finalize.
    • X-Goog-Upload-Offset: defina o deslocamento em que o bytes serão gravados. É preciso fazer o upload dos bytes em série. O primeiro deslocamento é 0.
  4. Envie a solicitação.

    Se a solicitação de upload for interrompida ou você receber uma 5xx resposta, siga o procedimento em Como retomar uma upload interrompido.

  5. Repita as etapas acima para cada parte restante do arquivo.

Se a solicitação for bem-sucedida, você receberá um status HTTP 200 OK e um token de upload no corpo da resposta. Criar o item de mídia usando esse token de upload.

Exemplo

Solicitação única

O exemplo a seguir mostra uma solicitação retomável para fazer upload de um Arquivo JPEG de 3.039.417 bytes em uma única solicitação.

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

A resposta contém o URL de upload e o tamanho do bloco esperado:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

A última solicitação de upload:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 3039417
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Vários pedaços

O exemplo a seguir mostra uma solicitação retomável para fazer upload de um Arquivo JPEG de 3.039.417 bytes em vários fragmentos, usando a sessão retomável o URL e a granularidade do tamanho do fragmento aceito obtida na etapa anterior. Este exemplo usa um bloco de 262.144 bytes que foi retornado no campo de cabeçalho, x-goog-upload-chunk-granularity, quando de upload foi inicializada. Cada upload contém bytes que estão em múltiplos de 262.144.

Inicializar a sessão de upload para receber o URL de upload e o tamanho do fragmento conforme descrito na etapa anterior:

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

A resposta contém o URL de upload e o tamanho do bloco esperado:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

Primeira parte:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0

[BYTES 0-1048575]

Segundo bloco:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 1048576

[BYTES 1048576-2097151]

Último bloco:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 942265
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 2097152

[BYTES 2097152-4200000]

Como retomar um upload interrompido

Se a solicitação de upload for interrompida ou você receber um status HTTP diferente de 200 consulta o servidor para saber quanto do upload foi bem-sucedido.

Aqui está uma solicitação POST para o URL de sessão retomável. X-Goog-Upload-Command precisa ser definido como query.

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: query

A resposta do servidor inclui um código de status HTTP 200 OK e o tamanho atual do upload.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

Você pode retomar o upload nesse deslocamento. Você deve retomar no deslocamento fornecida pelo servidor, a menos que você envie um comando combinado de upload e finalização, Nesse caso, você também pode retomar no deslocamento 0.

Se o cabeçalho X-Goog-Upload-Status na resposta HTTP do comando de consulta estiver presente e o valor não for active, isso indica que o upload foi já tiver sido encerrado.