Questa pagina descrive come importare in blocco i dati sugli eventi utente da eventi passati. Gli eventi utente sono obbligatori per le app multimediali. Se non utilizzi app multimediali, l'importazione degli eventi utente non è necessaria. Tuttavia, la registrazione degli eventi utente è consigliata per le app di ricerca e suggerimenti personalizzati.
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 ha documenti elencati in userEvents.Documents, le
applicazioni AI partecipano automaticamente agli eventi con quel documento.
L'unione consente alle applicazioni AI di attribuire eventi come clic e
visualizzazioni al documento corretto in un risultato di ricerca o in un consiglio. Per
le app di ricerca e consigli personalizzati, l'unione avviene in modo asincrono, ovvero gli eventi utente
vengono uniti ai documenti dopo il completamento dell'importazione batch (in genere
entro pochi minuti).
Per le app multimediali, l'unione avviene in modo sincrono.
Le applicazioni AI iniziano a unire gli eventi utente ai documenti mentre
l'importazione batch è ancora in corso.
Per scoprire come visualizzare
le metriche sugli eventi non uniti nella console, consulta
Visualizzare le informazioni aggregate sugli eventi utente.
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 all'datastorei a cui è associato. Per
importare eventi utente con documenti da diversi
dataStores a livello di località anziché di datastore,
vedi 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:
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 multimediali o Informazioni sugli eventi utente per i requisiti degli eventi utente.
Importa eventi utente storici da Cloud Storage
Se hai un'app multimediale, puoi importare gli eventi utente utilizzando la console Google Cloud o l'API. Per gli altri tipi di app, puoi importare solo tramite l'API.Console
Per importare gli eventi utente per le app multimediali utilizzando la console, segui questi passaggi:
Nella Google Cloud console, vai alla pagina AI Applications.
Nella pagina App, fai clic sull'app multimediale.
Vai alla pagina Dati.
Per le app di suggerimenti sui contenuti multimediali, la scheda Requisiti mostra i documenti multimediali e gli eventi utente che devi importare.
Fai clic sulla scheda Eventi. Se hai già importato degli eventi, le informazioni relative vengono visualizzate in questa scheda.
Fai clic su Importa eventi.
Seleziona Cloud Storage come origine dati.
Inserisci o seleziona la posizione Cloud Storage dei tuoi eventi utente.
Fai clic su Importa.
La scheda Attività mostra lo stato dell'importazione.
Se si verificano errori di importazione, nella scheda Attività:
Espandi l'errore nella colonna Dettagli e fai clic su Visualizza dettagli per visualizzare ulteriori informazioni nel riquadro Dettagli log attività.
Nel riquadro Dettagli log attività, fai clic su Visualizza log errori completi per visualizzare l'errore in Esplora log.
REST
Per importare in blocco gli eventi utente storici da Cloud Storage:
Crea uno o più file di dati per i parametri di input per l'importazione. Utilizza l'oggetto
gcsSourceper indirizzare il 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, consultauserEventsnella documentazione di riferimento dell'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 informazioni sugli errori relativi all'importazione, ad esempiogs://<your-gcs-bucket>/directory/import_errors. Google consiglia di lasciare vuoto questo campo per consentire alle applicazioni AI di creare automaticamente una directory temporanea.
Importa gli eventi effettuando una richiesta POST al metodo
userEvents.import, specificando 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/dataStores/DATA_STORE_ID/userEvents:import"Se importi eventi utente a livello di località, utilizza l'endpoint
https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/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.
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.
- Apri la pagina IAM e amministrazione nella console Google Cloud .
- Seleziona il progetto che contiene il datastore in cui vuoi importare gli eventi utente.
- Seleziona la casella di controllo Includi concessioni di ruoli fornite da Google.
- Trova il account di servizio con il nome Discovery Engine Service Account.
- Se non hai mai avviato un'operazione di importazione con Discovery Engine, questoaccount di serviziot 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 Discovery Engine.
- Copia l'identificatore del account di servizio, che ha l'aspetto di un indirizzo email, ad esempio
service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com. - Passa al tuo progetto BigQuery (nella stessa pagina IAM e amministrazione) e fai clic su Concedi l'accesso.
- Per Nuovi principal, inserisci l'identificatore dell'account di servizio e seleziona il ruolo BigQuery > Visualizzatore dati BigQuery.
- Fai clic su Salva.
Per saperne di più sull'accesso a BigQuery, consulta la sezione Controllare l'accesso ai set di dati nella documentazione di BigQuery.
Importare eventi da BigQuery
Se hai un'app multimediale, puoi importare gli eventi utente utilizzando la consoleGoogle Cloud o l'API. Per gli altri tipi di app, puoi importare solo utilizzando l'API.Console
Per importare gli eventi utente per le app multimediali utilizzando la console, segui questi passaggi:
Nella Google Cloud console, vai alla pagina AI Applications.
Nella pagina App, fai clic sull'app multimediale.
Vai alla pagina Dati.
Per le app di suggerimenti sui contenuti multimediali, la scheda Requisiti mostra i documenti multimediali e gli eventi utente che devi importare.
Fai clic sulla scheda Eventi. Se hai già importato degli eventi, le informazioni relative vengono visualizzate in questa scheda.
Fai clic su Importa eventi.
Seleziona BigQuery come origine dati.
Inserisci o seleziona il percorso BigQuery per gli eventi utente.
Fai clic su Importa.
La scheda Attività mostra lo stato dell'importazione.
Se si verificano errori di importazione, nella scheda Attività:
Espandi l'errore nella colonna Dettagli e fai clic su Visualizza dettagli per visualizzare ulteriori informazioni nel riquadro Dettagli log attività.
Nel riquadro Dettagli log attività, fai clic su Visualizza log errori completi per visualizzare l'errore in Esplora log.
REST
Per importare in blocco gli eventi utente storici da Cloud Storage:
Importa gli eventi utente effettuando 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_eventperdataSchema.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/dataStores/DATA_STORE_ID/userEvents:import" \ --data '{ "bigquerySource": { "projectId":"PROJECT_ID", "datasetId": "DATASET_ID", "tableId": "TABLE_ID", "dataSchema": "user_event" } }'Se importi eventi utente a livello di località, utilizza l'endpoint
https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.
Importare 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 degli eventi utente in un file JSON e specificare il file in una richiesta API, segui queste istruzioni:
Crea un file JSON contenente i dati degli eventi utente. Per la rappresentazione JSON degli eventi utente, consulta
userEventsnella documentazione di riferimento dell'API.{ "inlineSource": { "userEvents": [ { USER_EVENT_1 }, { USER_EVENT_2 } ] } }Importa gli eventi effettuando una richiesta POST al metodo
userEvents.import, specificando 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/dataStores/DATA_STORE_ID/userEvents:import"Se importi eventi utente a livello di località, utilizza l'endpoint
https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import.