Method: mediaItems.search

Pesquisa itens de mídia na biblioteca do Google Fotos de um usuário. Se nenhum filtro for definido, todos os itens de mídia na biblioteca do usuário serão retornados. Se um álbum for definido, todos os itens de mídia desse álbum serão retornados. Se os filtros forem especificados, os itens de mídia que corresponderem aos filtros da biblioteca do usuário serão listados. Se você definir o álbum e os filtros, a solicitação resultará em um erro.

Solicitação HTTP

POST https://photoslibrary.googleapis.com/v1/mediaItems:search

O URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "albumId": string,
  "pageSize": integer,
  "pageToken": string,
  "filters": {
    object (Filters)
  },
  "orderBy": string
}
Campos
albumId

string

Identificador de um álbum. Se preenchido, lista todos os itens de mídia no álbum especificado. Não é possível definir juntamente com filtros.
pageSize

integer

Número máximo de itens de mídia a serem retornados na resposta. Podem ser retornados menos itens de mídia do que o número especificado. O pageSize padrão é 25, o máximo é 100.
pageToken

string

Um token de continuação para ter acesso à próxima página de resultados. Adicionar isso à solicitação retorna as linhas após pageToken. O pageToken precisa ser o valor retornado no parâmetro nextPageToken na resposta à solicitação searchMediaItems.
filters

object (Filters)

Filtros a serem aplicados à solicitação. Não pode ser definido com uma albumId.
orderBy

string

Um campo opcional para especificar a ordem de classificação dos resultados da pesquisa. O campo orderBy só funciona quando um dateFilter é usado. Quando esse campo não é especificado, os resultados são exibidos mais recentes primeiro, os mais antigos por último, com a creationTime. Fornecer MediaMetadata.creation_time mostra os resultados da pesquisa na ordem oposta, com os mais antigos primeiro e os mais recentes por último. Para mostrar os resultados mais recentes primeiro e os mais antigos depois, inclua o argumento desc da seguinte maneira: MediaMetadata.creation_time desc.

Os únicos filtros adicionais que podem ser usados com esse parâmetro são includeArchivedMedia e excludeNonAppCreatedData. Não há suporte para outros filtros.

Corpo da resposta

Lista de itens de mídia que correspondem aos parâmetros de pesquisa.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "mediaItems": [
    {
      object (MediaItem)
    }
  ],
  "nextPageToken": string
}
Campos
mediaItems[]

object (MediaItem)

Apenas saída. Lista de itens de mídia que correspondem aos parâmetros de pesquisa.
nextPageToken

string

Apenas saída. Use esse token para receber o próximo conjunto de itens de mídia. Sua presença é o único indicador confiável de que mais itens de mídia estarão disponíveis na próxima solicitação.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/photoslibrary
  • https://www.googleapis.com/auth/photoslibrary.readonly
  • https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata
  • https://www.googleapis.com/auth/photoslibrary.readonly.originals

Filtros

Filtros que podem ser aplicados a uma pesquisa de item de mídia. Se várias opções de filtro forem especificadas, elas serão tratadas como "E".

Representação JSON 
{
  "dateFilter": {
    object (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
Campos
dateFilter

object (DateFilter)

Filtra os itens de mídia com base na data de criação.
contentFilter

object (ContentFilter)

Filtra os itens de mídia com base no conteúdo.
mediaTypeFilter

object (MediaTypeFilter)

Filtra os itens de mídia com base no tipo de mídia.
featureFilter

object (FeatureFilter)

Filtra os itens de mídia com base nos recursos.
includeArchivedMedia

boolean

Se definida, os resultados incluirão itens de mídia arquivados pelo usuário. O padrão é "false". Os itens de mídia arquivados não são incluídos.
excludeNonAppCreatedData

boolean

Se definido, os resultados excluem os itens de mídia que não foram criados por esse app. O padrão é "false" (todos os itens de mídia são retornados). Esse campo será ignorado se o escopo photoslibrary.readonly.appcreateddata for usado.

DateFilter

Esse filtro define as datas ou os períodos permitidos para a mídia retornada. É possível escolher um conjunto de datas específicas e um conjunto de períodos. Os itens de mídia enviados sem metadados que especificam a data em que o item de mídia foi capturado não são retornados em consultas que usam filtros de data. O tempo de upload do servidor do Google Fotos não é usado como substituto nesse caso.

Representação JSON 
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
Campos
dates[]

object (Date)

Lista de datas que correspondem aos itens de mídia data de criação. É possível incluir até cinco datas por solicitação.
ranges[]

object (DateRange)

Lista de períodos que correspondem aos itens de mídia data de criação. É possível incluir no máximo cinco períodos por solicitação.

Data

Representa uma data inteira do calendário. Defina day como 0 quando apenas o mês e o ano forem importantes, por exemplo, todo o período de dezembro de 2018. Defina day e month como 0 se apenas o ano for importante, por exemplo, todo o ano de 2018. Defina year como 0 quando apenas o dia e o mês forem importantes, por exemplo, uma data comemorativa ou um aniversário.

Não compatível: definir todos os valores como 0, somente month como 0 ou day e year como 0 ao mesmo tempo.

Representação JSON 
{
  "year": integer,
  "month": integer,
  "day": integer
}
Campos
year

integer

Ano da data. Precisa ser de 1 a 9.999 ou 0 para especificar uma data sem ano.
month

integer

Mês do ano. Precisa ser de 1 a 12, ou 0 para especificar um ano sem um mês e dia.
day

integer

Dia do mês. Precisa ser de 1 a 31 e válido para o ano e o mês, ou 0 se especificar um ano/mês em que o dia não é relevante.

DateRange

Define um período. As duas datas precisam estar no mesmo formato. Para mais informações, consulte Date.

Representação JSON 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Campos
startDate

object (Date)

A data de início (incluída como parte do período) em um dos formatos descritos.
endDate

object (Date)

A data de término (incluída como parte do período). Ela precisa ser especificada no mesmo formato da data de início.

ContentFilter

Esse filtro permite retornar itens de mídia com base no tipo de conteúdo.

É possível especificar uma lista de categorias a serem incluídas e/ou uma lista de categorias a serem excluídas. Em cada lista, as categorias são combinadas com um OU.

O filtro de conteúdo includedContentCategories: [c1, c2, c3] vai receber itens de mídia que contêm (c1 OU c2 OU c3).

O filtro de conteúdo excludedContentCategories: [c1, c2, c3] NÃO receberia itens de mídia que contenham (c1 OR c2 OR c3).

Você também pode incluir algumas categorias e excluir outras, como neste exemplo: includedContentCategories: [c1, c2], excludedContentCategories: [c3, c4]

O exemplo anterior obteria itens de mídia que contêm (c1 OR c2) AND NOT (c3 OR c4). Uma categoria que aparece em includedContentategories não pode aparecer em excludedContentCategories.

Representação JSON 
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
Campos
includedContentCategories[]

enum (ContentCategory)

O conjunto de categorias a serem incluídas nos resultados da pesquisa de itens de mídia. Os itens do conjunto são combinados com a opção OR. Há um máximo de 10 includedContentCategories por solicitação.
excludedContentCategories[]

enum (ContentCategory)

O conjunto de categorias que não serão incluídas nos resultados da pesquisa de itens de mídia. Os itens do conjunto são combinados com a opção OR. Há um máximo de 10 excludedContentCategories por solicitação.

ContentCategory

Esse é um conjunto de categorias de conteúdo predefinidas que você pode filtrar.

Enums
NONE Categoria de conteúdo padrão. Essa categoria é ignorada quando qualquer outra categoria é usada no filtro.
LANDSCAPES Itens de mídia contendo paisagens.
RECEIPTS Itens de mídia que contêm recibos.
CITYSCAPES Itens de mídia contendo paisagens urbanas.
LANDMARKS Itens de mídia contendo pontos de referência.
SELFIES Itens de mídia que são selfies.
PEOPLE Itens de mídia que contêm pessoas.
PETS Itens de mídia que contêm animais de estimação.
WEDDINGS Itens de mídia de casamentos.
BIRTHDAYS Itens de mídia de aniversários.
DOCUMENTS Itens de mídia contendo documentos.
TRAVEL Itens de mídia obtidos durante a viagem.
ANIMALS Itens de mídia que contêm animais.
FOOD Itens de mídia que contêm alimentos.
SPORT Itens de mídia de eventos esportivos.
NIGHT Itens de mídia capturados à noite.
PERFORMANCES Itens de mídia de apresentações.
WHITEBOARDS Itens de mídia contendo lousas interativas.
SCREENSHOTS Itens de mídia que são capturas de tela.
UTILITY Itens de mídia que são considerados utilitários. Isso inclui, entre outros, documentos, capturas de tela, lousas interativas etc.
ARTS Itens de mídia que contêm arte
CRAFTS Itens de mídia que contêm artesanatos.
FASHION Itens de mídia relacionados a moda.
HOUSES Itens de mídia contendo casas.
GARDENS Itens de mídia contendo jardins.
FLOWERS Itens de mídia contendo flores.
HOLIDAYS Itens de mídia tirados de feriados.

MediaTypeFilter

Esse filtro define o tipo de itens de mídia que serão retornados, por exemplo, vídeos ou fotos. Somente um tipo de mídia é compatível.

Representação JSON 
{
  "mediaTypes": [
    enum (MediaType)
  ]
}
Campos
mediaTypes[]

enum (MediaType)

Os tipos de itens de mídia a serem incluídos. Esse campo precisa ser preenchido com apenas um tipo de mídia. Se você especificar vários tipos de mídia, isso resultará em um erro.

MediaType

O conjunto de tipos de mídia que podem ser pesquisados.

Enums
ALL_MEDIA É tratado como se nenhum filtro estivesse aplicado. Todos os tipos de mídia estão incluídos.
VIDEO Todos os itens de mídia que são considerados vídeos. Isso também inclui filmes que o usuário criou usando o app Google Fotos.
PHOTO Todos os itens de mídia considerados fotos. Isso inclui .bmp, .gif, .ico, .jpg (e outras formas), .tiff, .webp e tipos de foto especiais, como fotos ao vivo do iOS, fotos com movimento do Android, panoramas e Photo Spheres.

FeatureFilter

Esse filtro define os recursos que os itens de mídia devem ter.

Representação JSON 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
Campos
includedFeatures[]

enum (Feature)

O conjunto de recursos a serem incluídos nos resultados da pesquisa do item de mídia. Os itens no conjunto são ORed e podem corresponder a qualquer um dos atributos especificados.

Recurso

O conjunto de recursos que podem ser filtrados.

Enums
NONE É tratado como se nenhum filtro fosse aplicado. Todos os recursos estão incluídos.
FAVORITES Itens de mídia que o usuário marcou como favoritos no app Google Fotos.