Configurare i controlli di pubblicazione

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

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

Informazioni sui controlli di pubblicazione

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

Alcuni controlli, come quelli di boost, hanno dipendenze dai datastore. Se un datastore viene rimosso da un'app, anche 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:

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

Informazioni sulle condizioni

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

  • 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 queryTerms diversi. Se non vengono specificati termini di query, il campo queryTerms viene ignorato.

    Per creare correttamente un controllo di promozione, devi specificare il campo queryTerms con fullMatch impostato su true o false.

  • activeTimeRange: un controllo facoltativo che viene applicato quando una richiesta si verifica entro un intervallo di tempo specificato. Verifica 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 campo activeTimeRange non è specificato, viene ignorato.

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

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

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

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

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

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

Crea e associa controlli di pubblicazione per il boost

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

Utilizza le istruzioni riportate di seguito per creare un controllo di boosting.

Console

Per creare e collegare un controllo di boost utilizzando la console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Seleziona l'app per cui vuoi creare il controllo di boost.

  3. Fai clic su Configurazioni e poi sulla scheda Controllo.

  4. Fai clic su Crea controllo.

  5. In Cosa vuoi fare?, specifica il nome e il tipo di controllo:

    1. In Nome controllo, inserisci un nome per il controllo di boost/bury.

    2. In Tipo di controllo, seleziona Aumenta/Diminuisci.

    3. Fai clic su Continua.

  6. In Imposta ambito e impatto della regola, definisci le azioni che vuoi attivare con questo controllo:

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

    2. In Filtro, aggiungi un filtro.

      Si tratta di una stringa che specifica i requisiti che devono essere soddisfatti dal documento. La condizione di boost viene applicata solo se il documento soddisfa tutti i requisiti. In caso contrario, non ci sono modifiche. Se non specifichi un filtro, il boost viene applicato a tutti i documenti nel datastore.

      Per informazioni sulla sintassi di filtro, consulta Sintassi delle espressioni di filtro.

    3. In Valore di boost/bury, seleziona un valore di boost/bury nell'intervallo [-1, 1] utilizzando il cursore. Il cursore si sposta con incrementi di 0,01.

    4. Fai clic su Continua.

  7. In (Facoltativo) Quando viene attivata la regola, imposta le seguenti condizioni che attivano il controllo. Se non sono configurate condizioni, il controllo è sempre attivo:

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

    2. Aggiungi Termini di query con corrispondenza esatta. Il controllo viene applicato quando questi termini di query corrispondono esattamente.

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

    4. Fai clic su Continua.

  8. In Impostazioni aggiuntive, scegli se attivare la regola:

    1. Se non vuoi attivare questo controllo non appena viene creato, disattiva l'opzione Pubblica questo controllo immediatamente.

    2. Fai clic su Continua.

  9. Fai clic su Invia.

REST

Un controllo di gestione del boost è definito come un controllo con un boostAction.

Utilizza le istruzioni riportate di seguito per creare un controllo di boosting.

Per i dettagli dei campi, consulta il Riferimento API engines.controls e il Riferimento API engines.controls.create.

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

    1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

      Vai ad App

    2. Nella pagina App, trova il nome della tua app e recupera l'ID app dalla colonna ID.

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

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

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud .
    • APP_ID: l'ID dell'app.
    • 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 utilizzare un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa con codifica 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: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore della query specifica da confrontare. È una stringa UTF-8 in minuscolo con lunghezza [1, 5000]. Se FULL_MATCH_1 è true, questo campo può contenere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di ricerca. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede che SearchRequest.query contenga queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • BOOST_VALUE: un numero in virgola mobile nell'intervallo [-1,1]. Quando il valore è negativo, i risultati vengono retrocessi (vengono visualizzati più in basso nei risultati). Quando il valore è positivo, i risultati vengono promossi (vengono visualizzati più in alto nei risultati). Per saperne di più, 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 boost. In caso contrario, non ci saranno modifiche. Se questo campo è vuoto, il boost viene applicato a tutti i documenti nel datastore. Per la sintassi di filtro, consulta Sintassi delle espressioni di filtro. Nota: il campo del documento title non può essere filtrato.
    • DATA_STORE_RESOURCE_PATH: il percorso completo della risorsa del datastore i cui documenti devono essere potenziati da questo controllo. Il formato del percorso completo della risorsa è projects/PROJECT_NUMBER/locations/LOCATION_ID/collections/default_collection/dataStores/DATA_STORE_ID. Questo datastore deve essere collegato all'engine 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 dei controlli che hai creato nel passaggio precedente.

Crea e associa i controlli di pubblicazione dei filtri

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

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

Console

Per creare e collegare un controllo di filtro utilizzando la console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

    Gemini Enterprise

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

  3. Fai clic su Configurazioni e poi sulla scheda Controllo.

  4. Fai clic su Crea controllo.

  5. In Cosa vuoi fare?, specifica il nome e il tipo di controllo:

    1. In Nome controllo, inserisci un nome per il controllo filtro.

    2. In Tipo di controllo, seleziona Filtro.

    3. Fai clic su Continua.

  6. In Imposta ambito e impatto della regola, definisci le azioni che vuoi attivare con questo controllo:

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

    2. In Filtro, indica alla regola quali elementi specifici cercare. Puoi combinare i termini di ricerca utilizzando AND, OR NOT e raggruppare i termini con (). Per le frasi esatte, utilizza le virgolette (""). Ad esempio: category: "electronics" AND price < 500, status: "open" AND priority:"P1".

      Per informazioni sulla sintassi di filtro, consulta Sintassi delle espressioni di filtro.

    3. Fai clic su Continua.

  7. In (Facoltativo) Quando viene attivata la regola, imposta le seguenti condizioni che attivano il controllo. Se non sono configurate condizioni, il controllo è sempre attivo:

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

    2. Aggiungi Termini di query con corrispondenza esatta. Il controllo viene applicato quando questi termini di query corrispondono esattamente.

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

    4. Fai clic su Continua.

  8. In Impostazioni aggiuntive, scegli se attivare la regola:

    1. Se non vuoi attivare questo controllo non appena viene creato, disattiva l'opzione Pubblica questo controllo immediatamente.

    2. Fai clic su Continua.

  9. Fai clic su Invia.

REST

Per i dettagli dei campi, consulta il Riferimento API engines.controls e il Riferimento API engines.controls.create.

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

    1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

      Vai ad App

    2. Nella pagina App, trova il nome della tua app e recupera l'ID app dalla colonna ID.

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

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

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud .
    • APP_ID: l'ID dell'app.
    • 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 utilizzare un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa con codifica 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: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore della query specifica da confrontare. È una stringa UTF-8 in minuscolo con lunghezza [1, 5000]. Se FULL_MATCH_1 è true, questo campo può contenere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di ricerca. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede che SearchRequest.query contenga queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • FILTER: una stringa che specifica i requisiti che devono essere soddisfatti dal documento. Se il documento soddisfa tutti i requisiti, viene restituito nei risultati. In caso contrario, il documento non è presente nei risultati. Per informazioni sulla sintassi di filtro, consulta Sintassi delle espressioni di filtro. Per saperne di più, consulta filterAction. Nota: il campo del documento title non può essere filtrato.

  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 dei controlli che hai creato nel passaggio precedente.

Crea e associa i controlli di pubblicazione dei sinonimi

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

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

Console

Per creare e collegare un controllo dei sinonimi utilizzando la console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Seleziona l'app per cui vuoi creare il controllo dei sinonimi.

  3. Fai clic su Configurazioni e poi sulla scheda Controllo.

  4. Fai clic su Crea controllo.

  5. In Cosa vuoi fare?, specifica il nome e il tipo di controllo:

    1. In Assegna un nome al controllo, inserisci un nome per il controllo dei sinonimi.

    2. In Tipo di controllo, seleziona Sinonimi.

    3. Fai clic su Continua.

  6. In Imposta ambito e impatto della regola, definisci le azioni che vuoi attivare con questo controllo:

    1. Inserisci i sinonimi che vuoi che vengano presi in considerazione nel controllo. Ad esempio, inserisci gatti seguito da un ritorno a capo (non da una virgola), poi felini.

    2. Fai clic su Continua.

  7. In (Facoltativo) Quando viene attivata la regola, imposta le seguenti condizioni che attivano il controllo. Se non sono configurate condizioni, il controllo è sempre attivo:

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

    2. Fai clic su Continua.

  8. In Impostazioni aggiuntive, scegli se attivare la regola:

    1. Se non vuoi attivare questo controllo non appena viene creato, disattiva l'opzione Pubblica questo controllo immediatamente.

    2. Fai clic su Continua.

  9. Fai clic su Invia.

REST

Per i dettagli dei campi, consulta il Riferimento API engines.controls e il Riferimento API engines.controls.create.

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

    1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

      Vai ad App

    2. Nella pagina App, trova il nome della tua app e recupera l'ID app dalla colonna ID.

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

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

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud .
    • APP_ID: l'ID dell'app.
    • 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 utilizzare un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa con codifica 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: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore della query specifica da confrontare. È una stringa UTF-8 in minuscolo con lunghezza [1, 5000]. Se FULL_MATCH_1 è true, questo campo può contenere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di ricerca. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede che SearchRequest.query contenga queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • SYNONYMS_N: un elenco di stringhe associate tra loro, il che aumenta la probabilità che ciascuna mostri risultati simili. Anche se è più probabile che tu ottenga risultati simili, quando cerchi ciascuna delle voci 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 avere codifica UTF-8 ed essere in minuscolo. Non sono consentite stringhe duplicate. Ad esempio, puoi aggiungere "pixel", "smartphone Android" e "smartphone Google" come sinonimi. Per saperne di più, consulta 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 dei controlli che hai creato nel passaggio precedente.

Crea e collega i controlli di gestione dei reindirizzamenti

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

Per creare un controllo di gestione dei reindirizzamenti, segui queste istruzioni.

Per i dettagli dei campi, consulta il Riferimento API engines.controls e il Riferimento API engines.controls.create.

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

    1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

      Vai ad App

    2. Nella pagina App, trova il nome della tua app e recupera l'ID app dalla colonna ID.

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

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

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud .
    • APP_ID: l'ID dell'app.
    • 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 utilizzare un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa con codifica 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: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore della query specifica da confrontare. È una stringa UTF-8 in minuscolo con lunghezza [1, 5000]. Se FULL_MATCH_1 è true, questo campo può contenere al massimo tre termini separati da spazi.
      • FULL_MATCH: un valore booleano che indica se la query di ricerca deve corrispondere esattamente al termine di ricerca. Se impostato su true, richiede che SearchRequest.query corrisponda completamente a queryTerm.value. Se impostato su false, richiede che SearchRequest.query contenga queryTerm.value come sottostringa.
      • START_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare l'inizio di un intervallo di tempo.
      • END_TIMESTAMP: un timestamp in formato "Zulu" UTC RFC 3339 per indicare la fine di un intervallo di tempo.
    • REDIRECT_URI_N: un URI a cui vieni reindirizzato. Può avere una lunghezza massima di 2000 caratteri. Ad esempio, se il valore del termine di query è "assistenza", puoi impostare un reindirizzamento alla pagina di assistenza tecnica anziché restituire (o non restituire) i risultati di ricerca per "assistenza". In questo esempio, l'URI di reindirizzamento diventa "https://www.example.com/support". Per saperne di più, consulta 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 dei controlli che hai creato nel passaggio precedente.

Crea e associa controlli di pubblicazione per la promozione

Un controllo di pubblicazione per la promozione ti consente di visualizzare un link come risultato promosso. Questo controllo è disponibile per le app di ricerca con datastore di dati strutturati o non strutturati e per le app di ricerca combinata.

Affinché il controllo di promozione abbia effetto, devi collegarlo alla configurazione di pubblicazione dell'app.

I controlli di promozione vengono definiti utilizzando un promoteAction.

Per creare correttamente un controllo di promozione, devi specificare il campo queryTerms con fullMatch impostato su true o false.

Utilizza le istruzioni riportate di seguito per creare un controllo di pubblicazione per la promozione.

Console

Per creare un controllo di pubblicazione per la promozione, segui le istruzioni nella scheda REST.

REST

Per i dettagli dei campi, consulta il Riferimento API engines.controls e il Riferimento API engines.controls.create.

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

    1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

      Vai ad App

    2. Nella pagina App, trova il nome della tua app e recupera l'ID app dalla colonna ID.

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

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

    Sostituisci quanto segue:

    • PROJECT_ID: il numero o l'ID del tuo progetto Google Cloud .
    • APP_ID: l'ID dell'app.
    • 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 utilizzare un nome che indichi quando o perché utilizzare il controllo. Deve essere una stringa con codifica 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: un campo facoltativo che definisce quando deve essere applicato il controllo. Contiene i seguenti campi:
      • VALUE: il valore della query specifica da confrontare. È una stringa UTF-8 in minuscolo con lunghezza [1, 5000].
      • FULL_MATCH: un valore booleano che indica se il termine di query deve corrispondere completamente.
      • 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.
    • DATA_STORE_RESOURCE_PATH: il percorso completo della risorsa del datastore i cui risultati di ricerca contengono l'URL della promozione. 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 all'engine specificato nella richiesta.

    • DOCUMENT_RESOURCE_PATH: un campo per specificare il percorso della risorsa del documento da promuovere. Devi fornire l'ID 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.

    • 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 per specificare l'URI a cui il risultato di ricerca indirizza l'utente. Devi fornire l'ID documento nel campo DOCUMENT_RESOURCE_PATH, l'URI nel campo URI o entrambi.

    • URI_DESCRIPTION: un campo facoltativo per descrivere l'URI, che viene visualizzato nel risultato di ricerca.

    La risposta contiene gli ID di controllo della promozione necessari per collegare il controllo della promozione alla tua app di ricerca.

  3. Collega il controllo alla configurazione di pubblicazione dell'app utilizzando il metodo engines.servingConfigs.patch. L'ordine in cui colleghi i promoteControlIds 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 dei controlli che hai ricevuto nel passaggio precedente.

Modifica i controlli di pubblicazione

Per modificare la configurazione di un controllo, segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Seleziona l'app per cui vuoi modificare i controlli.

  3. Fai clic su Configurazioni e poi sulla scheda Controllo.

  4. Nell'elenco dei controlli dell'app, fai clic su per un controllo che vuoi modificare e fai clic su Modifica.

  5. Modifica il controllo nel riquadro Modifica controllo:

    1. Per attivare o disattivare un controllo, nell'elenco dei controlli dei filtri dell'app, fai clic su per un controllo che vuoi attivare o disattivare e fai clic rispettivamente su Attiva o Disattiva.

    2. Per eliminare un controllo, nell'elenco dei controlli dell'app, fai clic su per un controllo che vuoi eliminare e poi su Elimina.

Passaggi successivi