Esta página foi traduzida pela API Cloud Translation.

Filtre a pesquisa de conteúdo multimédia

Se tiver uma app de pesquisa de multimédia, pode usar metadados para filtrar as suas consultas de pesquisa. Esta página explica como usar campos de metadados para restringir a sua pesquisa a um conjunto específico de documentos.

Antes de começar

Certifique-se de que criou uma app de multimédia e um arquivo de dados, e carregou dados. Para mais informações, consulte os artigos Crie um arquivo de dados multimédia e Crie uma app de multimédia.

Exemplos de documentos

Reveja estes documentos de multimédia de exemplo. Pode consultá-los à medida que lê esta página.

{"id":"172851","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar: Creating the World of Pandora (2010)\",\"categories\":[\"Documentary\"],\"uri\":\"http://mytestdomain.movie/content/172851\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"243308","schemaId":"default_schema","jsonData":"{\"title\":\"Capturing Avatar (2010)\",\"categories\":[\"Documentary\"],\"uri\":\"http://mytestdomain.movie/content/243308\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"280218","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar: The Way of Water (2022)\",\"categories\":[\"Action\",\"Adventure\",\"Sci-Fi\"],\"uri\":\"http://mytestdomain.movie/content/280218\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"72998","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar (2009)\",\"categories\":[\"Action\",\"Adventure\",\"Sci-Fi\",\"IMAX\"],\"uri\":\"http://mytestdomain.movie/content/72998\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}

Sintaxe das expressões de filtro

Certifique-se de que compreende a sintaxe da expressão de filtro que vai usar para definir o filtro de pesquisa. A sintaxe da expressão de filtro pode ser resumida no seguinte formulário Backus-Naur alargado:

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };
  # Expressions can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
    # A parenthetical expression.
    | "(", expression, ")"
    # A simple expression applying to a text field.
    # Function "ANY" returns true if the field contains any of the literals.
    ( text_field, ":", "ANY", "(", literal, { ",", literal }, ")"
    # A simple expression applying to a numerical field. Function "IN" returns true
    # if a field value is within the range. By default, lower_bound is inclusive and
    # upper_bound is exclusive.
    | numerical_field, ":", "IN", "(", lower_bound, ",", upper_bound, ")"
    # A simple expression that applies to a numerical field and compares with a double value.
    | numerical_field, comparison, double );
    # Datetime field
    | datetime_field, comparison, literal_iso_8601_datetime_format);
  # A lower_bound is either a double or "*", which represents negative infinity.
  # Explicitly specify inclusive bound with the character 'i' or exclusive bound
  # with the character 'e'.
  lower_bound = ( double, [ "e" | "i" ] ) | "*";
  # An upper_bound is either a double or "*", which represents infinity.
  # Explicitly specify inclusive bound with the character 'i' or exclusive bound
  # with the character 'e'.
  upper_bound = ( double, [ "e" | "i" ] ) | "*";
  # Supported comparison operators.
  comparison = "<=" | "<" | ">=" | ">" | "=";
  # A literal is any double quoted string. You must escape backslash (\) and
  # quote (") characters.
  literal = double quoted string;
  text_field = text field - for example, category;
  numerical_field = numerical field - for example, score;
  datetime_field = field of datetime data type - for example available_time;
  literal_iso_8601_datetime_format = either a double quoted string representing ISO 8601 datetime or a numerical field representing microseconds from unix epoch.

Filtre a pesquisa de conteúdo multimédia

Para filtrar a pesquisa de conteúdo multimédia através de metadados, siga estes passos:

Encontre o ID da loja de dados. Se já tiver o ID do armazenamento de dados, avance para o passo seguinte.
1. Na Google Cloud consola, aceda à página Aplicações de IA e, no menu de navegação, clique em Armazenamentos de dados.
  
  Aceda à página Armazenamentos de dados
2. Clique no nome do seu arquivo de dados.
3. Na página Dados da sua loja de dados, obtenha o ID da loja de dados.
Determine o campo ou os campos do documento pelos quais quer filtrar. Por exemplo, para os documentos em Antes de começar, pode usar o campo categories como filtro.

Só pode usar campos indexáveis em expressões de filtro. Para determinar se um campo é indexável, faça o seguinte:
1. Na Google Cloud consola, aceda à página Aplicações de IA e, no menu de navegação, clique em Armazenamentos de dados.
  
  Aceda à página Armazéns de dados
2. Clique no nome do seu arquivo de dados.
3. Na coluna Nome, clique no arquivo de dados.
4. Clique no separador Esquema para ver o esquema da sua base de dados. Se Indexable para o campo for:
  - Selecionou e, em seguida, esse campo está pronto para ser filtrado na pesquisa; ignore o passo 3.
  - Não selecionado e, de seguida, siga o passo 3 para ativar o campo para indexação.
  - Não disponível , então não é possível indexar o campo.
Para tornar um campo, como o campo categories, filtrável, faça o seguinte:
1. Na Google Cloud consola, aceda à página Aplicações de IA e, no menu de navegação, clique em Apps.
  
  Aceda à página Apps
2. Clique na sua app de pesquisa de multimédia.
3. No menu de navegação, clique em Dados.
4. Clique no separador Esquema. Este separador mostra as definições de campo atuais.
5. Clique em Edit.
6. Se ainda não estiver selecionada, selecione a caixa de verificação Indexável na linha categorias e, de seguida, clique em Guardar.
7. Aguarde seis horas para dar tempo para que a edição do esquema se propague. Após seis horas, pode avançar para o passo seguinte.

Receber resultados da pesquisa.

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search:search" \
-d '{
"query": "QUERY",
"filter": "FILTER"
}'

Substitua o seguinte:

PROJECT_ID: o ID do seu projeto.
DATA_STORE_ID: o ID do seu armazenamento de dados.
QUERY: o texto da consulta a pesquisar.
FILTER: um campo de texto para filtrar a pesquisa através de uma expressão de filtro.

Por exemplo, suponhamos que quer pesquisar os filmes na secção Antes de começar e quer resultados da pesquisa apenas para filmes que: (1) contenham a palavra "avatar" e (2) estejam na categoria "Documentário". Pode fazê-lo incluindo as seguintes declarações na sua chamada:

"query": "avatar",
"filter": "categories: ANY(\"Documentary\")"

Para mais informações, consulte o método search.

Clique para ver uma resposta de exemplo.

Se fizer uma pesquisa como a do procedimento anterior, pode esperar receber uma resposta semelhante à seguinte. Tenha em atenção que a resposta inclui apenas os documentários de Avatar.

{
  "results": [
    {
      "id": "243308",
      "document": {
        "name": "projects/431678329718/locations/global/collections/default_collection/dataStores/rdds3_1698205785399/branches/0/documents/243308",
        "id": "243308",
        "structData": {
          "categories": [
            "Documentary"
          ],
          "title": "Capturing Avatar (2010)",
          "uri": "http://mytestdomain.movie/content/243308",
          "media_type": "movie"
        }
      }
    },
    {
      "id": "172851",
      "document": {
        "name": "projects/431678329718/locations/global/collections/default_collection/dataStores/rdds3_1698205785399/branches/0/documents/172851",
        "id": "172851",
        "structData": {
          "categories": [
            "Documentary"
          ],
          "uri": "http://mytestdomain.movie/content/172851",
          "media_type": "movie",
          "title": "Avatar: Creating the World of Pandora (2010)"
        }
      }
    }
  ],
  "totalSize": 2,
  "attributionToken": "XfBcCgwIvIzJqwYQ2_qNxwMSJDY1NzEzNmY1LTAwMDAtMmFhMy05YWU3LTE0MjIzYmIwOGVkMiIFTUVESUEqII6-nRXFy_MXnIaOIsLwnhXUsp0VpovvF6OAlyKiho4i",
  "guidedSearchResult": {},
  "summary": {}
}

Filtre os documentos disponíveis

Se quiser que os resultados da pesquisa devolvam apenas documentos disponíveis, tem de incluir um filtro para tal nas suas consultas. Os documentos disponíveis são aqueles em que a available_time está no passado e a expire_time não está especificada ou está definida para uma data futura.

Filtre para devolver apenas documentos que estão atualmente disponíveis:

  available_time <= \"DATE_TIME\" AND expire_time > \"DATE_TIME\"

Substitua DATE_TIME pela data de hoje, por exemplo, 2025-04-21 ou 2025-04-21T00:00:00Z.

Filtros para classificações, pessoas e organizações

A sintaxe de filtro para classificações de conteúdo multimédia, pessoas e organizações é única e não segue os padrões acima. Use os exemplos seguintes e os fragmentos de filtros copiáveis para criar filtros para classificações, pessoas e organizações.

O filtro difere consoante esteja a usar o esquema predefinido da Google ou o seu próprio esquema personalizado.

Filtros para classificações, pessoas e organizações (esquema predefinido da Google)

A sintaxe e os exemplos para os filtros de classificação, pessoa e organização são os seguintes:

Filtrar por classificações: filtre por classificações de uma determinada origem.
```
 rating(RATING_SOURCE, aggregate_ratings.rating_score) OPERATOR RATING_SCORE
```
Substitua o seguinte:
- RATING_SOURCE: a origem da classificação. Para um esquema predefinido, este é um valor no campo aggregate_ratings.rating_source.
- OPERATOR: um dos operadores de comparação, <= , < , >= , > ou =
- RATING_SCORE: um valor de classificação no intervalo [1,5]. Para um esquema predefinido, este é um valor no campo aggregate_ratings.rating_score.
Exemplo: este filtro restringe a pesquisa a filmes com classificações do IMDB superiores a 2 estrelas e meia. O valor entre parênteses é resolvido para o valor da classificação do IMDB:
```
"filter": "rating(imdb, aggregate_ratings.rating_score) > 2.5"
```
Filtrar pessoas: filtre por nomes de pessoas para uma determinada função.
```
person(PERSONS_ROLE, persons.name): ANY NAME_STRING
```
Substitua o seguinte:
- PERSONS_ROLE: para um esquema predefinido, este é um valor no campo persons.role (director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel ou custom-role).
- NAME_STRING: um ou mais nomes de pessoas com a função especificada. Para comandos curl, como no passo 4, as aspas duplas têm de ser interpretadas de forma literal com o caráter de barra invertida.
Exemplo: este filtro restringe a pesquisa a filmes em que um dos atores é Brad Pitt ou Kate Winslet.
```
filter: "person(actor, persons.name): ANY(\"Brad Pitt\", \"Kate Winslet\")"
```
Filtrar organizações: filtre por um nome de organização para uma determinada função.
```
org(ORG_ROLE, organization.name): ANY NAME_STRING
```
Substitua o seguinte:
- ORG_ROLE: para um esquema predefinido, este é um valor no campo organizations.role (director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel ou custom-role).
- NAME_STRING: um ou mais nomes de organizações com a função especificada. Para comandos curl, como no passo 4, as aspas têm de ser interpretadas de forma literal com o caráter de barra invertida.
Este exemplo restringe a pesquisa a filmes cuja organização de produção seja Walt Disney Studios:
```
filter: "org(producer, organizations.name): ANY(\"Walt Disney Studios\")"
```

Filtros para classificações, pessoas e organizações (esquema personalizado)

Se usar um esquema personalizado, reveja a secção Esquema predefinido da Google e, em seguida, os exemplos nesta secção. Para que os filtros de classificação, pessoa e organização funcionem num esquema personalizado, os mapeamentos de propriedades têm de estar definidos corretamente. Para obter informações sobre os mapeamentos de propriedades, consulte o artigo Esquema personalizado.

Filtro	Propriedades a mapear
classificação	`media_aggregated_rating` `media_aggregated_rating_score` `media_aggregated_rating_source`
pessoa	`media_person` `media_person_name` `media_person_role`
org	`media_organization` `media_organization_name` `media_organization_role`

Exemplo de um filtro de classificações para um esquema personalizado

Este filtro pesquisa filmes com uma classificação de 5 estrelas do Rotten Tomatoes:

"filter": "rating(rotten_tomatoes, custom_rating.star_score) = 5"

rotten_tomatoes é um valor no campo mapeado para media_aggregated_rating_source. O custom_rating.star_score é o campo mapeado para a propriedade da chave media_aggregated_rating.media_aggregated_rating_score.

Exemplo de um filtro de organização para um esquema personalizado

Este filtro pesquisa filmes onde a música foi composta pela Orquestra Sinfónica de Londres ou pela Hollywood Studio Symphony.

"filter: org(music-by, company.id): ANY (\"London Symphony Orchestra\", \"Hollywood Studio Symphony\" )

O company.id é o nome do campo mapeado para a propriedade media_organization_name. Além disso, music-by é um valor no campo de registo da empresa que é mapeado para media_organization_role.

Filtre a pesquisa de conteúdo multimédia Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Exemplos de documentos

Sintaxe das expressões de filtro

Filtre a pesquisa de conteúdo multimédia

Filtre os documentos disponíveis

Filtros para classificações, pessoas e organizações

Filtros para classificações, pessoas e organizações (esquema predefinido da Google)

Filtros para classificações, pessoas e organizações (esquema personalizado)

Filtre a pesquisa de conteúdo multimédia