Configurare i controlli di pubblicazione per la rete di ricerca

I controlli di pubblicazione (chiamati anche controlli) modificano il comportamento predefinito della modalità di pubblicazione di una richiesta quando vengono restituiti i risultati. I controlli di pubblicazione agiscono a livello di data store.

Ad esempio, i controlli possono aumentare e nascondere i risultati, filtrare le voci tra i risultati restituiti, associare le 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 consigli sui contenuti multimediali, consulta Creare e gestire le configurazioni di pubblicazione.

Informazioni sui controlli di pubblicazione

Per modificare i risultati di una richiesta, devi prima creare un controllo della pubblicazione. Quindi, associa questo controllo alla configurazione di pubblicazione di un'app di ricerca. Una configurazione di pubblicazione configura i metadati utilizzati per generare risultati relativi al momento della pubblicazione, ad esempio risultati di ricerca o risposte. Un controllo di pubblicazione influisce sulle richieste pubblicate dall'app solo se il controllo è collegato alla configurazione di pubblicazione dell'app.

Alcuni controlli, come i controlli di miglioramento, hanno dipendenze dagli store di dati. Se un datastore viene rimosso da un'app, tutti i controlli dipendenti dal datastore vengono anche 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 restituito dei risultati	App di ricerca con datastore che supportano uno schema, ad esempio datastore contenenti 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 contenenti dati strutturati, siti web (indicizzazione avanzata dei siti web e ricerca di siti web di base), dati non strutturati con metadati o dati multimediali
Controllo dei sinonimi	Associa le query tra loro	App di ricerca con siti web (indicizzazione avanzata dei siti web), datastore strutturati, non strutturati o di contenuti multimediali
Controllo dei reindirizzamenti	Reindirizza a un URI specificato	Tutte le app di ricerca
Promuovere il controllo	Promuove un link specificato per una query	Solo app di ricerca di base sui siti web

Informazioni sulle condizioni

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

• 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 query possono essere utilizzati solo quando Control.searchUseCase è impostato su SOLUTION_TYPE_SEARCH. In un singolo Control.condition è possibile specificare fino a 10 diversi queryTerms. Se non vengono specificati termini di query, il campo queryTerms viene ignorato.

  Per un controllo della pubblicazione delle promozioni, si applicano questi vincoli aggiuntivi:

  • Non è possibile specificare la condizione queryTerms se hai specificato la condizione queryRegex
  • fullMatch deve essere impostato su true

• activeTimeRange. Un controllo facoltativo che viene applicato quando una richiesta avviene in un intervallo di tempo specificato. Controlla che l'ora di ricezione di una richiesta sia compresa tra activeTimeRange.startTime e activeTimeRange.endTime. In un singolo Control.condition è possibile specificare fino a 10 intervalli activeTimeRange. Se il campoactiveTimeRange non è specificato, viene ignorato.

• queryRegex. Disponibile solo per un controllo di promozione della pubblicazione, una condizione facoltativa che applica il controllo quando la query corrisponde all'espressione regolare specificata. Questa condizione non può essere specificata se specifichi la condizione queryTerms.

Se per un controllo vengono specificate più condizioni, il controllo viene applicato alla richiesta di ricerca quando entrambi i tipi di condizione sono soddisfatti. Se vengono specificati più valori per la stessa condizione, è sufficiente che uno solo dei valori corrisponda per soddisfare la condizione.

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

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

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

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

Per ulteriori informazioni, consulta il campo Condition nella documentazione di riferimento dell'API.

Creare e collegare i controlli di pubblicazione con incremento

Un controllo della pubblicazione con incremento è definito come un controllo con un boostAction.

Segui le istruzioni riportate di seguito per creare un controllo di pubblicazione con incremento.

Per i dettagli dei campi, consulta il riferimento all'API engines.controls e il riferimento all'API engines.controls.create.

1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

   1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Vai ad App

   2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app la 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 progetto Google Cloud.
   • APP_ID: l'ID dell'app Vertex AI Search.
   • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere [1-63] caratteri che possono essere lettere, cifre, trattini e trattini bassi.
   • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di fornire un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128.
   • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, Condition.queryTerms non può essere utilizzato nella condizione.
   • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
     • VALUE: il valore specifico della query con cui eseguire la corrispondenza. Si tratta di una stringa UTF-8 minuscola con una lunghezza pari a [1, 5000]. Se FULL_MATCH_1 è true, questo campo può avere al massimo tre termini separati da spazi.
     • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di query. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede SearchRequest.query di contenere 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 a virgola mobile nell'intervallo [-1,1]. Quando il valore è negativo, i risultati vengono retrocessi (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, consulta boostAction.
   • FILTER: una stringa che specifica i requisiti che devono essere soddisfatti dal documento. Se il documento soddisfa tutti i requisiti, viene applicato il potenziamento. In caso contrario, non viene apportata alcuna modifica. Se questo campo è vuoto, l'aumento viene applicato a tutti i documenti nello datastore. Per la sintassi di filtro, consulta Sintassi dell'espressione di filtro. Nota: non è possibile filtrare il campo del documento title.
   • DATA_STORE_RESOURCE_PATH: il percorso completo della risorsa del datastore i cui documenti devono essere migliorati 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 pubblicazione 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.

Crea e allega i controlli di pubblicazione dei filtri

Un controllo di pubblicazione del filtro è definito come un controllo con un filterAction.

Segui le istruzioni riportate di seguito per creare un controllo di pubblicazione dei filtri.

Per i dettagli dei campi, consulta il riferimento all'API engines.controls e il riferimento all'API engines.controls.create.

1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

   1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Vai ad App

   2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app la 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 progetto Google Cloud.
   • APP_ID: l'ID dell'app Vertex AI Search.
   • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere [1-63] caratteri che possono essere lettere, cifre, trattini e trattini bassi.
   • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di fornire un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128.
   • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, Condition.queryTerms non può essere utilizzato nella condizione.
   • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
     • VALUE: il valore specifico della query con cui eseguire la corrispondenza. Si tratta di una stringa UTF-8 minuscola con una lunghezza pari a [1, 5000]. Se FULL_MATCH_1 è true, questo campo può avere al massimo tre termini separati da spazi.
     • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di query. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede SearchRequest.query di contenere 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 visualizzato nei risultati. In caso contrario, il documento non è presente nei risultati. Per la sintassi di filtro, consulta Sintassi dell'espressione di filtro. Per ulteriori informazioni, vedi filterAction. Nota: non è possibile filtrare il campo del documento title.

3. Collega il controllo alla configurazione di pubblicazione 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 associare controlli di pubblicazione di sinonimi

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

Segui le istruzioni riportate di seguito per creare un controllo della pubblicazione di sinonimi.

Per i dettagli dei campi, consulta il riferimento all'API engines.controls e il riferimento all'API engines.controls.create.

1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

   1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Vai ad App

   2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app la 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 progetto Google Cloud.
   • APP_ID: l'ID dell'app Vertex AI Search.
   • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere [1-63] caratteri che possono essere lettere, cifre, trattini e trattini bassi.
   • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di fornire un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128.
   • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, Condition.queryTerms non può essere utilizzato nella condizione.
   • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
     • VALUE: il valore specifico della query con cui eseguire la corrispondenza. Si tratta di una stringa UTF-8 minuscola con una lunghezza pari a [1, 5000]. Se FULL_MATCH_1 è true, questo campo può avere al massimo tre termini separati da spazi.
     • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di query. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede SearchRequest.query di contenere 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, che aumenta la probabilità che ciascuna mostri risultati simili. Sebbene sia più probabile che tu ottenga risultati simili, quando cerchi ciascuna delle voci dei 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 pubblicazione 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.

Crea e collega i controlli di pubblicazione dei reindirizzamenti

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

Segui le istruzioni riportate di seguito per creare un controllo di pubblicazione con reindirizzamento.

Per i dettagli dei campi, consulta il riferimento all'API engines.controls e il riferimento all'API engines.controls.create.

1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

   1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Vai ad App

   2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app la 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 progetto Google Cloud.
   • APP_ID: l'ID dell'app Vertex AI Search.
   • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere [1-63] caratteri che possono essere lettere, cifre, trattini e trattini bassi.
   • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di fornire un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128.
   • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, Condition.queryTerms non può essere utilizzato nella condizione.
   • CONDITION: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
     • VALUE: il valore specifico della query con cui eseguire la corrispondenza. Si tratta di una stringa UTF-8 minuscola con una lunghezza pari a [1, 5000]. Se FULL_MATCH_1 è true, questo campo può avere al massimo tre termini separati da spazi.
     • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di query. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede SearchRequest.query di contenere 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 dell'assistenza tecnica anziché restituire (o non restituire) i 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 pubblicazione 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.

Crea e allega i controlli di pubblicazione delle promozioni

Un controllo di pubblicazione di annunci promossi ti consente di mostrare un link come risultato promosso. Questo controllo è disponibile solo per i datastore dei siti web con ricerca di base sul sito web.

A differenza di altri controlli di pubblicazione, non è necessario collegare un controllo di promozione alla configurazione di pubblicazione dell'app. La creazione e l'attivazione di un controllo di promozione per un'app attivano il controllo di promozione. Inoltre, a differenza di altri controlli di pubblicazione, puoi attivare o disattivare un controllo delle promozioni abilitandolo o disattivandolo.

I controlli di promozione vengono definiti utilizzando un promoteAction.

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

• Il campo queryTerms con fullMatch impostato su true
• Il campo queryRegex

Segui le istruzioni riportate di seguito per creare un controllo di pubblicazione della promozione.

Per i dettagli dei campi, consulta il riferimento all'API engines.controls e il riferimento all'API engines.controls.create.

1. Trova l'ID app. Se hai già l'ID app, vai al passaggio successivo.

   1. Nella console Google Cloud, vai alla pagina Agent Builder.

      Vai ad App

   2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app la 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": {
        "title": "URI_TITLE",
        "uri": "URI",
        "description": "URI_DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE,
     }
    }
   }'

   Sostituisci quanto segue:

   • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud.
   • APP_ID: l'ID dell'app Vertex AI Search.
   • CONTROL_ID: un identificatore univoco per il controllo. L'ID può contenere [1-63] caratteri che possono essere lettere, cifre, trattini e trattini bassi.
   • DISPLAY_NAME: il nome leggibile del controllo. Google consiglia di fornire un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa codificata in UTF-8 con una lunghezza compresa tra 1 e 128.
   • USE_CASE: deve essere SEARCH_USE_CASE_SEARCH o SEARCH_USE_CASE_BROWSE. Se viene specificato SEARCH_USE_CASE_BROWSE, Condition.queryTerms non può essere utilizzato 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 con cui eseguire la corrispondenza. Si tratta di una stringa UTF-8 minuscola con una lunghezza pari a [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: non può essere utilizzato con il campo queryTerms.
       • VALUE_REGEX: un'espressione regolare a cui fare corrispondere la query. Questa opzione è disponibile solo per il controllo della pubblicazione di annunci.
   • DATA_STORE_RESOURCE_PATH: il percorso completo della risorsa dell'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.
   • URI_TITLE: un campo obbligatorio per specificare il titolo dell'URI, visualizzato nel risultato di ricerca.
   • URI: un campo obbligatorio per specificare il link all'URI a cui indirizza l'utente il risultato di ricerca. Questo URI non deve essere incluso nel datastore.
   • URI_DESCRIPTION: un campo facoltativo per descrivere l'URI, visualizzato nel risultato di ricerca.
   • ENABLED_TRUE|FALSE: un campo booleano facoltativo per indicare se il controllo di promozione è attivato e collegato all'app. Quando imposti questo campo su false, il controllo della pubblicazione di promozioni viene disattivato e, affinché venga applicato, devi aggiornarlo attivandolo, come spiegato nel passaggio successivo. Per ulteriori informazioni, vedi promoteAction.

   Risposta

   Dovresti ricevere una risposta JSON simile alla seguente:

   {
    "name": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/engines/APP_ID/controls/PROMOTE_CONTROL_ID",
    "displayName": "PROMOTE_CONTROL_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "conditions": [
      {
        "queryTerms": [
          {
            "value": "VALUE",
            "fullMatch": true
          }
        ]
      }
    ],
    "useCases": [
      "SEARCH_USE_CASE_SEARCH"
    ],
    "promoteAction": {
      "dataStore": "projects/PROJECT_NUMBER/locations/global/collections/default_collection/dataStores/DATA_STORE_ID",
      "searchLinkPromotion": {
        "title": "URI_TITLE",
        "uri": "URI",
        "description": "URI_DESCRIPTION",
        "enabled": ENABLED_TRUE|FALSE
     }
    }
   }
   

3. (Facoltativo) Per attivare o disattivare un controllo di promozione dopo la sua creazione, chiama 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 promosso viene visualizzato nella risposta.

Ad esempio, supponiamo di creare un controllo di promozione con la seguente configurazione:

{
 "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 generica, valuta la qualità della ricerca. Per ulteriori informazioni, consulta Valutare la qualità della ricerca.