Questa pagina è stata tradotta dall'API Cloud Translation.

Configura i controlli di pubblicazione

I controlli di pubblicazione, detti anche controlli, modificano il comportamento predefinito di un richiesta.

Ad esempio, i controlli possono eseguire il boosting e il bury dei risultati, filtrare le voci da quelle restituite eseguire l'associazione tra loro come sinonimi oppure reindirizzare le query per gli URI specificati.

Informazioni sui controlli di pubblicazione

Per modificare i risultati di una richiesta, devi prima creare un controllo della pubblicazione. Quindi, allega che controllano a un'app. Un controllo influisce solo richieste gestite da un'app a cui è associato il controllo. Se un controllo non è associato a un'app, non ha alcun effetto.

Alcuni controlli, come i controlli di potenziamento, hanno dipendenze dai datastore. Se un insieme di dati viene rimosso da un'app, tutti i controlli dipendenti dall'insieme di dati 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 delle condizioni. I seguenti campi delle condizioni sono disponibili:

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

Se per un controllo vengono specificati entrambi i tipi di condizioni, quest'ultimo viene applicato alla richiesta di ricerca quando entrambi i tipi di condizione sono soddisfatti. Se più per la stessa condizione, solo uno dei valori deve una corrispondenza perché 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 sarà soddisfatta per una richiesta con SearchRequest.query="gShoe" o una richiesta con SearchRequest.query="gBoot", ma non sarà soddisfatto di SearchRequest.query="gSandal" o di altri stringa.

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

Per ulteriori informazioni, vedi servingConfigs.search nel riferimento 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 dei risultati restituito	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 sinonimi	Associa le query tra loro	Cerca app con datastore di siti web, strutturati, non strutturati o multimediali
Controllo dei reindirizzamenti	Reindirizza a un URI specificato	Tutte le app di ricerca

Informazioni sui controlli di pubblicazione avanzata

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 numero in virgola mobile 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 corrisponde a tutti i requisiti, viene applicato il booster. In caso contrario, non viene apportata alcuna modifica. Se questo campo è vuoto, il miglioramento viene applicato a tutti i documenti nei dati . 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 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 dalla documento. Se il documento soddisfa tutti i requisiti, il risultato viene incluso nell'elenco dei risultati. In caso contrario, il risultato viene rimosso dal risultato. dall'elenco di lettura. Per la sintassi dei filtri, consulta la pagina Sintassi delle espressioni 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, rendendo è più probabile che vengano mostrati risultati simili. Devi specificare almeno due stringhe e puoi specificarne fino a 100. Le stringhe devono essere in formato UTF-8 e minuscolo. Non sono consentite stringhe duplicate.

Ad esempio:

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

Informazioni sui controlli di pubblicazione del reindirizzamento

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.

Sintassi per redirectAction:

{
    "redirect_uri": "REDIRECT_URI"
}

REDIRECT_URI: un URI di massimo 2000 caratteri.

Ad esempio, se il valore del termine di query è "support", puoi impostare un alla pagina di assistenza tecnica anziché tornare indietro (o non restituirla) risultati di ricerca per "assistenza".

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

Informazioni sulla condizione `queryTerms`

Il campo 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 per 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ò contenere 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.

È possibile specificare fino a 10 intervalli activeTimeRange su una singola Control.condition. Se non vengono specificati intervalli activeTimeRange, il campo è 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. Timestamp sono nel formato RFC 3339 UTC "Zulu" con risoluzione in nanosecondi e fino a nove cifre frazionarie, ad esempio, "2023-10-02T15:01:23Z".
END_TIMESTAMP_1: definisce l'ora più recente (inclusa) in cui verrà applicato il controllo. L'ora deve essere nel futuro.

Istruzioni dell'API: modifica il comportamento predefinito delle richieste di ricerca con i controlli di pubblicazione

Per modificare il comportamento predefinito della richiesta di ricerca, devi creare un controllo di pubblicazione e alla configurazione di pubblicazione predefinita.

Prima di iniziare

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

Crea un controllo di pubblicazione

Segui queste istruzioni per creare un controllo di pubblicazione.

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

Individua l'ID datastore. Se hai già un datastore ID, 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 del datastore.

Scegli il tipo di condizione e i valori dei campi 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"
    },
  ]
}

Esegui i seguenti comandi curl per creare i controlli.

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

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 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 del progetto 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 SEARCH_USE_CASE_BROWSE è specificato, allora Condition.queryTerms non potrà essere utilizzato nella condizione.
(Facoltativo) CONDITION: indica quando il controllo deve essere applicati.
BOOST_ACTION: utilizzato per definire un controllo del booster. Consulta le Riferimento API di boostAction.
FILTER_ACTION: utilizzato per definire un controllo filtro. Consulta le Riferimento API di filterAction.
SYNONYMS_ACTION: utilizzato per definire un controllo sinonimi. Consulta le Riferimento API di synonymsAction.
REDIRECT_ACTION: utilizzato per specificare un URI di reindirizzamento. Consulta il riferimento all'API redirectAction.

Collega il controllo all'app.

Controllo boost: fai clic per il comando curl per un controllo del livello di potenziamento.

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 accedere al curl. per un controllo dei 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 le gli ID controllo creati nel passaggio precedente.

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

Esegui questo comando curl per collegare un controllo di reindirizzamento a un per abilitare l'utilizzo delle 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, vedi Valuta la qualità della ricerca.

Configura i controlli di pubblicazione

Informazioni sui controlli di pubblicazione

Tipi di controlli di pubblicazione

Informazioni sui controlli di pubblicazione avanzata

Informazioni sui controlli di pubblicazione dei filtri

Informazioni sui controlli di pubblicazione dei sinonimi

Informazioni sui controlli di pubblicazione del reindirizzamento

Informazioni sulla condizione queryTerms

Informazioni sulla condizione activeTimeRange

Istruzioni dell'API: modifica il comportamento predefinito delle richieste di ricerca con i controlli di pubblicazione

Prima di iniziare

Crea un controllo di pubblicazione

Passaggi successivi

Informazioni sulla condizione `queryTerms`

Informazioni sulla condizione `activeTimeRange`