Se usó la API de Cloud Translation para traducir esta página.

Cómo filtrar la búsqueda de contenido multimedia

Si tienes una app de búsqueda de contenido multimedia, puedes usar metadatos para filtrar tus búsquedas. En esta página, se explica cómo usar los campos de metadatos para restringir tu búsqueda a un conjunto específico de documentos.

Antes de comenzar

Asegúrate de haber creado una app de medios y un almacén de datos, y de haber transferido datos. Para obtener más información, consulta Crea un almacén de datos de medios y Crea una app de medios.

Documentos de ejemplo

Revisa estos documentos de medios de ejemplo. Puedes consultarlos mientras lees 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\"}"}

Sintaxis de la expresión de filtro

Asegúrate de comprender la sintaxis de la expresión de filtro que usarás para definir tu filtro de búsqueda. La sintaxis de la expresión de filtro se puede resumir con la siguiente notación de Backus-Naur extendida:

  # 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 la búsqueda de contenido multimedia

Para filtrar la búsqueda de contenido multimedia con metadatos, sigue estos pasos:

Busca el ID de tu almacén de datos. Si ya tienes el ID del almacén de datos, ve al siguiente paso.
1. En la consola de Google Cloud , ve a la página AI Applications y, en el menú de navegación, haz clic en Data Stores.
  
  Ve a la página Almacenes de datos.
2. Haz clic en el nombre de tu almacén de datos.
3. En la página Datos de tu almacén de datos, obtén el ID del almacén de datos.
Determina los campos del documento según los que deseas filtrar. Por ejemplo, para los documentos de Antes de comenzar, puedes usar el campo categories como filtro.

Solo puedes usar campos indexables en las expresiones de filtro. Para determinar si un campo se puede indexar, haz lo siguiente:
1. En la consola de Google Cloud , ve a la página AI Applications y, en el menú de navegación, haz clic en Data Stores.
  
  Ir a la página Almacenes de datos
2. Haz clic en el nombre de tu almacén de datos.
3. En la columna Nombre, haz clic en el almacén de datos.
4. Haz clic en la pestaña Esquema para ver el esquema de tu almacén de datos. Si Indexable para el campo es lo siguiente:
  - Si seleccionaste , ese campo está listo para filtrarse en la búsqueda. Omite el paso 3.
  - Si no está seleccionado , sigue el paso 3 para habilitar la indexación del campo.
  - Si no está disponible , no se puede indexar el campo.
Para que un campo, como el campo categories, se pueda filtrar, haz lo siguiente:
1. En la consola de Google Cloud , ve a la página AI Applications y, en el menú de navegación, haz clic en Apps.
  
  Ir a la página Apps
2. Haz clic en tu app de búsqueda de contenido multimedia.
3. En el menú de navegación, haz clic en Datos.
4. Haz clic en la pestaña Esquema. En esta pestaña, se muestra la configuración actual de los campos.
5. Haz clic en Editar.
6. Si aún no está seleccionada, marca la casilla de verificación Indexable en la fila categories y, luego, haz clic en Save.
7. Espera seis horas para que se propague la edición del esquema. Después de seis horas, puedes continuar con el siguiente paso.

Obtener resultados de la búsqueda

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"
}'

Reemplaza lo siguiente:

PROJECT_ID: el ID de tu proyecto.
DATA_STORE_ID: Es el ID de tu almacén de datos.
QUERY: Es el texto de la búsqueda.
FILTER: Un campo de texto para filtrar tu búsqueda con una expresión de filtro.

Por ejemplo, supongamos que deseas buscar películas en la sección Antes de comenzar y solo quieres resultados de películas que cumplan con los siguientes criterios: (1) Contener la palabra "avatar" y (2) estar en la categoría "Documental". Para ello, debes incluir las siguientes instrucciones en tu llamada:

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

Para obtener más información, consulta el método search.

Haz clic para ver un ejemplo de respuesta.

Si realizas una búsqueda como la del procedimiento anterior, puedes esperar obtener una respuesta similar a la siguiente. Observa que la respuesta solo incluye los documentales 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": {}
}

Cómo filtrar los documentos disponibles

Si quieres que los resultados de la búsqueda solo muestren los documentos disponibles, debes incluir un filtro para ello en tus consultas. Los documentos disponibles son aquellos en los que available_time está en el pasado y expire_time no se especifica o se establece en una fecha futura.

Filtro para devolver solo los documentos que están disponibles actualmente:

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

Reemplaza DATE_TIME por la fecha de hoy, por ejemplo, 2025-04-21 o 2025-04-21T00:00:00Z.

Filtros para calificaciones, personas y organizaciones

La sintaxis de los filtros para las clasificaciones de medios, las personas y las organizaciones es única y no sigue los patrones anteriores. Usa los siguientes ejemplos y fragmentos de filtros que puedes copiar para crear filtros para calificaciones, personas y organizaciones.

El filtro varía según si usas el esquema predefinido de Google o tu propio esquema personalizado.

Filtros para calificaciones, personas y organizaciones (esquema predefinido de Google)

La sintaxis y los ejemplos de los filtros de calificación, persona y organización son los siguientes:

Filtro de calificaciones: Filtra las calificaciones de una fuente determinada.
```
 rating(RATING_SOURCE, aggregate_ratings.rating_score) OPERATOR RATING_SCORE
```
Reemplaza lo siguiente:
- RATING_SOURCE: Es la fuente de la calificación. Para un esquema predefinido, este es un valor en el campo aggregate_ratings.rating_source.
- OPERATOR: Uno de los operadores de comparación, <=, <, >=, > o =
- RATING_SCORE: Es un valor de calificación en el rango [1,5]. Para un esquema predefinido, este es un valor en el campo aggregate_ratings.rating_score.
Ejemplo: Este filtro restringe la búsqueda a películas con calificaciones de IMDB superiores a 2 estrellas y media. El valor entre paréntesis se resuelve en el valor de la clasificación de IMDB:
```
"filter": "rating(imdb, aggregate_ratings.rating_score) > 2.5"
```
Filtrar personas: Filtra por los nombres de las personas para un rol determinado.
```
person(PERSONS_ROLE, persons.name): ANY NAME_STRING
```
Reemplaza lo siguiente:
- PERSONS_ROLE: Para un esquema predefinido, este es un valor en el campo persons.role (director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel o custom-role).
- NAME_STRING: Uno o más nombres de personas con el rol especificado. En el caso de los comandos curl, como en el paso 4, las comillas dobles deben escaparse con el carácter de barra invertida.
Ejemplo: Este filtro restringe la búsqueda a películas en las que uno de los actores es Brad Pitt o Kate Winslet.
```
filter: "person(actor, persons.name): ANY(\"Brad Pitt\", \"Kate Winslet\")"
```
Filter organizations: Filtra por el nombre de una organización para un rol determinado.
```
org(ORG_ROLE, organization.name): ANY NAME_STRING
```
Reemplaza lo siguiente:
- ORG_ROLE: Para un esquema predefinido, este es un valor en el campo organizations.role (director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel o custom-role).
- NAME_STRING: Uno o más nombres de organizaciones con el rol especificado. En el caso de los comandos curl, como en el paso 4, las comillas dobles deben reemplazarse por el carácter de barra inversa.
En este ejemplo, se restringe la búsqueda a las películas en las que la organización de producción es Walt Disney Studios:
```
filter: "org(producer, organizations.name): ANY(\"Walt Disney Studios\")"
```

Filtros para calificaciones, personas y organizaciones (esquema personalizado)

Si usas un esquema personalizado, revisa la sección Esquema predefinido de Google y, luego, los ejemplos de esta sección. Para que los filtros de clasificación, persona y organización funcionen en un esquema personalizado, las asignaciones de propiedades deben establecerse correctamente. Para obtener información sobre las asignaciones de propiedades, consulta Esquema personalizado.

Filtro	Propiedades para asignar
Calificación	`media_aggregated_rating` `media_aggregated_rating_score` `media_aggregated_rating_source`
persona	`media_person` `media_person_name` `media_person_role`
org	`media_organization` `media_organization_name` `media_organization_role`

Ejemplo de un filtro de calificaciones para un esquema personalizado

Este filtro busca películas que tienen una calificación de 5 estrellas en Rotten Tomatoes:

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

El rotten_tomatoes es un valor en el campo asignado a media_aggregated_rating_source. custom_rating.star_score es el campo asignado a la propiedad de clave media_aggregated_rating.media_aggregated_rating_score.

Ejemplo de un filtro de organización para un esquema personalizado

Este filtro busca películas en las que la música fue interpretada por la Orquesta Sinfónica de Londres o la Orquesta Sinfónica de Hollywood Studio.

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

company.id es el nombre del campo asignado a la propiedad media_organization_name. Además, music-by es un valor en el campo de registro de la empresa que se asigna a media_organization_role.

Cómo filtrar la búsqueda de contenido multimedia Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.