Filtrer la recherche de contenus multimédias

Si vous disposez d'une application de recherche de contenus multimédias, vous pouvez utiliser des métadonnées pour filtrer vos requêtes de recherche. Cette page explique comment utiliser des champs de métadonnées pour limiter votre recherche à un ensemble spécifique de documents.

Avant de commencer

Assurez-vous d'avoir créé une application multimédia et data store, et d'avoir ingéré des données. Pour en savoir plus, consultez Créer un datastore multimédia et Créer une application multimédia.

Exemples de documents

Consultez ces exemples de documents multimédias. Vous pouvez vous y référer tout au long de cette page.

{"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\"}"}

Syntaxe des expressions de filtre

Assurez-vous de comprendre la syntaxe des expressions de filtre que vous utiliserez pour définir votre filtre de recherche. La syntaxe de l'expression de filtre peut être résumée au format EBNF étendu comme suit :

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

Filtrer la recherche de contenus multimédias

Pour filtrer la recherche de contenus multimédias à l'aide de métadonnées, procédez comme suit :

1. Trouvez l'ID de votre application. Si vous disposez déjà de l'ID de votre application, passez à l'étape suivante.

   1. Dans la Google Cloud console, accédez à la page Applications d'IA.

      Accédez à "Applications".

   2. Sur la page Applications, recherchez le nom de votre application et retrouvez son ID dans la colonne ID.

2. Déterminez le ou les champs de document sur lesquels vous souhaitez filtrer. Par exemple, pour les documents de la section Avant de commencer, vous pouvez utiliser le champ categories comme filtre.

   Vous ne pouvez utiliser que des champs indexables dans les expressions de filtre. Pour déterminer si un champ est indexable, procédez comme suit :

   1. Dans la Google Cloud console, accédez à la page Applications d'IA et cliquez sur Datastores dans le menu de navigation.

      Accéder à la page "Datastores"

   2. Cliquez sur le nom de votre data store.

   3. Dans la colonne Nom, cliquez sur le data store.

   4. Cliquez sur l'onglet Schéma pour afficher le schéma de votre data store. Si Indexable pour le champ est :

      • Sélectionné , ce champ est prêt à être filtré pour la recherche. Passez à l'étape 3.

      • Non sélectionné , suivez l'étape 3 pour activer l'indexation du champ.

      • Non disponible , le champ ne peut pas être indexé.

3. Pour rendre un champ, tel que le champ categories, filtrable, procédez comme suit :

   1. Dans la Google Cloud console, accédez à la page Applications d'IA, puis cliquez sur Applications dans le menu de navigation.

      Accéder à la page "Applications"

   2. Cliquez sur votre application de recherche de contenus multimédias.

   3. Dans le menu de navigation, cliquez sur Données.

   4. Cliquez sur l'onglet Schéma. Cet onglet affiche les paramètres de champ actuels.

   5. Cliquez sur Modifier.

   6. Si ce n'est pas déjà fait, cochez la case Indexable dans la ligne categories, puis cliquez sur Enregistrer.

   7. Attendez six heures pour que la modification de votre schéma soit appliquée. Au bout de six heures, vous pouvez passer à l'étape suivante.

4. Obtenez les résultats de recherche.

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

   Remplacez les éléments suivants :

   • PROJECT_ID : par l'ID du projet.
   • APP_ID : par l'ID de l'application.
   • QUERY : par le texte de la requête à rechercher.
   • FILTER: par un champ de texte permettant de filtrer votre recherche à l'aide d'une expression de filtre.

   Supposons, par exemple, que vous souhaitiez effectuer une recherche dans les films de la section Avant de commencer et que vous ne souhaitiez obtenir des résultats de recherche que pour les films qui : (1) contiennent le mot "avatar" et (2) appartiennent à la catégorie "Documentaire" . Pour ce faire, incluez les instructions suivantes dans votre appel :

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

   Pour en savoir plus, consultez la méthode search.

   Cliquez pour obtenir un exemple de réponse.

   Si vous effectuez une recherche comme celle de la procédure précédente, vous pouvez vous attendre à obtenir une réponse semblable à la suivante. Notez que la réponse n'inclut que les documentaires 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": {}
   }

Filtrer les documents disponibles

Si vous souhaitez que vos résultats de recherche ne renvoient que les documents disponibles, vous devez inclure un filtre à cet effet dans vos requêtes. Les documents disponibles sont ceux dont le champ available_time est antérieur et dont le champ expire_time n'est pas spécifié ou est défini sur une date ultérieure.

Filtrez pour ne renvoyer que les documents actuellement disponibles :

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

Remplacez DATE_TIME par la date du jour, par exemple 2025-04-21 ou 2025-04-21T00:00:00Z.

Filtres pour les notes, les personnes et les organisations

La syntaxe des filtres pour les notes, les personnes et les organisations est unique et ne suit pas les modèles ci-dessus. Utilisez les exemples et les extraits de filtres copiables suivants pour créer des filtres pour les notes, les personnes et les organisations.

Le filtre diffère selon que vous utilisez le schéma prédéfini de Google ou votre propre schéma personnalisé.

Filtres pour les notes, les personnes et les organisations (schéma prédéfini de Google)

La syntaxe et les exemples pour les filtres de note, de personne et d'organisation sont les suivants :

• Filtrer les notes : filtrez les notes d'une source donnée.

   rating(RATING_SOURCE, aggregate_ratings.rating_score) OPERATOR RATING_SCORE
  

  Remplacez les éléments suivants :

  • RATING_SOURCE : par la source de la note. Pour un schéma prédéfini, il s'agit d'une valeur dans le champ aggregate_ratings.rating_source.

  • OPERATOR : par l'un des opérateurs de comparaison, soit <= , < , >= , > ou =

  • RATING_SCORE : par une valeur de note comprise entre 1 et 5. Pour un schéma prédéfini, il s'agit d'une valeur dans le champ aggregate_ratings.rating_score.

  Exemple : Ce filtre limite la recherche aux films dont la note IMDB est supérieure à 2 étoiles et demie. La valeur entre parenthèses correspond à la valeur de la note IMDB :

  "filter": "rating(imdb, aggregate_ratings.rating_score) > 2.5"
  

• Filtrer les personnes : filtrez les noms de personnes pour un rôle donné.

  person(PERSONS_ROLE, persons.name): ANY NAME_STRING
  

  Remplacez les éléments suivants :

  • PERSONS_ROLE: pour un schéma prédéfini, il s'agit d'une valeur dans le champ 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: par un ou plusieurs noms de personnes ayant le rôle spécifié. Pour les commandes curl, comme à l'étape 4, les guillemets doubles doivent être échappés avec la barre oblique inverse.

  Exemple : Ce filtre limite la recherche aux films dans lesquels l'un des acteurs est Brad Pitt ou Kate Winslet.

  filter: "person(actor, persons.name): ANY(\"Brad Pitt\", \"Kate Winslet\")"
  

• Filtrer les organisations : filtrez un nom d'organisation pour un rôle donné.

  org(ORG_ROLE, organization.name): ANY NAME_STRING
  

  Remplacez les éléments suivants :

  • ORG_ROLE: pour un schéma prédéfini, il s'agit d'une valeur dans le champ 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: par un ou plusieurs noms d'organisations ayant le rôle spécifié. Pour les commandes curl, comme à l'étape 4, les guillemets doubles doivent être échappés avec la barre oblique inverse.

  Cet exemple limite la recherche aux films dont l'organisation de production est Walt Disney Studios :

  filter: "org(producer, organizations.name): ANY(\"Walt Disney Studios\")"
  

Filtres pour les notes, les personnes et les organisations (schéma personnalisé)

Si vous utilisez un schéma personnalisé, consultez la section Schéma prédéfini de Google, puis les exemples de cette section. Pour que les filtres de note, de personne et d'organisation fonctionnent dans un schéma personnalisé, les mappages de propriétés doivent être correctement définis. Pour en savoir plus sur les mappages de propriétés, consultez Schéma personnalisé.

Filtre	Propriétés à mapper
Note	media_aggregated_rating media_aggregated_rating_score media_aggregated_rating_source
Personne	media_person media_person_name media_person_role
org	media_organization media_organization_name media_organization_role

Exemple de filtre de note pour un schéma personnalisé

Ce filtre recherche les films qui ont une note de 5 étoiles sur Rotten Tomatoes :

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

rotten_tomatoes est une valeur dans le champ mappé à media_aggregated_rating_source. custom_rating.star_score est le champ mappé à la propriété clé media_aggregated_rating.media_aggregated_rating_score.

Exemple de filtre d'organisation pour un schéma personnalisé

Ce filtre recherche les films dont la musique a été composée par le London Symphony Orchestra ou le Hollywood Studio Symphony.

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

company.id est le nom du champ mappé à la propriété media_organization_name. De plus, music-by est une valeur dans le champ d'enregistrement de l'entreprise qui correspond à media_organization_role.