Nota:Vertex AI Search verrà rinominato Agent Search. Stiamo aggiornando i contenuti per riflettere il nuovo brand.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Filtrare la ricerca multimediale

Se hai un'app di ricerca di contenuti multimediali, puoi utilizzare i metadati per filtrare le query di ricerca. Questa pagina spiega come utilizzare i campi dei metadati per limitare la ricerca a un insieme specifico di documenti.

Prima di iniziare

Assicurati di aver creato un'app multimediale e un datastore e di aver inserito i dati. Per saperne di più, consulta Crea un datastore di contenuti multimediali e Crea un'app multimediale.

Documenti di esempio

Esamina questi documenti di contenuti multimediali di esempio. Puoi farvi riferimento mentre leggi questa pagina.

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

Sintassi delle espressioni di filtro

Assicurati di comprendere la sintassi delle espressioni di filtro che utilizzerai per definire il filtro di ricerca. La sintassi delle espressioni di filtro può essere riassunta dalla seguente forma di Backus-Naur estesa:

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

Filtra la ricerca di contenuti multimediali

Per filtrare la ricerca di contenuti multimediali utilizzando i metadati:

Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.
1. Nella Google Cloud console, vai alla pagina AI Applications.
  
  Vai ad App
2. Nella pagina App, trova il nome dell'app e recupera l'ID app dalla colonna ID.
Determina il campo o i campi del documento su cui vuoi filtrare. Ad esempio, per i documenti in Prima di iniziare, puoi utilizzare il categories campo come filtro.

Nelle espressioni di filtro puoi utilizzare solo i campi indicizzabili. Per determinare se un campo è indicizzabile:
1. Nella Google Cloud console, vai alla pagina AI Applications e nel menu di navigazione, fai clic su Datastore.
  
  Vai alla pagina Datastore
2. Fai clic sul nome del tuo datastore.
3. Nella colonna Nome, fai clic sul datastore.
4. Fai clic sulla scheda Schema per visualizzare lo schema del datastore. Se Indicizzabile per il campo è:
  - Selezionato , il campo è pronto per essere filtrato per la ricerca; salta il passaggio 3.
  - Se non è selezionato , segui il passaggio 3 per abilitare l'indicizzazione del campo.
  - Se non è disponibile , il campo non può essere indicizzato.
Per rendere filtrabile un campo, ad esempio il campo categories:
1. Nella Google Cloud console, vai alla pagina AI Applications e fai clic su App nel menu di navigazione.
  
  Vai alla pagina App
2. Fai clic sull'app di ricerca di contenuti multimediali.
3. Nel menu di navigazione, fai clic su Dati.
4. Fai clic sulla scheda Schema. Questa scheda mostra le impostazioni dei campi correnti.
5. Fai clic su Modifica.
6. Se non è già selezionata, seleziona la casella di controllo Indicizzabile nella riga categories e poi fai clic su Salva.
7. Attendi sei ore per consentire la propagazione della modifica dello schema. Dopo sei ore, puoi procedere al passaggio successivo.

Ottieni i risultati di ricerca.

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

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto.
APP_ID: l'ID app.
QUERY: il testo della query da cercare.
FILTER: un campo di testo per filtrare la ricerca utilizzando un'espressione di filtro.

Ad esempio, supponiamo che tu voglia cercare i film nella sezione Prima di iniziare e che tu voglia risultati di ricerca solo per i film che: (1) contengono la parola "avatar" e (2) appartengono alla categoria "Documentario" . Per farlo, devi includere le seguenti istruzioni nella chiamata:

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

Per saperne di più, consulta il metodo search.

Fai clic per visualizzare una risposta di esempio.

Se esegui una ricerca come quella nella procedura precedente, puoi aspettarti di ricevere una risposta simile alla seguente. Tieni presente che la risposta include solo i documentari su 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": {}
}

Filtra i documenti disponibili

Se vuoi che i risultati di ricerca restituiscano solo i documenti disponibili, devi includere un filtro per questo nelle query. I documenti disponibili sono quelli in cui available_time è nel passato e expire_time non è specificato o è impostato su una data futura.

Filtra per restituire solo i documenti attualmente disponibili:

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

Sostituisci DATE_TIME con la data odierna, ad esempio, 2025-04-21 o 2025-04-21T00:00:00Z.

Filtri per valutazioni, persone e organizzazioni

La sintassi dei filtri per le valutazioni dei contenuti multimediali, le persone e le organizzazioni è univoca e non segue i pattern sopra indicati. Utilizza gli esempi e gli snippet di filtri copiabili riportati di seguito per creare filtri per valutazioni, persone e organizzazioni.

Il filtro varia a seconda che tu stia utilizzando lo schema predefinito di Google o il tuo schema personalizzato.

Filtri per valutazioni, persone e organizzazioni (schema predefinito di Google)

La sintassi e gli esempi per i filtri di valutazione, persona e organizzazione sono i seguenti:

Filtra le valutazioni:filtra le valutazioni di una determinata fonte.
```
 rating(RATING_SOURCE, aggregate_ratings.rating_score) OPERATOR RATING_SCORE
```
Sostituisci quanto segue:
- RATING_SOURCE: la fonte della valutazione. Per uno schema predefinito, questo è un valore nel campo aggregate_ratings.rating_source.
- OPERATOR: uno degli operatori di confronto, <= , < , >= , > , o =
- RATING_SCORE: un valore di valutazione nell'intervallo [1,5]. Per uno schema predefinito, questo è un valore nel campo aggregate_ratings.rating_score.
Esempio: questo filtro limita la ricerca ai film con valutazioni IMDB superiori a 2 stelle e mezzo. Il valore tra parentesi si risolve nel valore della valutazione IMDB:
```
"filter": "rating(imdb, aggregate_ratings.rating_score) > 2.5"
```
Filtra le persone:filtra i nomi delle persone per un determinato ruolo.
```
person(PERSONS_ROLE, persons.name): ANY NAME_STRING
```
Sostituisci quanto segue:
- PERSONS_ROLE: per uno schema predefinito, questo è un valore nel 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 più nomi di persone con il ruolo specificato. Per i comandi curl, come nel passaggio 4, le virgolette doppie devono essere sottoposte a escape con il carattere barra rovesciata.
Esempio: questo filtro limita la ricerca ai film in cui uno degli attori è Brad Pitt o Kate Winslet.
```
filter: "person(actor, persons.name): ANY(\"Brad Pitt\", \"Kate Winslet\")"
```
Filtra le organizzazioni:filtra il nome di un'organizzazione per un determinato ruolo.
```
org(ORG_ROLE, organization.name): ANY NAME_STRING
```
Sostituisci quanto segue:
- ORG_ROLE: per uno schema predefinito, questo è un valore nel 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 più nomi di organizzazioni con il ruolo specificato. Per i comandi curl, come nel passaggio 4, le virgolette doppie devono essere sottoposte a escape con il carattere barra rovesciata.
Questo esempio limita la ricerca ai film in cui l'organizzazione di produzione è Walt Disney Studios:
```
filter: "org(producer, organizations.name): ANY(\"Walt Disney Studios\")"
```

Filtri per valutazioni, persone e organizzazioni (schema personalizzato)

Se utilizzi uno schema personalizzato, esamina la sezione relativa allo schema predefinito di Google e poi gli esempi in questa sezione. Affinché i filtri di valutazione, persona e organizzazione funzionino in uno schema personalizzato, i mapping delle proprietà devono essere impostati correttamente. Per informazioni sui mapping delle proprietà, consulta Schema personalizzato.

Filtro	Proprietà da mappare
rating	`media_aggregated_rating` `media_aggregated_rating_score` `media_aggregated_rating_source`
person	`media_person` `media_person_name` `media_person_role`
org	`media_organization` `media_organization_name` `media_organization_role`

Esempio di filtro di valutazione per uno schema personalizzato

Questo filtro cerca i film che hanno una valutazione di 5 stelle su Rotten Tomatoes:

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

rotten_tomatoes è un valore nel campo mappato a media_aggregated_rating_source. custom_rating.star_score è il campo mappato alla proprietà chiave media_aggregated_rating.media_aggregated_rating_score.

Esempio di filtro di organizzazione per uno schema personalizzato

Questo filtro cerca i film in cui la musica è stata composta dalla London Symphony Orchestra o dalla Hollywood Studio Symphony.

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

company.id è il nome del campo mappato alla proprietà media_organization_name. Inoltre, music-by è un valore nel campo del record dell'azienda che esegue il mapping a media_organization_role.

Filtrare la ricerca multimediale Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.