Fazer upload de mídia

O upload de itens de mídia é um processo de duas etapas:

1. Faça upload dos bytes dos seus arquivos de mídia para um servidor do Google usando o endpoint uploads. Isso retorna um token de upload que identifica os bytes enviados.
2. Use uma chamada batchCreate com o token de upload para criar um item de mídia na conta do Google Fotos do usuário.

Estas etapas descrevem o processo de upload de um único item de mídia. Se você estiver enviando vários itens de mídia (muito provável para qualquer aplicativo de produção), consulte as práticas recomendadas para uploads e melhore a eficiência do processo.

Antes de começar

Escopos de autorização obrigatórios

O upload de itens de mídia para a biblioteca ou o álbum de um usuário exige o escopo photoslibrary.appendonly. Para mais informações sobre escopos, consulte Escopos de autorização.

Tipos e tamanhos de arquivo aceitos

É possível fazer upload dos tipos de arquivo listados nesta tabela.

Etapa 1: fazer upload de bytes

Faça upload de bytes para o Google usando solicitações de upload. Uma solicitação de upload bem-sucedida retorna um token de upload na forma de uma string de texto bruto. Use esses tokens de upload para criar itens de mídia com a chamada batchCreate.

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

media-binary-data

upload-token

O tamanho sugerido para imagens é inferior a 50 MB. Arquivos com mais de 50 MB podem causar problemas de desempenho.

A API Google Photos Library oferece suporte a uploads retomáveis. Com um upload retomável, é possível dividir um arquivo de mídia em várias seções e fazer o upload de uma seção por vez.

Etapa 2: criar um item de mídia

Depois de fazer upload dos bytes dos seus arquivos de mídia, você pode criá-los como itens de mídia no Google Fotos usando tokens de upload. Um token de upload é válido por um dia após a criação. Um item de mídia é sempre adicionado à biblioteca do usuário. Os itens de mídia só podem ser adicionados a álbuns criados pelo seu app. Para mais informações, consulte Escopos de autorização.

Para criar novos itens de mídia, chame mediaItems.batchCreate especificando uma lista de newMediaItems. Cada newMediaItem contém um token de upload especificado em um simpleMediaItem e uma descrição opcional mostrada ao usuário.

O campo de descrição é restrito a 1.000 caracteres e só pode incluir texto significativo criado pelos usuários. Por exemplo, "Nossa viagem ao parque" ou "Jantar de fim de ano". Não inclua metadados, como nomes de arquivos, tags programáticas ou outros textos gerados automaticamente.

Para ter o melhor desempenho, reduza o número de chamadas para mediaItems.batchCreate que você precisa fazer incluindo vários itens de mídia em uma chamada. Sempre aguarde a conclusão da solicitação anterior antes de fazer uma chamada subsequente para o mesmo usuário.

É possível criar um ou vários itens de mídia na biblioteca de um usuário especificando as descrições e os tokens de upload correspondentes:

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

Você também pode especificar albumId e albumPosition para inserir itens de mídia em um local específico do álbum.

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

Para mais detalhes sobre o posicionamento em álbuns, consulte Adicionar enriquecimentos.

Resposta de criação de item

A chamada mediaItems.batchCreate retorna o resultado de cada um dos itens de mídia que você tentou criar. A lista de newMediaItemResults indica o status e inclui o uploadToken da solicitação. Um código de status diferente de zero indica um erro.

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

Se um item for adicionado, um mediaItem será retornado com o mediaItemId, productUrl e mediaMetadata dele. Para mais informações, consulte Acessar itens de mídia.

Se o item de mídia for um vídeo, ele precisará ser processado primeiro. O mediaItem contém um status dentro do mediaMetadata que descreve o estado de processamento do arquivo de vídeo. Um arquivo recém-enviado retorna o status PROCESSING primeiro, antes de ficar READY para uso. Para detalhes, consulte Acessar itens de mídia.

Se você encontrar um erro durante essa chamada, siga as Práticas recomendadas e tente fazer a solicitação novamente. Você pode querer acompanhar as adições bem-sucedidas para que a imagem seja inserida na posição correta do álbum durante a próxima solicitação. Para mais informações, consulte Criar álbuns.

Os resultados são sempre retornados na mesma ordem em que os tokens de upload foram enviados.

Práticas recomendadas para uploads

As práticas recomendadas e os recursos a seguir ajudam a melhorar sua eficiência geral com uploads:

• Siga as práticas recomendadas de novas tentativas e tratamento de erros, tendo em mente os seguintes pontos:
  • Os erros 429 podem ocorrer quando sua cota foi esgotada ou você recebeu uma limitação de taxa por fazer muitas chamadas muito rapidamente. Não chame batchCreate para o mesmo usuário até que a solicitação anterior seja concluída.
  • Os erros 429 exigem um atraso mínimo de 30s antes de uma nova tentativa. Use uma estratégia de espera exponencial ao repetir solicitações.
  • Os erros 500 ocorrem quando o servidor encontra um erro. Ao fazer upload, isso provavelmente acontece porque várias chamadas de gravação (como batchCreate) foram feitas para o mesmo usuário ao mesmo tempo. Confira os detalhes da sua solicitação e não faça chamadas para batchCreate em paralelo.
• Use o fluxo de upload retomável para tornar seus uploads mais robustos em caso de interrupções na rede, reduzindo o uso da largura de banda ao permitir que você retome uploads parcialmente concluídos. Isso é importante ao fazer upload de dispositivos móveis do cliente ou de arquivos grandes.

Além disso, considere as dicas a seguir para cada etapa do processo de upload: upload de bytes e criação de itens de mídia.

Bytes de upload

• O upload de bytes (para recuperar tokens de upload) pode ser feito em paralelo.
• Sempre defina o tipo MIME correto no cabeçalho X-Goog-Upload-Content-Type para cada chamada de upload.

Criar itens de mídia

• Não faça chamadas em paralelo para batchCreate de um único usuário.

  • Para cada usuário, faça chamadas para batchCreate uma após a outra (em série).
  • Para vários usuários, sempre faça chamadas batchCreate para cada um deles, uma após a outra. Faça chamadas apenas para usuários diferentes em paralelo.

• Inclua o máximo possível de NewMediaItems em cada chamada para batchCreate e minimize o número total de chamadas que você precisa fazer. É possível incluir no máximo 50 itens.

• Defina um texto de descrição significativo criado pelos usuários. Não inclua metadados, como nomes de arquivos, tags programáticas ou outros textos gerados automaticamente no campo de descrição.

Exemplo de tutorial

Este exemplo usa pseudocódigo para mostrar como fazer upload de itens de mídia para vários usuários. O objetivo é descrever as duas etapas do processo de upload (upload de bytes brutos e criação de itens de mídia) e detalhar as práticas recomendadas para criar uma integração de upload eficiente e resiliente.

Etapa 1: fazer upload de bytes brutos

Primeiro, crie uma fila para fazer upload dos bytes brutos dos itens de mídia de todos os seus usuários. Rastreie cada uploadToken retornado por usuário. Lembre-se destes pontos principais:

• O número de linhas de execução de upload simultâneas depende do seu ambiente operacional.
• Reordene a fila de upload conforme necessário. Por exemplo, é possível priorizar uploads com base no número de uploads restantes por usuário, no progresso geral de um usuário ou em outros requisitos.

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

Etapa 2: criar itens de mídia

Na etapa 1, é possível fazer upload de vários bytes de vários usuários em paralelo, mas na etapa 2, só é possível fazer uma única chamada por usuário de cada vez.

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

Continue esse processo até que todos os uploads e chamadas de criação de mídia sejam concluídos.