Configurare i controlli di pubblicazione per la rete di ricerca

I controlli di pubblicazione (chiamati anche controlli) modificano il comportamento predefinito di come viene pubblicata una richiesta quando vengono restituiti i risultati. I controlli di pubblicazione agiscono a livello di datastore.

Ad esempio, i controlli possono aumentare e nascondere i risultati, filtrare le voci dai risultati restituiti, associare stringhe tra loro come sinonimi o reindirizzare i risultati a URI specificati.

Questa pagina descrive i controlli di pubblicazione per le app di ricerca. Per informazioni sull'utilizzo dei controlli di pubblicazione con i suggerimenti per i contenuti multimediali, vedi Creare e gestire le configurazioni di pubblicazione dei contenuti multimediali.

Informazioni sui controlli di pubblicazione

Per modificare i risultati di una richiesta, crea prima un controllo della pubblicazione. Poi, collega questo controllo alla configurazione di gestione di un'app di ricerca. Una configurazione di gestione configura i metadati utilizzati per generare risultati in tempo reale, come risultati di ricerca o risposte. Un controllo di pubblicazione influisce solo sulle richieste pubblicate dall'app se è collegato alla configurazione di pubblicazione dell'app.

Alcuni controlli, come i controlli di incremento, hanno dipendenze dagli archivi dati. Se un datastore viene rimosso da un'app, anche tutti i controlli che dipendono dal datastore vengono rimossi dall'app e diventano inattivi, ma non vengono eliminati.

Tipi di controlli di pubblicazione

Sono disponibili i seguenti tipi di controlli di pubblicazione:

Controllo Descrizione Disponibile per
Controllo del boost Modifica l'ordine dei risultati restituiti App di ricerca con datastore che supportano uno schema, ad esempio datastore che contengono dati strutturati, siti web con dati strutturati (indicizzazione avanzata dei siti web), dati non strutturati con metadati o dati multimediali
Controllo filtro Rimuove le voci dai risultati restituiti App di ricerca con datastore che supportano uno schema, ad esempio datastore che contengono dati strutturati, siti web (indicizzazione avanzata dei siti web), dati non strutturati con metadati o dati multimediali
Controllo sinonimi Associa le query tra loro App di ricerca con datastore di siti web (indicizzazione avanzata dei siti web), strutturati, non strutturati o multimediali
Controllo del reindirizzamento Reindirizza a un URI specificato Tutte le app di ricerca
Controllo della promozione Promuove un link specificato per una query Tutte le app di ricerca

Informazioni sulle condizioni

Quando crei un controllo, puoi definire facoltativamente una condizione che determina quando viene applicato il controllo. Le condizioni vengono definite utilizzando i campi condizione. Sono disponibili i seguenti campi di condizione:

  • Termini di query (queryTerms). Un controllo facoltativo che viene applicato quando vengono cercate query specifiche. Quando viene utilizzata la condizione queryTerms, il controllo viene applicato quando il valore di queryTerms corrisponde a un termine in SearchRequest.query. I termini di ricerca possono essere utilizzati solo quando Control.searchUseCase è impostato su SOLUTION_TYPE_SEARCH. È possibile specificare fino a 10 queryTerms diversi in un singolo Control.condition. Se non vengono specificati termini di query, il campo queryTerms viene ignorato.

    Per un controllo della pubblicazione della promozione, non è possibile specificare queryTerms se stai specificando la condizione queryRegex, che è applicabile solo alla ricerca di base sui siti web. Inoltre, il campo fullMatch per la ricerca di base sul sito web deve essere impostato su true se queryTerms è specificato. Per tutte le altre app di ricerca, è supportato solo queryTerms e fullMatch può essere impostato su true o false.

  • Intervallo di tempo (activeTimeRange). Un controllo facoltativo che viene applicato quando una richiesta si verifica in un intervallo di tempo specificato. Verifica che l'ora di ricezione di una richiesta sia compresa tra le activeTimeRange.startTime e le activeTimeRange.endTime. È possibile specificare fino a 10 intervalli activeTimeRange in un singolo Control.condition. Se il campo activeTimeRange non è specificato, il campo viene ignorato.

  • queryRegex. Disponibile solo per un controllo della pubblicazione della promozione solo per la ricerca di base sui siti web. Si tratta di una condizione facoltativa che applica il controllo quando la query corrisponde all'espressione regolare specificata. Questa condizione non può essere specificata se stai specificando la condizione queryTerms.

Se per un controllo vengono specificate più condizioni, il controllo viene applicato alla richiesta di ricerca quando entrambi i tipi di condizioni sono soddisfatti. Se vengono specificati più valori per la stessa condizione, solo uno dei valori deve corrispondere affinché la condizione sia soddisfatta.

Ad esempio, considera la seguente condizione con due termini di query specificati:

"queryTerms": [
  {
    "value": "gShoe",
    "fullMatch": true
  },
  {
    "value": "gBoot",
    "fullMatch": true
  }
]

La condizione verrà soddisfatta per una richiesta con SearchRequest.query="gShoe" o una richiesta con SearchRequest.query="gBoot", ma non verrà soddisfatta con SearchRequest.query="gSandal" o qualsiasi altra stringa.

Se non vengono specificate condizioni, il controllo viene sempre applicato.

Per ulteriori informazioni, consulta il campo Condition nel riferimento API.

Creare e allegare controlli di pubblicazione del boost

Un controllo di pubblicazione del boost riordina i risultati promuovendoli o declassandoli in base alle condizioni applicate. Il boost funziona applicando un fattore di moltiplicazione al ranking di un documento che soddisfa le condizioni di boost.

Per creare e collegare il controllo dell'incremento:

Console

  1. Nella Google Cloud console, vai alla pagina AI Applications.

    Applicazioni di AI

  2. Seleziona l'app per cui vuoi creare il controllo dell'incremento.

  3. Nella pagina di panoramica dell'app, seleziona Aumenta/Diminuisci elencato nella fase Segnale.

  4. Nella pagina Segnale, fai clic su Crea controllo.

  5. Nel riquadro Crea controllo, segui questi passaggi:

    1. Inserisci un nome per il controllo di boost/bury e fai clic su Continua.

    2. Imposta le seguenti condizioni che attivano il controllo. Se non sono configurate condizioni, il controllo è sempre attivo:

      1. Aggiungi termini di query con corrispondenza parziale. Il controllo ha effetto quando questi termini di ricerca corrispondono parzialmente.

      2. Aggiungi termini di query con corrispondenza esatta. Il controllo ha effetto quando questi termini di query corrispondono esattamente.

      3. Per aggiungere un intervallo di tempo attivo, fai clic su Aggiungi intervallo di tempo e imposta Ora di inizio 1 e Ora di fine 1. Definisce la finestra in cui la condizione è attiva. Puoi aggiungere un massimo di 10 intervalli di tempo.

      4. Fai clic su Continua.

    3. Definisci le azioni che vuoi attivare con questo controllo:

      1. Seleziona un datastore dall'elenco. Se vuoi che l'azione venga applicata a più datastore, crea un controllo per ogni datastore.

      2. Aggiungi un filtro.

        Si tratta di una stringa che specifica i requisiti che devono essere soddisfatti dal documento. La condizione di incremento viene applicata solo se il documento soddisfa tutti i requisiti. In caso contrario, non viene apportata alcuna modifica. Se non specifichi filtri, l'incremento viene applicato a tutti i documenti nell&#39datastorei.

        Per capire come scrivere le espressioni di filtro, consulta Sintassi delle espressioni di filtro ed Esempi di espressioni di filtro.

      3. Seleziona un valore di aumento/riduzione nell'intervallo [-1, 1] utilizzando il cursore. Il cursore si sposta a incrementi di 0,01.

      4. Fai clic su Continua.

    4. Se vuoi applicare il controllo non appena viene creato, attiva Pubblica questo controllo immediatamente e fai clic su Continua.

  6. Fai clic su Invia.

  7. Per modificare la configurazione di un controllo:

    1. Nella pagina Segnale, nell'elenco dei controlli di aumento/riduzione della visibilità dell'app, fai clic su per un controllo che vuoi modificare e fai clic su Modifica.

    2. Modifica il controllo nel riquadro Modifica controllo.

  8. Per attivare o disattivare un controllo, nella pagina Segnale, nell'elenco dei controlli di aumento/riduzione della visibilità dell'app, fai clic su per un controllo che vuoi attivare o disattivare e fai clic su Attiva o Disattiva, a seconda dei casi.

  9. Per eliminare un controllo, nella pagina Indicatore, nell'elenco dei controlli di aumento/riduzione dell'app, fai clic su per un controllo che vuoi eliminare e fai clic su Elimina.

REST

Un controllo di pubblicazione con boost è definito come un controllo con un boostAction.

Utilizza le seguenti istruzioni per creare un controllo di pubblicazione del boost.

Per i dettagli sui campi, consulta il riferimento API engines.controls e il riferimento API engines.controls.create.

  1. 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 della tua app e recupera il relativo ID dalla colonna ID.

  2. Esegui i seguenti comandi curl per creare i controlli.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": [
  "USE_CASE"
],
"conditions": {
 "queryTerms": [
   {
     "value": "VALUE",
     "fullMatch": FULL_MATCH
   }
 ],
 "activeTimeRange": [
   {
     "startTime": "START_TIMESTAMP",
     "endTime": "END_TIMESTAMP"
   }
 ]
},
"boostAction": {
  "boost": BOOST_VALUE,
  "filter": "FILTER",
  "dataStore": "DATA_STORE_RESOURCE_PATH"
 }
}'

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo Google Cloud progetto.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere da 1 a 63 caratteri che possono essere lettere, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di scegliere un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128 caratteri.
    • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, non è possibile utilizzare Condition.queryTerms nella condizione.
    • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore specifico della query da confrontare. È una stringa UTF-8 minuscola di lunghezza [1, 5000]. Se FULL_MATCH_1 è true, questo campo può contenere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine della query. Se impostato su true, SearchRequest.query deve corrispondere esattamente a queryTerm.value. Se impostato su false, richiede che SearchRequest.query contenga queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • BOOST_VALUE: un numero in virgola mobile nell'intervallo [-1,1]. Quando il valore è negativo, i risultati vengono declassati (vengono visualizzati più in basso nei risultati). Quando il valore è positivo, i risultati vengono promossi (vengono visualizzati più in alto nei risultati). Per ulteriori informazioni, vedi boostAction.
    • FILTER: una stringa che specifica i requisiti che devono essere soddisfatti dal documento. Se il documento soddisfa tutti i requisiti, viene applicato il boost. In caso contrario, non viene apportata alcuna modifica. Se questo campo è vuoto, il boost viene applicato a tutti i documenti nel datastore. Per la sintassi di filtro, consulta Sintassi delle espressioni di filtro. Nota: il campo del documento title non può essere filtrato.
    • DATA_STORE_RESOURCE_PATH: il percorso completo della risorsa del datastore i cui documenti devono essere potenziati da questo controllo. Il formato del percorso completo della risorsa è projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Questo datastore deve essere collegato al motore specificato nella richiesta.

  3. Collega il controllo alla configurazione di gestione dell'app utilizzando il metodo engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
-d '{
 "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2"]
}'

    Sostituisci BOOST_ID_N con gli ID controllo che hai creato nel passaggio precedente.

Creare e collegare i controlli di pubblicazione dei filtri

Un controllo di pubblicazione dei filtri è definito come un controllo con un filterAction.

Utilizza le seguenti istruzioni per creare un controllo della pubblicazione dei filtri.

Per i dettagli sui campi, consulta il riferimento API engines.controls e il riferimento API engines.controls.create.

  1. 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 della tua app e recupera il relativo ID dalla colonna ID.

  2. Esegui i seguenti comandi curl per creare i controlli.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"filterAction": {
  "filter": "FILTER"
 }
}'

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo Google Cloud progetto.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere da 1 a 63 caratteri che possono essere lettere, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di scegliere un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128 caratteri.
    • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, non è possibile utilizzare Condition.queryTerms nella condizione.
    • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore specifico della query da confrontare. È una stringa UTF-8 minuscola di lunghezza [1, 5000]. Se FULL_MATCH_1 è true, questo campo può contenere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine della query. Se impostato su true, SearchRequest.query deve corrispondere esattamente a queryTerm.value. Se impostato su false, richiede che SearchRequest.query contenga queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • FILTER: una stringa che specifica i requisiti che devono essere soddisfatti dal documento. Se il documento soddisfa tutti i requisiti, viene restituito nei risultati. In caso contrario, il documento non viene visualizzato nei risultati. Per la sintassi di filtro, consulta Sintassi delle espressioni di filtro. Per ulteriori informazioni, vedi filterAction. Nota: il campo del documento title non può essere filtrato.

  3. Collega il controllo alla configurazione di gestione dell'app utilizzando il metodo engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
-d '{
  "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2"]
}'

    Sostituisci FILTER_ID_N con gli ID controllo che hai creato nel passaggio precedente.

Creare e collegare controlli di pubblicazione dei sinonimi

Un controllo di pubblicazione dei sinonimi è definito come un controllo con un synonymsAction.

Segui queste istruzioni per creare un controllo di pubblicazione dei sinonimi.

Per i dettagli sui campi, consulta il riferimento API engines.controls e il riferimento API engines.controls.create.

  1. 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 della tua app e recupera il relativo ID dalla colonna ID.

  2. Esegui i seguenti comandi curl per creare i controlli.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"synonymsAction": {
  "synonyms": ["SYNONYMS_1","SYNONYMS_2"]
 }
}'

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo Google Cloud progetto.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere da 1 a 63 caratteri che possono essere lettere, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di scegliere un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128 caratteri.
    • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, non è possibile utilizzare Condition.queryTerms nella condizione.
    • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore specifico della query da confrontare. È una stringa UTF-8 minuscola di lunghezza [1, 5000]. Se FULL_MATCH_1 è true, questo campo può contenere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine della query. Se impostato su true, SearchRequest.query deve corrispondere esattamente a queryTerm.value. Se impostato su false, richiede che SearchRequest.query contenga queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • SYNONYMS_N: un elenco di stringhe associate tra loro, il che aumenta la probabilità che ciascuna mostri risultati simili. Anche se è più probabile che tu ottenga risultati simili, quando cerchi ciascuna delle voci di sinonimi, potresti non ricevere tutti i risultati pertinenti per tutti i sinonimi associati. Devi specificare almeno due sinonimi e puoi specificarne fino a 100. Ogni sinonimo deve essere codificato in UTF-8 e in minuscolo. Non sono consentite stringhe duplicate. Ad esempio, puoi aggiungere "pixel", "smartphone Android" e "smartphone Google" come sinonimi. Per ulteriori informazioni, vedi synonymsAction.

  3. Collega il controllo alla configurazione di gestione dell'app utilizzando il metodo engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
-d '{
  "synonymsControlIds": ["SYNONYMS_ID_1", "SYNONYMS_ID_2"]
}'

    Sostituisci SYNONYMS_ID_N con gli ID controllo che hai creato nel passaggio precedente.

Creare e collegare i controlli di gestione dei reindirizzamenti

Un controllo di pubblicazione del reindirizzamento consente di reindirizzare gli utenti a un URI fornito. I controlli di reindirizzamento sono definiti come un controllo con un redirectAction.

Segui queste istruzioni per creare un controllo di pubblicazione del reindirizzamento.

Per i dettagli sui campi, consulta il riferimento API engines.controls e il riferimento API engines.controls.create.

  1. 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 della tua app e recupera il relativo ID dalla colonna ID.

  2. Esegui i seguenti comandi curl per creare i controlli.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": FULL_MATCH
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ]
},
"redirectAction": {
  "redirectURI": "REDIRECT_URI"
 }
}'

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo Google Cloud progetto.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere da 1 a 63 caratteri che possono essere lettere, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di scegliere un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128 caratteri.
    • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, non è possibile utilizzare Condition.queryTerms nella condizione.
    • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore specifico della query da confrontare. È una stringa UTF-8 minuscola di lunghezza [1, 5000]. Se FULL_MATCH_1 è true, questo campo può contenere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine della query. Se impostato su true, SearchRequest.query deve corrispondere esattamente a queryTerm.value. Se impostato su false, richiede che SearchRequest.query contenga queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • REDIRECT_URI_N: un URI a cui viene eseguito il reindirizzamento. Può avere una lunghezza massima di 2000 caratteri. Ad esempio, se il valore del termine di query è "assistenza", puoi impostare un reindirizzamento alla pagina di assistenza tecnica anziché restituire (o non restituire) risultati di ricerca per "assistenza". In questo esempio, l'URI di reindirizzamento diventa "https://www.example.com/support". Per ulteriori informazioni, vedi redirectAction.

  3. Collega il controllo alla configurazione di gestione dell'app utilizzando il metodo engines.servingConfigs.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
-d '{
  "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2"]
}'

    Sostituisci REDIRECT_ID_N con gli ID controllo che hai creato nel passaggio precedente.

Creare e allegare controlli di pubblicazione della promozione

Un controllo di pubblicazione della promozione consente di visualizzare un link come risultato promozionale ed è disponibile per i seguenti tipi di datastore di ricerca:

  • Datastore di siti web con ricerca di base: per questi datastore, non è necessario collegare un controllo di promozione alla configurazione di pubblicazione dell'app. La creazione e l'attivazione di un controllo di promozione attiva il controllo di promozione. Puoi attivare o disattivare un controllo di promozione abilitandolo o disabilitandolo.

  • Datastore con dati strutturati e non strutturati, dati del sito web con indicizzazione avanzata dei siti web e app di ricerca combinate: per questi datastore, devi collegare il controllo di promozione alla configurazione di pubblicazione.

I controlli di promozione vengono definiti utilizzando un promoteAction.

Per creare correttamente un controllo di promozione, è necessario uno dei seguenti campi nella richiesta di creazione:

  • queryTerms: questa condizione non può essere specificata se stai specificando la condizione queryRegex, che è applicabile solo alla ricerca di base sui siti web. Per la ricerca di base sul sito web, fullMatch deve essere impostato su true se queryTerms è specificato. Per tutte le altre app di ricerca, sono supportati solo queryTerms e fullMatch può essere impostato su true o false.
  • queryRegex. Disponibile solo per un controllo della pubblicazione della promozione solo per la ricerca di base sui siti web. Questa condizione applica il controllo quando la query corrisponde all'espressione regolare specificata. Questa condizione non può essere specificata se stai specificando la condizione queryTerms.

ovvero, per la ricerca di base di siti web, devi specificare il campo queryTerms con fullMatch impostato su true o specificare il campo queryRegex. Per tutti gli altri tipi di ricerca, specifica il campo queryTerms con fullMatch impostato su true o false.

Per creare un controllo di pubblicazione della promozione, segui queste istruzioni.

Per i dettagli sui campi, consulta il riferimento API engines.controls e il riferimento API engines.controls.create.

  1. 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 della tua app e recupera il relativo ID dalla colonna ID.

  2. Esegui i seguenti comandi curl per creare i controlli.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
"displayName": "DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"useCases": ["USE_CASE"],
"conditions": {
  "queryTerms": [
    {
      "value": "VALUE",
      "fullMatch": true
    }
  ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP",
      "endTime": "END_TIMESTAMP"
    }
  ],
  "queryRegex": "VALUE_REGEX"
},
"promoteAction": {
  "dataStore": "DATA_STORE_RESOURCE_PATH",
  "searchLinkPromotion": {
     "document": "DOCUMENT_RESOURCE_PATH",
     "title": "TITLE",
     "uri": "URI",
     "description": "DESCRIPTION",
     "enabled": ENABLED_TRUE|FALSE,
  }
 }
}'

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo Google Cloud progetto.
    • APP_ID: l'ID dell'app Vertex AI Search.
    • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere da 1 a 63 caratteri che possono essere lettere, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di scegliere un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128 caratteri.
    • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, non è possibile utilizzare Condition.queryTerms nella condizione.
    • Condition: un oggetto facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • queryTerms: non può essere utilizzato con il campo queryRegex.
        • VALUE: il valore specifico della query da confrontare. È una stringa UTF-8 minuscola di lunghezza [1, 5000].
      • activeTimeRange:
        • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
        • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
      • queryRegex: disponibile solo per gli archivi di dati con ricerca di base del sito web. Questo campo non può essere utilizzato con il campo queryTerms.
        • VALUE_REGEX: un'espressione regolare con cui confrontare la query.
    • DATA_STORE_RESOURCE_PATH: il percorso completo della risorsa del datastore i cui risultati di ricerca contengono l'URL promosso. Il formato del percorso completo della risorsa è projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Questo datastore deve essere collegato al motore specificato nella richiesta.
    • DOCUMENT_RESOURCE_PATH: un campo per specificare il percorso della risorsa del documento da promuovere:
      • Per i datastore di ricerca con dati strutturati e non strutturati, devi fornire il percorso della risorsa del documento nel campo DOCUMENT_RESOURCE_PATH, l'URI nel campo URI o entrambi. Il formato del percorso completo della risorsa è projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID/branches/0/documents/DOCUMENT_ID.
      • Per i datastore del sito web, questo campo deve essere annullato e impostato il campo URI invece.
    • TITLE: un campo obbligatorio per specificare il titolo del documento o della pagina web da promuovere. Questo titolo viene visualizzato nel risultato di ricerca.
    • URI: un campo obbligatorio per specificare il link URI a cui il risultato di ricerca indirizza l'utente. Questo URI non deve essere incluso nel datastore.
      • Per i datastore di ricerca con dati strutturati e non strutturati, devi fornire il percorso della risorsa del documento nel campo DOCUMENT_RESOURCE_PATH, l'URI nel campo URI o entrambi.
      • Per i datastore di siti web, questo è un campo obbligatorio e devi impostarlo.
    • DESCRIPTION: un campo facoltativo per descrivere il documento o la pagina web da promuovere, che viene visualizzato nel risultato di ricerca.
    • ENABLED_TRUE|FALSE: un campo booleano facoltativo per indicare se il controllo di promozione è attivato e collegato all'app. Questo campo è applicabile solo ai datastore di siti web con ricerca di base sul sito web. Se imposti questo campo su false, il controllo di pubblicazione della promozione viene disattivato e, affinché il controllo abbia effetto, devi aggiornarlo attivandolo, come spiegato nel passaggio successivo. Per ulteriori informazioni, vedi promoteAction.

  3. Per tutte le app di ricerca, ad eccezione della ricerca di base sui siti web, collega il controllo alla configurazione di gestione dell'app utilizzando il metodo engines.servingConfigs.patch. L'ordine in cui vengono allegati i promoteControlIds nella seguente richiesta è l'ordine in cui vengono restituiti i risultati promossi.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search?update_mask=promote_control_ids" \
-d '{
  "promoteControlIds": ["PROMOTE_ID_1", "PROMOTE_ID_2"]
}'

    Sostituisci PROMOTE_ID_N con gli ID controllo che hai creato nel passaggio precedente.

  4. (Facoltativo) Per la ricerca di base sul sito web, non è necessario collegare il controllo alla configurazione di pubblicazione dell'app. Tuttavia, per la ricerca di base sui siti web puoi attivare o disattivare un controllo di promozione dopo la creazione chiamando il metodo engines.control.patch.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls/CONTROL_ID?updateMask=promoteAction.searchLinkPromotion.enabled" \
-d '{
"promoteAction": {
  "searchLinkPromotion": {
     "enabled": ENABLED_TRUE|FALSE,
  }
}
}'

Esempio

Quando invii una richiesta di ricerca all'app con una query che corrisponde alla query o all'espressione regolare della query specificata per il controllo di promozione, il link promozionale viene visualizzato nella risposta.

Ad esempio, supponi di creare un controllo di promozione con la seguente configurazione in un datastore con la ricerca di base sul sito web:

{
 "conditions": [
   {
     "queryTerms": [
       {
         "value": "artificial intelligence",
         "fullMatch": true
       }
     ]
   }
 ]"
 ...
 promoteAction": {
  "dataStore": "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/dataStores/basic-website-data-store" \
  "searchLinkPromotion": {
    "title": "What is AI?",
    "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
    "description": "Explain what is AI"
    "enabled": true
  }
 }
}

Poi invii la seguente richiesta di ricerca:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/123456/locations/us/collections/default_collection/engines/basic-website-app/servingConfigs/default_search:search" \
  -d '{
"query": "artificial intelligence"
}'

Dovresti ricevere una risposta JSON simile alla seguente risposta troncata. La risposta contiene il campo searchLinkPromotions che contiene il link promosso.

{
 "results": [...],
  "totalSize": 3,
  "attributionToken": "_gHw_QoMCMSbhboGELuI1qwCEiQ2NzQwYmYzYi0wMDAwLTJmYTctYTk1OC0yNDA1ODg4MzZmYjgiB0dFTkVSSUMqvAGrxIotzua1L5neqC_n7YgtxPzLMIOymiK0kq4wxPi8MPn2sy3LmrQw6d3EMNSynRWc1rctnN3YMOuCsS3ogrEto4CXIsLwnhX89rMtkKS0MJbeqC-jibMtkPeyMMTGsTCZ3dgw5O2ILa7Eii2NpLQw5t3EMN6PmiKOvp0VwfzLMICymiKq-LMt0ea1L634sy3Fy_MXtreMLbeSrjDHxrEwzpq0MMH4vDCgibMtn9a3LZSSxTCOkckw24-aIjAB",
  "guidedSearchResult": {},
  "summary": {},
  "searchLinkPromotions": [
    {
      "title": "What is AI?",
      "uri": "https://cloud.google.com/learn/what-is-artificial-intelligence",
      "description": "Explain what is AI"
    }
  ]
}

Passaggi successivi

  • Per comprendere l'impatto di un controllo della pubblicazione sulla qualità della ricerca di un'app di ricerca personalizzata, valuta la qualità della ricerca. Per maggiori informazioni, vedi Valutare la qualità della ricerca.