Cette page a été traduite par l'API Cloud Translation.

Filtrer la recherche multimédia

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 les 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 un data store, et d'avoir ingéré des données. Pour en savoir plus, consultez Créer un data store multimédia et Créer une application multimédia.

Exemples de documents

Consultez ces exemples de documents média. 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 par la forme Backus-Naur étendue suivante :

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

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 :

Trouvez l'ID de votre data store. Si vous disposez déjà de l'ID de votre data store, passez à l'étape suivante.
1. Dans la console Google Cloud , accédez à la page Applications d'IA et cliquez sur Data stores dans le menu de navigation.
  
  Accéder à la page "Data stores"
2. Cliquez sur le nom de votre data store.
3. Sur la page Données de votre datastore, obtenez l'ID du datastore.
Déterminez le ou les champs de document sur lesquels vous souhaitez appliquer un filtre. 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 console Google Cloud , accédez à la page Applications d'IA et cliquez sur Data stores 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 la valeur Indexable du champ est :
  - Si l'option est sélectionnée, le champ est prêt à être filtré pour la recherche. Passez à l'étape 3.
  - Si l'option n'est pas sélectionnée , suivez l'étape 3 pour activer l'indexation du champ.
  - Si la valeur n'est pas disponible, le champ ne peut pas être indexé.
Pour rendre un champ filtrable, tel que le champ categories, procédez comme suit :
1. Dans la console Google Cloud , 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 multimédia.
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à le cas, cochez la case Indexable dans la ligne categories (catégories), puis cliquez sur Save (Enregistrer).
7. Patientez six heures pour que la modification de votre schéma soit propagée. Au bout de six heures, vous pouvez passer à l'étape suivante.

obtenir des résultats de recherche ;

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

Remplacez les éléments suivants :

PROJECT_ID : par l'ID du projet.
DATA_STORE_ID : ID de votre data store.
QUERY : texte de la requête à rechercher.
FILTER : champ de texte permettant de filtrer votre recherche à l'aide d'une expression de filtre.

Par exemple, supposons que vous souhaitiez rechercher des films dans 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 section sur 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 la date available_time est passée et dont la date expire_time n'est pas spécifiée ou est définie sur une date future.

Filtrez les résultats pour n'afficher 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 de filtre pour les classifications de contenu multimédia, les personnes et les organisations est unique et ne suit pas les modèles ci-dessus. Utilisez les exemples suivants et les extraits de filtres copiables 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 Google)

Voici la syntaxe et des exemples pour les filtres "Évaluation", "Personne" et "Organisation" :

Filtrer par 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 : source de la classification. Pour un schéma prédéfini, il s'agit d'une valeur dans le champ aggregate_ratings.rating_source.
- OPERATOR : l'un des opérateurs de comparaison, <=, <, >=, > ou =
- RATING_SCORE : valeur de classification comprise dans la plage [1,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,5 étoiles. 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 personnes par nom 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 : 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 le caractère barre oblique inverse.
Exemple : Ce filtre limite la recherche aux films dans lesquels Brad Pitt ou Kate Winslet jouent.
```
filter: "person(actor, persons.name): ANY(\"Brad Pitt\", \"Kate Winslet\")"
```
Filtrer les organisations : filtrez sur le nom d'une 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 : 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 le caractère barre oblique inverse.
Cet exemple limite la recherche aux films dont la société 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 Google, puis les exemples de cette section. Pour que les filtres "Note", "Personne" et "Organisation" fonctionnent dans un schéma personnalisé, les mappages de propriétés doivent être correctement définis. Pour en savoir plus sur le mappage des 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 notes pour un schéma personnalisé

Ce filtre recherche les films qui ont obtenu 5 étoiles sur Rotten Tomatoes :

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

rotten_tomatoes est une valeur du champ mappé à media_aggregated_rating_source. custom_rating.star_score est le champ mappé à la propriété de 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 correspond au nom du champ mappé à la propriété media_organization_name. music-by est une valeur dans le champ d'enregistrement de l'entreprise qui correspond à media_organization_role.

Filtrer la recherche multimédia Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.