Importare gli eventi utente storici

Questa pagina descrive come importare in blocco i dati sugli eventi utente da eventi passati.

Per i tipi di eventi utente che puoi importare, consulta il campo eventType dell'oggetto userEvents. Importando gli eventi utente, puoi migliorare la qualità dei risultati. Ad esempio, gli eventi utente influiscono sul ranking dei risultati di ricerca. I risultati con percentuali di clic più elevate vengono promossi, mentre quelli con percentuali di clic più basse vengono nascosti. Importa solo gli eventi utente per i documenti che hai già importato nel datastore.

Se un evento contiene documenti elencati in userEvents.Documents, Gemini Enterprise partecipa automaticamente agli eventi con quel documento. L'unione consente a Gemini Enterprise di attribuire eventi come clic e visualizzazioni al documento corretto in un risultato di ricerca o in un suggerimento. Per le app di ricerca e suggerimenti personalizzati, l'unione avviene in modo asincrono, ovvero gli eventi utente vengono uniti ai documenti al termine dell'importazione batch (in genere entro pochi minuti).

Se utilizzi un'app di ricerca con più datastore collegati, importa gli eventi utente a livello di località anziché di datastore. In questo modo, un determinato evento utente può essere inviato al datastore a cui è associato. Quando importi gli eventi utente a livello di località, includi il campo engine nell'evento utente per associarlo all'app corretta. Per esempi di eventi utente che includono il campo engine, consulta quanto segue:

• Esempi e schemi di tipi di eventi utente delle app personalizzate

Per saperne di più sul metodo di importazione, consulta userEvents.import.

Per importare gli eventi utente in tempo reale, consulta Registra gli eventi utente in tempo reale.

Puoi importare gli eventi storici nei seguenti modi:

• Da Cloud Storage
• Da BigQuery
• Come dati JSON locali

Per la rappresentazione JSON degli eventi utente, consulta userEvents nel riferimento API.

Prima di iniziare

Prima di importare gli eventi utente:

• Crea un datastore e un'app.
• Consulta Informazioni sugli eventi utente per i requisiti per gli eventi utente.

Importa gli eventi utente storici da Cloud Storage

REST

Per importare in blocco gli eventi utente storici da Cloud Storage, segui questi passaggi:

1. Crea uno o più file di dati per i parametri di input per l'importazione. Utilizza l'oggetto gcsSource per puntare al tuo bucket Cloud Storage.

   {
   "gcsSource": {
     "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
     "dataSchema": "user_event"
     },
     "errorConfig":{
         "gcsPrefix":"ERROR_DIRECTORY"
     }
   }
   

   Sostituisci quanto segue:

   • INPUT_FILE: un file in Cloud Storage contenente i dati sugli eventi utente. Assicurati che ogni evento utente sia su una singola riga, senza interruzioni di riga. Per la rappresentazione JSON degli eventi utente, consulta userEvents nel riferimento API. I campi del file di input devono essere nel seguente formato: gs://<bucket>/<path-to-file>/.
   • ERROR_DIRECTORY: facoltativo. Una directory Cloud Storage per le informazioni sugli errori relative all'importazione, ad esempio gs://<your-gcs-bucket>/directory/import_errors. Google consiglia di lasciare vuoto questo campo per consentire a Gemini Enterprise di creare automaticamente una directory temporanea.

2. Importa gli eventi inviando una richiesta POST al metodo userEvents.import, fornendo il nome del file di dati.

   curl -X POST \
       -v \
       -H "Content-Type: application/json; charset=utf-8" \
       -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
       --data @DATA_FILE.json \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/userEvents:import"
   

Importa gli eventi utente storici da BigQuery

Quando crei tabelle per gli eventi utente in BigQuery, utilizza gli schemi documentati in Informazioni sugli eventi utente per le app personalizzate. Ogni evento utente search deve includere un campo engine per associare l'evento a un'app. Per saperne di più, consulta engine.

Configura l'accesso a BigQuery

Se il set di dati BigQuery si trova in un progetto diverso da quello del datastore, segui questi passaggi per configurare l'accesso a BigQuery.

1. Apri la pagina IAM e amministrazione nella console Google Cloud .
2. Seleziona il progetto che contiene il datastore in cui vuoi importare gli eventi utente.
3. Seleziona la casella di controllo Includi concessioni di ruoli fornite da Google.
4. Trova il account di servizio con il nome Discovery Engine Service Account.
5. Se non hai avviato in precedenza un'operazione di importazione con Discovery Engine, questo account di servizio potrebbe non essere elencato. Se non vedi questo account di servizio, torna all'attività di importazione e avvia l'importazione. Quando l'operazione non riesce a causa di errori di autorizzazione, torna qui e completa questa attività. Verrà visualizzato il account di servizio Discovery Engine.
6. Copia l'identificatore del account di servizio, che assomiglia a un indirizzo email, ad esempio service-525@gcp-sa-discoveryengine..
7. Passa al progetto BigQuery (nella stessa pagina IAM e amministrazione) e fai clic su Concedi l'accesso.
8. In Nuove entità, inserisci l'identificatore del account di servizio e seleziona il ruolo BigQuery > Visualizzatore dati BigQuery.
9. Fai clic su Salva.

Per saperne di più sull'accesso a BigQuery, consulta Controllo dell'accesso ai set di dati nella documentazione di BigQuery.

Importa eventi da BigQuery

REST

Per importare in blocco gli eventi utente storici da BigQuery, segui questi passaggi:

1. Importa gli eventi utente inviando una richiesta POST al metodo userEvents.import, fornendo il nome del progetto BigQuery, l'ID set di dati e l'ID tabella.

   Quando importi gli eventi, utilizza il valore user_event per dataSchema.

   curl \
     -v \
     -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
     "https://discoveryengine.googleapis.com/v1/projects/[PROJECT_NUMBER]/locations/global/userEvents:import" \
     --data '{
         "bigquerySource": {
             "projectId":"PROJECT_ID",
             "datasetId": "DATASET_ID",
             "tableId": "TABLE_ID",
             "dataSchema": "user_event"
         }
       }'
   

Importa gli eventi utente storici come dati JSON locali

Puoi importare gli eventi utente includendo i dati JSON locali per gli eventi nella chiamata al metodo userEvents.import.

Per inserire i dati sugli eventi utente in un file JSON e specificare il file in una richiesta API, segui queste istruzioni:

1. Crea un file JSON contenente i dati sugli eventi utente. Per la rappresentazione JSON degli eventi utente, consulta userEvents nella documentazione di riferimento dell'API.

   {
     "inlineSource": {
       "userEvents": [
         {
           USER_EVENT_1
         },
         {
           USER_EVENT_2
         }
       ]
     }
   }
   

2. Importa gli eventi inviando una richiesta POST al metodo userEvents.import, fornendo il nome del file di dati.

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data @[JSON_FILE] \
     "https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/userEvents:import"