Method: projects.locations.collections.dataStores.servingConfigs.recommend

Esegue un suggerimento, che richiede un evento utente contestuale.

Richiesta HTTP

POST https://discoveryengine.googleapis.com/v1alpha/{servingConfig=projects/*/locations/*/collections/*/dataStores/*/servingConfigs/*}:recommend

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri del percorso

Parametri
servingConfig

string

Obbligatorio. Nome completo della risorsa di un ServingConfig: projects/*/locations/global/collections/*/engines/*/servingConfigs/* o projects/*/locations/global/collections/*/dataStores/*/servingConfigs/*

Viene creata una configurazione di pubblicazione predefinita insieme alla creazione del motore di suggerimenti. L'ID motore viene utilizzato come ID della configurazione di pubblicazione predefinita. Ad esempio, per il motore projects/*/locations/global/collections/*/engines/my-engine, puoi utilizzare projects/*/locations/global/collections/*/engines/my-engine/servingConfigs/my-engine per le richieste RecommendationService.Recommend.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "userEvent": {
    object (UserEvent)
  },
  "pageSize": integer,
  "filter": string,
  "validateOnly": boolean,
  "params": {
    string: value,
    ...
  },
  "userLabels": {
    string: string,
    ...
  }
}
Campi
userEvent

object (UserEvent)

Obbligatorio. Contesto dell'utente, di ciò che sta guardando e dell'azione che ha intrapreso per attivare la richiesta servingConfigs.recommend. Tieni presente che questi dettagli dell'evento utente non verranno inseriti nei log userEvent. Pertanto, è necessaria una richiesta di scrittura userEvent separata per la registrazione degli eventi.

Non impostare UserEvent.user_pseudo_id o UserEvent.user_info.user_id sullo stesso ID fisso per utenti diversi. Se stai cercando di ricevere suggerimenti non personalizzati (non consigliato, in quanto può influire negativamente sulle prestazioni del modello), imposta UserEvent.user_pseudo_id su un ID univoco casuale e lascia UserEvent.user_info.user_id non impostato.
pageSize

integer

Il numero massimo di risultati da restituire. Imposta questa proprietà sul numero di risultati dei suggerimenti necessari. Se è zero, il servizio sceglie un valore predefinito ragionevole. Il valore massimo consentito è 100. I valori superiori a 100 vengono impostati su 100.
filter

string

Filtro per limitare i risultati dei suggerimenti con un limite di lunghezza di 5000 caratteri. Al momento sono supportate solo le espressioni di filtro sull'attributo filterTags.

Esempi:

  • (filterTags: ANY("Red", "Blue") OR filterTags: ANY("Hot", "Cold"))
  • (filterTags: ANY("Red", "Blue")) AND NOT (filterTags: ANY("Green"))

Se attributeFilteringSyntax è impostato su true nel campo params, sono previste espressioni basate sugli attributi anziché la sintassi basata sui tag descritta sopra. Esempi:

  • (language: ANY("en", "es")) AND NOT (categories: ANY("Movie"))
  • (available: true) AND (language: ANY("en", "es")) OR (categories: ANY("Movie"))

Se il filtro blocca tutti i risultati, l'API restituisce documenti popolari generici (non filtrati). Se vuoi solo risultati che corrispondano rigorosamente ai filtri, imposta strictFiltering su true in RecommendRequest.params per ricevere risultati vuoti.

Tieni presente che l'API non restituisce mai Document con storageStatus come EXPIRED o DELETED, indipendentemente dalle scelte di filtro.
validateOnly

boolean

Utilizza la modalità di sola convalida per questa query di suggerimenti. Se impostato su true, viene utilizzato un modello fittizio che restituisce ID documento arbitrari. Tieni presente che la modalità di sola convalida deve essere utilizzata solo per testare l'API o se il modello non è pronto.
params

map (key: string, value: value (Value format))

Parametri aggiuntivi specifici del dominio per i suggerimenti.

Valori consentiti:

  • returnDocument: valore booleano. Se impostato su true, l'oggetto Documento associato viene restituito in RecommendResponse.RecommendationResult.document.
  • returnScore: valore booleano. Se impostato su true, il punteggio di suggerimento corrispondente a ogni documento restituito viene impostato in RecommendResponse.RecommendationResult.metadata. Il punteggio indicato indica la probabilità di conversione di un documento in base al contesto e alla cronologia dell'utente.
  • strictFiltering: valore booleano. True per impostazione predefinita. Se impostato su false, il servizio restituisce documenti popolari generici (non filtrati) anziché vuoti se il filtro blocca tutti i risultati dei suggerimenti.
  • diversityLevel: stringa. Valore predefinito vuoto. Se il valore non è vuoto, deve essere uno dei seguenti:
    • no-diversity
    • low-diversity
    • medium-diversity
    • high-diversity
    • auto-diversity Questa opzione offre il controllo a livello di richiesta e regola i risultati dei suggerimenti in base alla categoria del documento.
  • attributeFilteringSyntax: valore booleano. False per impostazione predefinita. Se impostato su true, il campo filter viene interpretato in base alla nuova sintassi basata sugli attributi.
userLabels

map (key: string, value: string)

Le etichette utente applicate a una risorsa devono soddisfare i seguenti requisiti:

  • Ogni risorsa può avere più etichette, fino a un massimo di 64.
  • Ogni etichetta deve essere una coppia chiave/valore.
  • Le chiavi hanno una lunghezza minima di 1 carattere e una lunghezza massima di 63 caratteri e non possono essere vuote. I valori possono essere vuoti e avere una lunghezza massima di 63 caratteri.
  • Le chiavi e i valori possono contenere solo lettere minuscole, caratteri numerici, trattini bassi e trattini. Tutti i caratteri devono utilizzare la codifica UTF-8; sono consentiti i caratteri internazionali.
  • La parte della chiave di un'etichetta deve essere univoca. Tuttavia, puoi utilizzare la stessa chiave con più risorse.
  • Le chiavi devono iniziare con una lettera minuscola o un carattere internazionale.

Per maggiori dettagli, consulta Requisiti per le etichette.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di RecommendResponse.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.serving.readwrite

Per saperne di più, consulta la Authentication Overview.

Autorizzazioni IAM

Richiede la seguente autorizzazione IAM per la risorsa servingConfig:

  • discoveryengine.servingConfigs.recommend

Per saperne di più, consulta la documentazione di IAM.