Importare gli eventi utente storici

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

Per i tipi di eventi utente che puoi importare, consulta il eventType campo dell' userEvents oggetto. 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 ha documenti elencati in userEvents.Documents, allora Gemini Enterprise unisce automaticamente gli eventi a 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 una raccomandazione. Per le app di ricerca personalizzata e di raccomandazioni, 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é a livello 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 associare l'evento all'app corretta. Per esempi di eventi utente che includono il campo engine, consulta quanto segue:

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

Per ulteriori informazioni sul metodo di importazione, consulta userEvents.import.

Per importare gli eventi utente in tempo reale, consulta Registrare 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 la sezione Informazioni sugli eventi utente per i requisiti degli eventi utente.

Importare 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 dell'importazione. Utilizza l' gcsSource oggetto per puntare al 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 degli eventi utente. Assicurati che ogni evento utente si trovi 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 relativi 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 effettuando una richiesta POST al userEvents.import metodo, 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"
   

Importare 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 ulteriori informazioni, consulta engine.

Configurare l'accesso a BigQuery

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

1. Apri la pagina IAM e amministrazione nella Google Cloud console.
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. Se l'operazione non riesce a causa di errori di autorizzazione, torna qui e completa questa attività. Verrà visualizzato il account di servizio di Discovery Engine.
6. Copia l'identificatore del account di servizio, che ha l'aspetto di un indirizzo email , ad esempio, [e-mail].
7. Passa al progetto BigQuery (nella stessa pagina IAM e amministrazione) e fai clic su Concedi l'accesso.
8. In Nuovi principali, inserisci l'identificatore del account di servizio e seleziona il ruolo BigQuery > Visualizzatore dati BigQuery.
9. Fai clic su Salva.

Per ulteriori informazioni sull'accesso a BigQuery, consulta Controllare l'accesso ai set di dati nella documentazione di BigQuery.

Importare eventi da BigQuery

REST

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

1. Importa gli eventi utente effettuando una richiesta POST al userEvents.import metodo, fornendo il nome del progetto BigQuery, l'ID del set di dati e l'ID della 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"
         }
       }'
   

Importare eventi utente storici come dati JSON locali

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

Per inserire i dati degli 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 degli 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 effettuando una richiesta POST al userEvents.import metodo, 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"