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 no álbum especificado 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 vai 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 pode ser definido com filtros.
pageSize

integer

Número máximo de itens de mídia para retornar na resposta. É possível que menos itens de mídia sejam retornados do que o número especificado. O pageSize padrão é 25, e 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 o 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 em conjunto com um 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 mostrados do mais recente para o mais antigo por creationTime. O fornecimento de MediaMetadata.creation_time mostra os resultados da pesquisa na ordem oposta, primeiro o mais antigo e depois o mais recente. 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. A presença dele é o único indicador confiável de que mais itens de mídia estã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

Filtros

Filtros que podem ser aplicados a uma pesquisa de itens 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 deles.
includeArchivedMedia

boolean

Se definido, os resultados incluem itens de mídia que o usuário arquivou. 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). Este campo é 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 à data de criação dos itens de mídia. É possível incluir até cinco datas por solicitação.
ranges[]

object (DateRange)

Lista de intervalos de datas que correspondem à data de criação dos itens de mídia. É possível incluir até cinco intervalos de datas por solicitação.

Data

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

Sem suporte: definir todos os valores como 0, apenas 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 é significativo.

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 intervalo) 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 excluídas. Em cada lista, as categorias são combinadas com um OR.

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 vai receber itens de mídia que contenham (c1 OU c2 OU c3).

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

O exemplo anterior vai buscar itens de mídia que contenham (c1 OU c2) E NÃO (c3 OU 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

É um conjunto de categorias de conteúdo predefinidas que podem ser filtradas.

Enums
NONE Categoria de conteúdo padrão. Essa categoria é ignorada quando qualquer outra categoria é usada no filtro.
LANDSCAPES Itens de mídia com paisagens.
RECEIPTS Itens de mídia que contêm recibos.
CITYSCAPES Itens de mídia com paisagens urbanas.
LANDMARKS Itens de mídia que contêm 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 com animais de estimação.
WEDDINGS Itens de mídia de casamentos.
BIRTHDAYS Itens de mídia de aniversários.
DOCUMENTS Itens de mídia que contêm documentos.
TRAVEL Itens de mídia feitos durante a viagem.
ANIMALS Itens de mídia com animais.
FOOD Itens de mídia que contenham alimentos.
SPORT Itens de mídia de eventos esportivos.
NIGHT Itens de mídia feitos à noite.
PERFORMANCES Itens de mídia de apresentações.
WHITEBOARDS Itens de mídia que contêm lousas digitais.
SCREENSHOTS Itens de mídia que são capturas de tela.
UTILITY Itens de mídia considerados úteis. Isso inclui, entre outros, documentos, capturas de tela, quadros brancos 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 à moda.
HOUSES Itens de mídia que contêm casas.
GARDENS Itens de mídia que contêm jardins.
FLOWERS Itens de mídia com 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 é aceito.

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

Conjunto de tipos de mídia que podem ser pesquisados.

Enums
ALL_MEDIA É tratado como se nenhum filtro fosse aplicado. Todos os tipos de mídia são incluídos.
VIDEO Todos os itens de mídia 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 grafias), .tiff, .webp e tipos de fotos especiais, como fotos ao vivo do iOS, fotos em movimento do Android, panoramas e fotosferas.

FeatureFilter

Esse filtro define os recursos que os itens de mídia precisam 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 recursos especificados.

Recurso

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.