Acessar itens de mídia

Depois de fazer chamadas para listar o conteúdo de uma biblioteca de fotos ou um álbum, em vez de armazenar os itens de mídia retornados, o aplicativo deve armazenar os IDs dos itens de mídia. Isso ocorre porque o conteúdo dos itens de mídia pode mudar e, depois de um determinado tempo, os URLs incluídos na resposta expiram. O ID de item de mídia identifica exclusivamente um item de mídia, como uma foto ou um vídeo na biblioteca de um usuário.

Observe que seu aplicativo não deve armazenar em cache a foto ou o vídeo de um usuário por muito tempo específicos, mas, dependendo do caso de uso, você pode armazenar ou armazenar em cache o ID do item de mídia longo como necessários. Observe também que o acesso a ferramentas de dados são regidos pelos requisitos de privacidade obrigações de privacidade de dados.

Escopos de autorização necessários

Para acessar itens de mídia, o app precisa solicitar pelo menos um dos seguintes escopos de autorização. O acesso aos itens de mídia retornados na resposta depende dos escopos solicitaram.

  • photoslibrary.readonly permite o acesso a todos os itens de mídia da conta do usuário biblioteca
  • photoslibrary.readonly.appcreateddata permite o acesso somente a itens de mídia que foram criadas pelo app

Itens de mídia

Um mediaItem é uma representação de mídia, como uma foto ou um vídeo, que foi enviado ao a biblioteca do Google Fotos. É um objeto de nível superior e suas propriedades podem diferem com base no tipo de mídia.

A tabela abaixo lista as propriedades de mediaItem:

Propriedades
id Um ID permanente e estável usado para identificar o objeto.
description Descrição do item de mídia exibido na parte interna Google Fotos
baseUrl Usado para acessar os bytes brutos. Para mais informações, consulte URLs base.
productUrl

Um link para a imagem no Google Fotos. Este link não pode ser aberto pelo desenvolvedor, apenas pelo usuário. Os URLs apontam para um item de mídia da biblioteca. Se o URL foi recuperado de uma pesquisa de álbum, ele aponta para o item no álbum.

mimeType O tipo do item de mídia para ajudar a identificar facilmente o tipo de mídia Por exemplo: image/jpg.
filename O nome do arquivo do item de mídia mostrado ao usuário no Google Fotos (na seção de informações do item).
mediaMetadata Varia de acordo com o tipo de mídia, como photo ou video. Para reduzir o payload, é possível usar máscaras de campo.
contributorInfo

Esse campo só é preenchido se o item de mídia está em um álbum compartilhado. criado por este app, e o usuário deu a permissão escopo photoslibrary.sharing.

Contém informações sobre o colaborador que adicionou a mídia do item de linha. Para mais detalhes, consulte Compartilhar mídia.

Receber um item de mídia

Para recuperar um item de mídia, chame mediaItems.get usando o mediaItemId A solicitação retorna um único item de mídia.

O mediaItem contém propriedades, como ID, descrição e URL. O informações adicionais em photo ou video são baseadas nos metadados em o arquivo. É possível que nem todas as propriedades estejam presentes. ContributorInfo contém metadados. para itens que fazem parte de um álbum compartilhado. Esse campo só é incluído quando listar o conteúdo de um álbum compartilhado em que o usuário concedeu a permissão photoslibrary.sharing escopo da autorização.

Se o item de mídia for um vídeo, o arquivo de vídeo terá que ser processado primeiro. O mediaItem contém um campo status dentro de mediaMetadata que descreve a estado de processamento do arquivo de vídeo. Um arquivo recém-enviado retorna o videoProcessingStatus com o valor PROCESSING primeiro, antes de ser READY para uso. O baseUrl de um item de mídia em vídeo não estará disponível até que o vídeo tenha sido processado.

REST

Aqui está uma solicitação GET:

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

A resposta para um item de mídia de foto é assim. A foto contém metadados para itens de foto.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "photo": {
       "cameraMake": "make-of-the-camera",
       "cameraModel": "model-of-the-camera",
       "focalLength": "focal-length-of-the-camera-lens",
       "apertureFNumber": "aperture-f-number-of-the-camera-lens",
       "isoEquivalent": "iso-of-the-camera",
       "exposureTime": "exposure-time-of-the-camera-aperture"
    }
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

A resposta para um item de mídia de vídeo é assim. O vídeo contém metadados de itens de vídeo.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "video": {
     "cameraMake": "make-of-the-camera",
     "cameraModel": "model-of-the-camera",
     "fps": "frame-rate-of-the-video",
     "status": "READY"
    },
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

Java

A propriedade foto contém metadados para itens de foto.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...
    if (metadata.hasPhoto()) {
      // This media item is a photo and has additional photo metadata
      Photo photoMetadata = metadata.getPhoto();
      String cameraMake = photoMetadata.getCameraMake();
      String cameraModel = photoMetadata.getCameraModel();
      float aperture = photoMetadata.getApertureFNumber();
      int isoEquivalent = photoMetadata.getIsoEquivalent();
      // ...
    }
  }
  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

A propriedade de vídeo contém metadados para itens de vídeo.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...

    if (metadata.hasVideo()) {
      // This media item is a video and has additional video metadata
      Video videoMetadata = metadata.getVideo();
      VideoProcessingStatus status = videoMetadata.getStatus();
      if (status.equals(VideoProcessingStatus.READY)) {
        // This video media item has been processed
        String cameraMake = videoMetadata.getCameraMake();
        String cameraModel = videoMetadata.getCameraModel();
        double fps = videoMetadata.getFps();
        // ...
      }
    }
  }

  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

A propriedade foto contém metadados para itens de foto.

try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $photoMetadata = $metadata->getPhoto();
        if (!is_null($photoMetadata)) {
            // This media item is a photo and has additional photo metadata
            $cameraMake = $photoMetadata->getCameraMake();
            $cameraModel = $photoMetadata->getCameraModel();
            $aperture = $photoMetadata->getApertureFNumber();
            $isoEquivalent = $photoMetadata->getIsoEquivalent();
            // ...
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

A propriedade de vídeo contém metadados para itens de vídeo.

  try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $videoMetadata = $metadata->getVideo();
        if (!is_null($videoMetadata)) {
            // This media item is a video and has additional video metadata
            if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
            // This video media item has been processed
                $cameraMake = $videoMetadata->getCameraMake();
                $cameraModel = $videoMetadata->getCameraModel();
                $fps = $videoMetadata->getFps();
                // ...
            }
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Receber vários itens de mídia

Para recuperar vários itens de mídia pelos identificadores, chame mediaItems.batchGet usando as mediaItemIds.

A solicitação retorna uma lista de MediaItemResults na ordem dos identificadores de itens de mídia fornecidos na solicitação. Cada resultado contém um MediaItem. ou um Status se houver um erro.

O número máximo de itens de mídia que você pode solicitar em uma chamada é 50. A lista de os itens de mídia não podem conter identificadores duplicados nem podem ficar em branco.

REST

Aqui está uma solicitação GET que mostra o acesso bem-sucedido e malsucedido de itens de mídia. Especifique cada identificador de item de mídia como um novo o parâmetro de consulta mediaItemIds como parte da solicitação:

GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

A solicitação GET retorna a seguinte resposta:

{
  "mediaItemResults": [
    {
      "mediaItem": {
        "id": "media-item-id",
        ...
      }
    },
    {
      "mediaItem": {
        "id": "another-media-item-id",
        ...
      }
    },
    {
      "status": {
        "code": 3,
        "message": "Invalid media item ID."
      }
    }
  ]
}

Java

try {
  // List of media item IDs to retrieve
  List<String> mediaItemIds = Arrays
      .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");

  // Get a list of media items using their IDs
  BatchGetMediaItemsResponse response = photosLibraryClient
      .batchGetMediaItems(mediaItemIds);

  // Loop over each result
  for (MediaItemResult result : response.getMediaItemResultsList()) {

    // Each MediaItemresult contains a status and a media item
    if (result.hasMediaItem()) {
      // The media item was successfully retrieved, get some properties
      MediaItem item = result.getMediaItem();
      String id = item.getId();
      // ...
    } else {
      // If the media item is not set, an error occurred and the item could not be loaded
      // Check the status and handle the error
      Status status = result.getStatus();
      // ...
    }

  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {

    // List of media item IDs to retrieve
    $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];

    // Get a list of media items using their IDs
    $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);

    // Loop over each result
    foreach ($response->getMediaItemResults() as $itemResult) {

        // Each MediaItemresult contains a status and a media item
        $mediaItem = $itemResult->getMediaItem();

        if(!is_null($mediaItem)){
            // The media item was successfully retrieved, get some properties
            $id = $mediaItem->getId();
            // ...
        } else {
            // If the media item is null, an error occurred and the item could not be loaded
        }
    }

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

URLs base

Os URLs de base na API Google Photos Library permitem que você acesse os bytes da mídia itens. Usando os diversos URLs base, o app pode fazer o download dos itens de mídia ou exibir os itens de mídia dentro do app. Os URLs base são strings incluído na resposta quando você lista álbuns ou acessa itens de mídia. São são válidos por 60 minutos e exigem parâmetros adicionais, já que não podem ser usados como o endereço IP interno.

Os vários URLs base são:

  • baseUrl: acessa diretamente a foto, a miniatura de um vídeo ou faz o download de bytes de vídeo.
  • coverPhotoBaseUrl: acessar diretamente a foto da capa do álbum.
  • profilePictureBaseUrl: acessa diretamente a foto de perfil do proprietário de um mediaItem.

URLs de base de imagem

Esta é a lista de opções que podem ser usadas com os URLs de base de imagem:

Parâmetro
w, h

Descrição

A largura, w e a altura, h. parâmetros.

Para acessar um item de mídia de imagem, como uma foto ou uma miniatura, um vídeo, é necessário especificar as dimensões que você planeja exibir em do aplicativo (para que a imagem possa ser dimensionada e manter a proporção). Para isso, concatenar o URL base com as dimensões necessárias, como mostrado em os exemplos.

Exemplos:

base-url=wmax-width-hmax-height

Este é um exemplo para exibir um item de mídia com largura menor que 2.048 px e não mais que 1.024 px:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

Descrição

O corte, parâmetro c.

Se você quiser cortar a imagem na largura e altura exatas especificadas, concatene o URL base com o parâmetro -c opcional, além do parâmetro obrigatório Parâmetros w e h.

O tamanho (em pixels) deve estar no intervalo [1, 16383]. Se a largura ou a altura da imagem, exceder o tamanho solicitado, o é reduzida e cortada (mantendo a proporção).

Exemplos:

base-url=wmax-width-hmax-height-c

Neste exemplo, o aplicativo exibe um item de mídia que é exatamente 256 px de largura por 256 px de altura, como miniatura:

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

Descrição

O download, parâmetro d.

Se você quiser fazer o download da imagem que retém todos os metadados Exif exceto os metadados de local, concatene o URL de base com o parâmetro d.

Exemplos:

base-url=d

Neste exemplo, o aplicativo faz o download de uma imagem com todos exceto os metadados de local:

https://lh3.googleusercontent.com/p/Az....XabC=d

URLs de base de vídeo

Esta é a lista de opções que você pode usar com os URLs de base de vídeo:

Parâmetro
dv

Descrição

Para acessar os bytes de um vídeo mediaItem, concatene a baseUrl com o vídeo salvo dv .

O parâmetro dv solicita uma alta qualidade, versão transcodificada do vídeo original. O parâmetro não é compatível com w e h parâmetros.

Os URLs de base para downloads de vídeo podem levar alguns segundos para retornam bytes. Os downloads de vídeo usam a codificação H.264 por padrão. Se a codificação H.264 falhar, o VP9 será usado.

Antes de usar esse parâmetro, verifique se o valor O campo mediaMetadata.status é READY. Caso contrário, se o item de mídia não tiver sido concluído o processamento, você receberá uma erro.

Exemplos:

base-url=dv

O exemplo a seguir mostra como fazer o download dos bytes de um vídeo:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c e d

Descrição

Para acessar a miniatura do vídeo, use um dos parâmetros de URL base da imagem.

Por padrão, todas as miniaturas de vídeo incluem uma sobreposição de um vídeo . Consulte o parâmetro -no para remover essa sobreposição.

Exemplos:

Consulte a tabela de URLs base de imagem. para ver exemplos.
no

Descrição

O parâmetro no para remover a sobreposição de miniatura.

Se você quiser recuperar a miniatura de um vídeo sem a sobreposição de um botão de reprodução, concatene o URL base com o sinal no .

O parâmetro no precisa ser usado com pelo menos um dos as parâmetros de URL de base da imagem.

Exemplos:

base-url=wmax-width-hmax-height-no

O exemplo a seguir exibe uma miniatura de vídeo com exatamente 1280 px de largura por 720 px de altura e não inclui uma sobreposição do botão de reprodução:

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URLs de base das fotos em movimento

As fotos com movimento contêm elementos de foto e vídeo. É possível usar parâmetros de URLs de base de imagem ou URLs de base de vídeo para solicitações de foto com movimento baseUrl.

Parâmetro
dv

Descrição

Para recuperar o elemento de vídeo de um item de mídia de foto com movimento, use o parâmetro dv da mesma forma que você faria para fazer o download dos URLs de vídeo de base.
w, h, c e d

Descrição

Para recuperar o elemento de foto de um item de mídia de foto com movimento, use o formato dos URLs de base de imagem.