Configurare i controlli di pubblicazione per la rete di ricerca

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

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 dei contenuti multimediali.

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 quelli di miglioramento, hanno dipendenze dagli store di dati. Se un datastore viene rimosso da un'app, tutti i controlli dipendenti 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:

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 condizione sono disponibili:

• 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 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, non è possibile specificare queryTerms se hai specificato la condizione queryRegex, che è applicabile solo alla ricerca di base sul sito web. Inoltre, il campo fullMatch per la ricerca di base sul sito web deve essere impostato su true se è specificato queryTerms. 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 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 solo per la ricerca di base sul sito 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 hai specificato 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 SearchRequest.query="gBoot", ma non 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 nella documentazione di riferimento dell'API.

Crea e allega i controlli di pubblicazione con boost

Un controllo di pubblicazione con potenziamento riordina i risultati promuovendoli o riducendone la visibilità in base alle condizioni applicate. Il potenziamento funziona applicando un fattore di moltiplicazione al ranking di un documento che soddisfa le condizioni di potenziamento.

Per creare e collegare il controllo dell'aumento:

Creare e allegare 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 Google Cloud console, vai alla pagina AI Applications.

      Vai ad App

   2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app 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 [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 di lunghezza [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.

Crea e allega 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 Google Cloud console, vai alla pagina AI Applications.

      Vai ad App

   2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app 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 [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 di lunghezza [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 Google Cloud console, vai alla pagina AI Applications.

      Vai ad App

   2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app 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 [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 di lunghezza [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 della promozione ti consente di visualizzare un link come risultato promosso ed è disponibile per i seguenti tipi di datastore di dati di ricerca:

• Data store dei siti web con ricerca di base sul sito web: 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 attivano il controllo di promozione. Puoi attivare o disattivare un controllo di promozione attivandolo o disattivandolo.

• Data store con dati strutturati e non strutturati, dati del sito web con indicizzazione avanzata del sito 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, nella richiesta di creazione è obbligatorio uno dei seguenti campi:

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

In altre parole, per la ricerca di base sul sito web, devi specificare il campo queryTerms con fullMatch impostato su true o il campo queryRegex. Per tutti gli altri tipi di ricerca, specifica il campo queryTerms con fullMatch impostato su true o false.

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 Google Cloud console, vai alla pagina AI Applications.

      Vai ad App

   2. Nella pagina App, trova il nome della tua app e recupera l'ID dall'app 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 [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 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 la ricerca di base sul sito web. Questo campo non può essere utilizzato con il campo queryTerms.
       • VALUE_REGEX: un'espressione regolare a cui fare corrispondere la query.
   • 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.
   • DOCUMENT_RESOURCE_PATH: un campo per specificare il percorso della risorsa del documento 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 dei siti web, questo campo deve essere deselezionato e deve essere impostato il campo URI.
   • 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 all'URI a cui indirizza l'utente il risultato di ricerca. 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 dei siti web, si tratta di un campo obbligatorio che devi impostare.
   • DESCRIPTION: un campo facoltativo per descrivere il documento o la pagina web da promuovere, visualizzato nel risultato di ricerca.
   • ENABLED_TRUE|FALSE: un campo booleano facoltativo per indicare se il controllo della promozione è attivato e collegato all'app. Questo campo è applicabile ai datastore dei siti web solo con ricerca di siti web di base. Quando imposti questo campo su false, il controllo della pubblicazione in primo piano 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. Per tutte le app di ricerca, ad eccezione della ricerca di siti web di base, collega il controllo alla configurazione di pubblicazione dell'app utilizzando il metodo engines.servingConfigs.patch. L'ordine in cui i parametri promoteControlIds sono allegati nella richiesta seguente è 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 del sito web puoi attivare o disattivare un controllo di promozione dopo averlo creato, 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 promosso viene visualizzato nella risposta.

Ad esempio, supponiamo di creare un controllo di promozione con la seguente configurazione in un datastore con 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, invia 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.