Esta página foi traduzida pela API Cloud Translation.

Filtrar a pesquisa de mídia

Se você tiver um app de pesquisa de mídia, use metadados para filtrar suas consultas de pesquisa. Nesta página, explicamos como usar campos de metadados para restringir sua pesquisa a um conjunto específico de documentos.

Antes de começar

Verifique se você criou um app de mídia e um repositório de dados e fez a ingestão de dados. Para mais informações, consulte Criar um repositório de dados de mídia e Criar um app de mídia.

Exemplos de documentos

Revise estes exemplos de documentos de mídia. Consulte-as enquanto 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 da expressão do filtro

Entenda a sintaxe da expressão de filtro que você vai usar para definir seu filtro de pesquisa. A sintaxe da expressão de filtro pode ser resumida pelo seguinte Formalismo de Backus-Naur Estendido:

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

Filtrar pesquisa de mídia

Para filtrar a pesquisa de mídia usando metadados, siga estas etapas:

Encontre o ID do repositório de dados. Se você já tiver o ID do repositório de dados, pule para a próxima etapa.
1. No console Google Cloud , acesse a página Aplicativos de IA e, no menu de navegação, clique em Repositórios de dados.
  
  Acesse a página "Repositórios de dados"
2. Clique no nome do seu repositório de dados.
3. Na página Dados do seu repositório de dados, encontre o ID do repositório.
Determine o campo ou os campos do documento que você quer usar como filtro. Por exemplo, para os documentos em Antes de começar, você pode usar o campo categories como um filtro.

Só é possível usar campos indexáveis em expressões de filtro. Para determinar se um campo pode ser indexado, faça o seguinte:
1. No console Google Cloud , acesse a página Aplicativos de IA e, no menu de navegação, clique em Repositórios de dados.
  
  Acesse a página Repositórios de dados
2. Clique no nome do seu repositório de dados.
3. Na coluna Nome, clique no repositório de dados.
4. Clique na guia Esquema para conferir o esquema do repositório de dados. Se Indexável para o campo for:
  - Selecionado , o campo está pronto para ser filtrado na pesquisa. Pule a etapa 3.
  - Não selecionado , siga a etapa 3 para ativar o campo para indexação.
  - Não disponível , o campo não pode ser indexado.
Para tornar um campo, como categories, filtrável, faça o seguinte:
1. No console Google Cloud , acesse a página Aplicativos de IA e no menu de navegação, clique em Apps.
  
  Acessar a página "Apps"
2. Clique no app de pesquisa de mídia.
3. No menu de navegação, clique em Dados.
4. Clique na guia Esquema. Esta guia mostra as configurações atuais dos campos.
5. Clique em Editar.
6. Se ela ainda não estiver marcada, selecione a caixa de seleção Indexável na linha Categorias e clique em Salvar.
7. Aguarde seis horas para que a edição do esquema seja propagada. Depois de seis horas, siga para a próxima etapa.

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:

PROJECT_ID: ID do projeto.
DATA_STORE_ID: o ID do seu repositório de dados.
QUERY: o texto da consulta a ser pesquisado.
FILTER: um campo de texto para filtrar sua pesquisa usando uma expressão de filtro.

Por exemplo, suponha que você queira pesquisar os filmes na seção Antes de começar e queira resultados de pesquisa apenas para filmes que: (1) contenham a palavra "avatar" e (2) estejam na categoria "Documentário". Para isso, inclua 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 um exemplo de resposta.

Se você fizer uma pesquisa como a do procedimento anterior, vai receber uma resposta semelhante a esta. 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": {}
}

Filtrar documentos disponíveis

Se você quiser que os resultados da pesquisa retornem apenas documentos disponíveis, inclua um filtro para isso nas suas consultas. Os documentos disponíveis são aqueles em que o available_time está no passado e o expire_time não está especificado ou está definido para uma data futura.

Filtre para retornar apenas documentos disponíveis no momento:

  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 mídia, pessoas e organizações é exclusiva e não segue os padrões acima. Use os exemplos a seguir e copie snippets de filtro para criar filtros de classificações, pessoas e organizações.

O filtro varia dependendo se você está usando o esquema predefinido do Google ou seu próprio esquema personalizado.

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

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

Filtrar por classificações:filtre por classificações de uma determinada fonte.
```
 rating(RATING_SOURCE, aggregate_ratings.rating_score) OPERATOR RATING_SCORE
```
Substitua:
- RATING_SOURCE: a origem da classificação. Para um esquema predefinido, esse é 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, esse é um valor no campo aggregate_ratings.rating_score.
Exemplo: esse filtro restringe a pesquisa a filmes com classificações do IMDB maiores que 2 estrelas e meia. O valor entre parênteses é resolvido como 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:
- PERSONS_ROLE: para um esquema predefinido, esse é 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 Etapa 4, as aspas duplas precisam ser precedidas do caractere de barra invertida.
Exemplo: esse 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 pelo nome de uma organização para uma determinada função.
```
org(ORG_ROLE, organization.name): ANY NAME_STRING
```
Substitua:
- ORG_ROLE: para um esquema predefinido, esse é 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 na etapa 4, as aspas duplas precisam ser escapadas com o caractere de barra invertida.
Este exemplo restringe a pesquisa a filmes em que a organização de produção é Walt Disney Studios:
```
filter: "org(producer, organizations.name): ANY(\"Walt Disney Studios\")"
```

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

Se você usa um esquema personalizado, consulte a seção Esquema predefinido do Google e os exemplos nesta seção. Para que os filtros de classificação, pessoa e organização funcionem em um esquema personalizado, os mapeamentos de propriedades precisam ser definidos corretamente. Para informações sobre mapeamentos de propriedades, consulte Esquema personalizado.

Filtro	Propriedades a serem mapeadas
avaliaçã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ção para um esquema personalizado

Este filtro pesquisa filmes que têm uma classificação de 5 estrelas do Rotten Tomatoes:

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

O 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

Esse filtro procura filmes em que a música foi feita 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. E o music-by é um valor no campo de registro da empresa que é mapeado para media_organization_role.

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