Configurare i controlli di pubblicazione per la rete di ricerca

I controlli di pubblicazione (chiamati anche controlli) modificano il comportamento predefinito di una richiesta.

Ad esempio, i controlli possono migliorare e nascondere i risultati, filtrare le voci tra i risultati restituiti, associare le query tra loro come sinonimi o reindirizzare le query 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, crea prima un controllo della pubblicazione. Quindi, collegalo a un'app. Un controllo influisce solo sulle richieste gestite da un'app a cui è collegato. Se un controllo non è associato a un'app, non ha alcun effetto.

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 dall'insieme di datastore vengono rimossi dall'app e diventano inattivi, ma non vengono eliminati.

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:

  • queryTerms. Il controllo viene applicato quando vengono cercate query specifiche.
  • activeTimeRange. Il controllo viene applicato quando viene effettuata una richiesta in un intervallo di tempo specificato.

Se per un controllo sono specificati entrambi i tipi di 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, è 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 servingConfigs.search nel riferimento all'API.

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, 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 con dati strutturati, dati non strutturati con metadati o dati multimediali
Controllo dei sinonimi Associa le query tra loro App di ricerca con datastore di siti web, strutturati, non strutturati o di contenuti multimediali
Controllo dei reindirizzamenti Reindirizza a un URI specificato Tutte le app di ricerca

Informazioni sui controlli di pubblicazione della funzionalità Boost

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

La sintassi di un boostAction è la seguente:

{
    "boost": "BOOST",
    "filter": "FILTER",
    "dataStore": "DATA_STORE_RESOURCE_PATH"
}
  • BOOST: un valore compreso tra -1 e 1. Quando il valore è negativo, i risultati vengono retrocessi e visualizzati più in basso nei risultati di ricerca. Quando il valore è positivo, i risultati vengono promossi in modo da apparire prima nei risultati di ricerca.
  • FILTER: una stringa che specifica i requisiti che devono essere soddisfatti dal documento. Se il documento soddisfa tutti i requisiti, il miglioramento viene applicato. In caso contrario, non viene apportata alcuna modifica. Se questo campo è vuoto, l'aumento viene applicato a tutti i documenti nel datastore. Per la sintassi di filtro, consulta Sintassi expression filter.
  • 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_ID/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Questo datastore deve essere collegato al motore specificato nella richiesta.

Informazioni sui controlli di pubblicazione dei filtri

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

La sintassi di un filterAction è la seguente:

{
    "filter": "FILTER"
}
  • FILTER: una stringa che specifica i requisiti che devono essere soddisfatti dal documento. Se il documento soddisfa tutti i requisiti, il risultato viene incluso nell'elenco dei risultati. In caso contrario, il risultato viene rimosso dall'elenco. Per la sintassi di filtro, consulta Sintassi dell'espressione di filtro.

Informazioni sui controlli di pubblicazione dei sinonimi

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

La sintassi di un synonymsAction è la seguente:

{
    "synonyms": "SYNONYMS"
}
  • SYNONYMS: stringhe che verranno associate tra loro, aumentando la probabilità che ciascuna mostri risultati simili. Devi specificare almeno due stringhe e puoi specificarne fino a 100. Le stringhe devono essere UTF-8 e in minuscolo. Non sono consentite stringhe duplicate.

Ad esempio:

{
    "synonyms": ["pixel", "android phone", "google phone"]
}

Informazioni sui controlli della 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.

Sintassi per redirectAction:

{
    "redirect_uri": "REDIRECT_URI"
}
  • REDIRECT_URI: un URI di massimo 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".

{
    "redirect_uri": ["https://www.example.com/support"]
}

Informazioni sulla condizione queryTerms

Il valore queryTerms è facoltativo. Utilizzalo se vuoi che venga utilizzato un controllo di pubblicazione 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 queryTerms diversi. Se non vengono specificati termini di query, il campo viene ignorato.

La sintassi di un singolo queryTerm è la seguente:

{
    "value": "VALUE_1",
    "fullMatch": "FULL_MATCH_1"
}
  • VALUE_1: una stringa UTF-8 in minuscolo di lunghezza [1, 5000]. Se FULL_MATCH_1 è true, può avere al massimo tre termini separati da spazi.
  • FULL_MATCH_1: un valore booleano. Se impostato su true, richiede SearchRequest.query per corrispondere completamente a queryTerm.value. Se impostato su false, richiede che SearchRequest.query contenga queryTerm.value come sottostringa.

Informazioni sulla condizione activeTimeRange

Il valore activeTimeRange è facoltativo. Verifica che l'ora di ricezione di una richiesta sia tra activeTimeRange.startTime e activeTimeRange.endTime.

In un singolo Control.condition è possibile specificare fino a 10 intervalli activeTimeRange. Se non vengono specificati intervalli activeTimeRange, il campo viene ignorato.

La sintassi per un singolo activeTimeRange è la seguente:

[
  {
    "startTime": "START_TIMESTAMP_1",
    "endTime": "END_TIMESTAMP_1"
  }
]
  • START_TIMESTAMP_1: definisce la data e l'ora (inclusive) più antiche a cui verrà applicato il controllo. I timestamp sono in formato "Zulu" UTC RFC 3339, con risoluzione in nanosecondi e fino a nove cifre decimali, ad esempio "2023-10-02T15:01:23Z".
  • END_TIMESTAMP_1: definisce l'ora (inclusa) massima in cui verrà applicato il controllo. L'ora deve essere futura.

Istruzioni API: modificare il comportamento predefinito delle richieste di ricerca con i controlli di pubblicazione

Per modificare il comportamento predefinito delle richieste di ricerca, crea un controllo della pubblicazione e collegalo alla configurazione di pubblicazione predefinita.

Prima di iniziare

Se vuoi creare controlli di pubblicazione, contatta il team degli Account Google e chiedi di essere aggiunto alla lista consentita per i controlli di pubblicazione.

Crea un controllo di pubblicazione

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

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

  1. Trova l'ID del tuo datastore. Se hai già l'ID del tuo datastore, vai al passaggio successivo.

    1. Nella console Google Cloud, vai alla pagina Agent Builder e nel menu di navigazione fai clic su Data Store.

      Vai alla pagina Datastore

    2. Fai clic sul nome del tuo datastore.

    3. Nella pagina Dati del tuo datastore, ottieni l'ID datastore.

  2. Scegli il tipo di condizione e i valori di campo per il controllo.

    Di seguito è riportato un esempio troncato di una condizione:

    {
  "queryTerms": [
      {
        "value": "VALUE_1",
        "fullMatch": FULL_MATCH_1
      },
      {
        "value": "VALUE_2",
        "fullMatch": FULL_MATCH_2
      },
    ],
  "activeTimeRange": [
    {
      "startTime": "START_TIMESTAMP_1",
      "endTime": "END_TIMESTAMP_1"
    },
    {
      "startTime": "START_TIMESTAMP_2",
      "endTime": "END_TIMESTAMP_2"
    },
  ]
}

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

    Controllo boost: fai clic per visualizzare il comando curl per creare un controllo boost.

    Esegui il seguente comando curl:

        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/dataStores/DATA_STORE_ID/controls?CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "boostAction": "BOOST_ACTION",
    }'

    Controllo filtro: fai clic per visualizzare il comando curl per creare un controllo filtro.

    Esegui il seguente comando curl:

        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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "filterAction": "FILTER_ACTION",
    }'

    Controllo sinonimi: fai clic per visualizzare il comando curl per creare un controllo sinonimi.

    Esegui il seguente comando curl:

        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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "synonymsAction": "SYNONYMS_ACTION",
    }'

    Controllo reindirizzamento: fai clic per visualizzare il comando curl per creare un controllo reindirizzamento.

    Esegui il seguente comando curl:

        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/dataStores/DATA_STORE_ID/controls?controlId=CONTROL_ID" \
    -d '{
    "displayName": "DISPLAY_NAME",
    "solutionType": "SOLUTION_TYPE_SEARCH",
    "useCases": ["USE_CASE"],
    "conditions": ["CONDITION"],
    "redirectAction": "REDIRECT_ACTION",
    }'
    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud.
    • DATA_STORE_ID: l'ID univoco del datastore.
    • CONTROL_ID: un identificatore univoco (all'interno di un datastore) per il controllo. L'ID può contenere lettere minuscole, cifre, trattini e trattini bassi.
    • DISPLAY_NAME: il nome leggibile per il controllo. Google consiglia di utilizzare un nome che fornisca un'indicazione su quando o perché utilizzare il controllo. Deve essere una stringa UTF-8 di lunghezza [1,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: (Facoltativo) definisce quando deve essere applicato il controllo.
    • BOOST_ACTION: utilizzato per definire un controllo dell'aumento. Consulta il riferimento all'API boostAction.
    • FILTER_ACTION: utilizzato per definire un controllo filtro. Consulta il riferimento all'API filterAction.
    • SYNONYMS_ACTION: utilizzato per definire un controllo sinonimi. Consulta il riferimento all'API synonymsAction.
    • REDIRECT_ACTION: utilizzato per specificare un URI di reindirizzamento. Consulta il riferimento all'API redirectAction.

  4. Collega il controllo all'app.

    Controllo boost: fai clic per il comando curl per un controllo boost.

    Esegui il seguente comando curl per associare un controllo dell'aumento a una configurazione di pubblicazione per consentirne l'utilizzo nelle richieste di pubblicazione:

        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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=boost_control_ids" \
    -d '{
      "boostControlIds": ["BOOST_ID_1", "BOOST_ID_2" … ]
    }'

    BOOST_ID_1 e BOOST_ID_2: rappresentano gli ID controllo che hai creato nel passaggio precedente.

    Controllo filtro: fai clic sul comando curl per un controllo filtro.

    Esegui il seguente comando curl per associare un controllo filtro a una configurazione di pubblicazione per consentirne l'utilizzo nelle richieste di pubblicazione:

        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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=filter_control_ids" \
    -d '{
      "filterControlIds": ["FILTER_ID_1", "FILTER_ID_2" … ]
    }'

    FILTER_ID_1 e FILTER_ID_2: rappresentano gli ID controllo che hai creato nel passaggio precedente.

    Controllo sinonimi: fai clic per il comando curl per un controllo sinonimi.

    Esegui il seguente comando curl per collegare un controllo dei sinonimi a un'app per consentirne l'utilizzo nelle richieste di pubblicazione:

        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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=synonyms_control_ids" \
    -d '{
     "synonymsControlIds": ["SYNONYM_ID_1", "SYNONYM_ID_2" … ]
    }'

    SYNONYM_ID_1 e SYNONYM_ID_2: rappresentano gli ID controllo che hai creato nel passaggio precedente.

    Controllo del reindirizzamento: fai clic per il comando curl per un controllo del reindirizzamento.

    Esegui il seguente comando curl per collegare un controllo di reindirizzamento a un'app per consentirne l'utilizzo nelle richieste di pubblicazione:

        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/dataStores/DATA_STORE_ID/servingConfigs/default_search?update_mask=redirect_control_ids" \
    -d '{
      "redirectControlIds": ["REDIRECT_ID_1", "REDIRECT_ID_2" … ]
    }'

    REDIRECT_ID_1 e REDIRECT_ID_2: rappresentano gli ID controllo che hai creato nel passaggio precedente.

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.