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 de 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 fazendo upload de vários itens de mídia (provavelmente para qualquer aplicativo de produção), revise as práticas recomendadas para uploads para melhorar a eficiência do envio.

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 requer o escopo photoslibrary.appendonly ou photoslibrary.

Também é possível criar itens de mídia usando o escopo photoslibrary.sharing. Para criar itens com o escopo photoslibrary.sharing, você precisa primeiro criar um álbum e marcá-lo como compartilhado usando shareAlbum. Depois, você pode criar itens de mídia para serem compartilhados com o usuário no álbum. Não é possível criar itens diretamente na biblioteca do usuário ou em álbuns que seu app não compartilhou.

Ao listar álbuns, a propriedade isWriteable indica se seu app tem acesso para criar mídia em um álbum específico.

Tipos e tamanhos de arquivo aceitos

Você pode fazer upload dos tipos de arquivo listados na tabela abaixo.

Tipo de mídia Tipos de arquivos aceitos Tamanho máximo do arquivo
Fotos AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP e alguns arquivos RAW. 200 MB
Vídeos 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. 20 GB

Etapa 1: fazer upload de bytes

Fazer upload de bytes para o Google com 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 de batchCreate.

REST

Inclua os seguintes campos no cabeçalho da solicitação POST:

Campos de cabeçalho
Content-type Defina como application/octet-stream.
X-Goog-Upload-Content-Type Recomendada. Defina o tipo MIME dos bytes que você está enviando. Os tipos MIME comuns incluem image/jpeg, image/png e image/gif.
X-Goog-Upload-Protocol Defina como raw.

Este é um cabeçalho de solicitação POST:

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

No corpo da solicitação, inclua o binário do arquivo: 

media-binary-data

Se essa solicitação POST for bem-sucedida, um token de upload, que está na forma de uma string de texto bruta, será retornado como o corpo da resposta. Para criar itens de mídia, use essas strings de texto na chamada de batchCreate.

upload-token

Java

// Open the file and automatically close it after upload
try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) {
  // Create a new upload request
  UploadMediaItemRequest uploadRequest =
      UploadMediaItemRequest.newBuilder()
              // The media type (e.g. "image/png")
              .setMimeType(mimeType)
              // The file to upload
              .setDataFile(file)
          .build();
  // Upload and capture the response
  UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest);
  if (uploadResponse.getError().isPresent()) {
    // If the upload results in an error, handle it
    Error error = uploadResponse.getError().get();
  } else {
    // If the upload is successful, get the uploadToken
    String uploadToken = uploadResponse.getUploadToken().get();
    // Use this upload token to create a media item
  }
} catch (ApiException e) {
  // Handle error
} catch (IOException e) {
  // Error accessing the local file
}

PHP

try {
    // Create a new upload request by opening the file
    // and specifying the media type (e.g. "image/png")
    $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType);
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // Handle error
}

O tamanho do arquivo sugerido para imagens é menor que 50 MB. Arquivos com mais de 50 MB estão propensos a apresentar problemas de desempenho.

A API Google Photos Library é compatível com uploads retomáveis. Um upload retomável permite dividir um arquivo de mídia em várias seções e fazer 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ê poderá 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 app. Para saber mais, 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 dentro de um simpleMediaItem e uma descrição opcional que é exibida ao usuário.

O campo de descrição é restrito a mil caracteres e só pode incluir textos significativos criados pelos usuários. Por exemplo, "Nossa viagem ao parque" ou "Jantar de férias". 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 necessárias 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:

REST

Este é o cabeçalho da solicitação POST:

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

O corpo da solicitação precisa especificar uma lista de newMediaItems.

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

Java

try {
  // Create a NewMediaItem with the following components:
  // - uploadToken obtained from the previous upload request
  // - filename that will be shown to the user in Google Photos
  // - description that will be shown to the user in Google Photos
  NewMediaItem newMediaItem = NewMediaItemFactory
          .createNewMediaItem(uploadToken, fileName, itemDescription);
  List<NewMediaItem> newItems = Arrays.asList(newMediaItem);

  BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);
  for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) {
    Status status = itemsResponse.getStatus();
    if (status.getCode() == Code.OK_VALUE) {
      // The item is successfully created in the user's library
      MediaItem createdItem = itemsResponse.getMediaItem();
    } else {
      // The item could not be created. Check the status and try again
    }
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $newMediaItems = [];
    // Create a NewMediaItem with the following components:
    // - uploadToken obtained from the previous upload request
    // - filename that will be shown to the user in Google Photos
    // - description that will be shown to the user in Google Photos
    $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName(
            $uploadToken, $itemDescription, $fileName);

    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems);
    foreach ($response->getNewMediaItemResults() as $itemResult) {
        $status = $itemResult->getStatus();
        if ($status->getCode() != Code::OK) {
            // Error while creating the item.
        }
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Para adicionar itens de mídia à biblioteca e a um álbum, especifique o álbum id. Para saber mais, consulte Criar álbuns.

Cada álbum pode conter até 20 mil itens de mídia. As solicitações para criar itens de mídia em um álbum que excedam esse limite falharão.

REST

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

Java

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

REST

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

Java

try {
  // Create new media items in a specific album, positioned after a media item
  AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum();
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems, positionInAlbum);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems,
        ['albumId' => $albumId, 'albumPosition' => $albumPosition]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

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

Resposta sobre a criação do item

A chamada mediaItems.batchCreate retorna o resultado para 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.

REST

Se todos os itens de mídia tiverem sido criados, a solicitação retornará o status HTTP 200 OK. Se não for possível criar alguns itens de mídia, a solicitação retornará o status HTTP 207 MULTI-STATUS para indicar sucesso parcial.

{
  "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"
      }
    }
  ]
}

Java

BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);

// The response contains a list of NewMediaItemResults
for (NewMediaItemResult result : response.getNewMediaItemResultsList()) {
  // Each result item is identified by its uploadToken
  String uploadToken = result.getUploadToken();
  Status status = result.getStatus();

  if (status.getCode() == Code.OK_VALUE) {
    // If the request is successful, a MediaItem is returned
    MediaItem mediaItem = result.getMediaItem();
    String id = mediaItem.getId();
    String productUrl = mediaItem.getProductUrl();
    // ...
  }
}

PHP

// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults
foreach ($response->getNewMediaItemResults() as $itemResult) {
    // Each result item is identified by its uploadToken
    $itemUploadToken = $itemResult->getUploadToken();
    // Verify the status of each entry to ensure that the item has been uploaded correctly
    $itemStatus = $itemResult->getStatus();
    if ($itemStatus->getCode() != Code::OK) {
        // Error when item is being created
    } else {
        // Media item is successfully created
        // Get the MediaItem object from the response
        $mediaItem = $itemResult->getMediaItem();
        // It contains details such as the Id of the item, productUrl
        $id = $mediaItem->getId();
        $productUrl = $mediaItem->getProductUrl();
        // ...
    }
}

Se um item for adicionado, será retornado um mediaItem contendo mediaItemId, productUrl e mediaMetadata. 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 READY para uso. Para mais detalhes, consulte Acessar itens de mídia.

Se você encontrar um erro durante a chamada, siga as práticas recomendadas e tente fazer a solicitação novamente. Você pode acompanhar as adições bem-sucedidas para que a imagem possa ser inserida no álbum na posição correta 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 envios

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

  • Usar uma das nossas bibliotecas de cliente compatíveis.
  • Siga as práticas recomendadas de nova tentativa e tratamento de erros, mantendo os seguintes pontos em mente:
    • Erros 429 podem ocorrer quando sua cota está esgotada ou quando você tem 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.
    • Erros 429 exigem um atraso mínimo de 30s antes de tentar novamente. Use uma estratégia de espera exponencial ao repetir solicitações.
    • Os erros 500 ocorrem quando o servidor encontra um erro. Durante o upload, isso ocorre provavelmente devido a várias chamadas de gravação (como batchCreate) para o mesmo usuário ao mesmo tempo. Verifique os detalhes da 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 de rede, reduzindo o uso da largura de banda ao permitir que você retome uploads parcialmente concluídos. Isso é importante ao fazer o upload de dispositivos móveis clientes ou de arquivos grandes.

Além disso, considere estas dicas para cada etapa do processo de upload: fazer upload de bytes e criar itens de mídia.

Upload de bytes

  • 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 a batchCreate para um único usuário.

    • Para cada usuário, faça chamadas para batchCreate uma após a outra (em série).
    • No caso de vários usuários, sempre faça chamadas batchCreate para cada usuário uma após a outra. Só faça chamadas para usuários diferentes em paralelo.

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

  • Defina um texto de descrição significativo que tenha sido criado pelos seus 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 um pseudocódigo para orientar o 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 usuários. Rastreie cada uploadToken retornado por usuário. Lembre-se destes pontos-chave:

  • O número de linhas de execução de upload simultâneo depende do ambiente operacional.
  • Considere reordenar 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.

Pseudocódigo

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 para cada usuário de cada vez.

Pseudocódigo

// 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.