Questa pagina è stata tradotta dall'API Cloud Translation.

Importare gli eventi utente storici

Questa pagina descrive come importare collettivamente i dati sugli eventi utente da eventi passati. Gli eventi dell'utente sono obbligatori per i consigli sui contenuti multimediali. Se non utilizzi i consigli sui contenuti multimediali, l'importazione degli eventi utente non è necessaria. Tuttavia, è consigliato per le app di ricerca di contenuti multimediali.

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 consigli e il ranking dei risultati di ricerca. I risultati di ricerca con percentuali di clic più elevate vengono messi in evidenza, mentre quelli con percentuali di clic più basse vengono nascosti. Non importare gli eventi utente per i documenti che non hai ancora importato.

Se un evento ha documenti elencati in userEvents.Documents, Vertex AI Search unisce automaticamente gli eventi a quel documento. L'unione consente a Vertex AI Search di attribuire eventi come clic e visualizzazioni al documento corretto in un risultato di ricerca o un consiglio. Per le app di casi d'uso generici, l'unione avviene in modo asincrono, ovvero gli eventi utente vengono uniti ai documenti al termine dell'importazione collettiva (in genere entro alcuni minuti). Per le app multimediali, l'unione avviene in modo sincrono. Vertex AI Search inizia ad unire gli eventi utente ai documenti mentre l'importazione collettiva è ancora in corso. Per scoprire come visualizzare le metriche sugli eventi non uniti nella console, consulta Visualizzare le informazioni sugli eventi utente aggregati.

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 all'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.

Importa eventi utente storici da Cloud Storage

Se hai un'app multimediale, puoi importare gli eventi dell'utente utilizzando la console Google Cloud o l'API. Per gli altri tipi di app, puoi eseguire l'importazione solo tramite l'API.

Console

Per importare gli eventi utente per le app multimediali utilizzando la console, segui questi passaggi:

Nella console Google Cloud, vai alla pagina Agent Builder.

Agent Builder
Nella pagina App, fai clic sull'app multimediale.
Vai alla pagina Dati.

Per le app per 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 eventi, le relative informazioni vengono visualizzate in questa scheda.
Fai clic su Importa eventi.
Seleziona Cloud Storage come origine dati.
Inserisci o seleziona la posizione di Cloud Storage degli eventi utente.
Fai clic su Importa.
La scheda Attività mostra lo stato dell'importazione.
Se si verificano errori di importazione, nella scheda Attività:
1. Espandi l'errore nella colonna Dettagli e fai clic su Visualizza dettagli per visualizzare maggiori informazioni nel riquadro Dettagli del log delle attività.
2. Nel riquadro Dettagli log attività, fai clic su Visualizza log degli errori completi per visualizzare l'errore in Esplora log.

REST

Per importare collettivamente 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 gcsSource per fare riferimento al tuo bucket Cloud Storage.
```
{
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}
```
- INPUT_FILE: un file in Cloud Storage contenente i dati sugli eventi degli utenti. Assicurati che ogni evento utente sia su una riga singola, senza interruzioni di riga. Per la rappresentazione JSON degli eventi utente, consulta userEvents nella 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 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 Vertex AI Agent Builder di creare automaticamente una directory temporanea.

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

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

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/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/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 da quello del tuo datastore, segui questi passaggi per configurare l'accesso a BigQuery.

Apri la pagina IAM e amministrazione nella console Google Cloud.
Seleziona il progetto contenente il datastore in cui vuoi importare gli eventi dell'utente.
Seleziona la casella di controllo Includi concessioni di ruoli fornite da Google.
Trova l'account di servizio denominato Discovery Engine Service Account.
Se non hai mai avviato 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 avviala. Se l'operazione non va a buon fine a causa di errori di autorizzazione, torna qui e completa questa attività. Verrà visualizzato l'account di servizio Discovery Engine.
Copia l'identificatore dell'account di servizio, che ha il formato di un indirizzo email, ad esempio service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com.
Passa al tuo progetto BigQuery (sempre nella stessa pagina IAM e amministrazione) e fai clic su Concede accesso.
In Nuovi principali, inserisci l'identificatore dell'account di servizio e seleziona il ruolo BigQuery > Visualizzatore dati BigQuery.
Fai clic su Salva.

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

Importa eventi da BigQuery

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 eseguire l'importazione solo tramite l'API.

Console

Per importare gli eventi utente per le app multimediali utilizzando la console, segui questi passaggi:

Nella console Google Cloud, vai alla pagina Agent Builder.

Agent Builder
Nella pagina App, fai clic sull'app multimediale.
Vai alla pagina Dati.

Per le app per 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 eventi, le relative informazioni 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à:
1. Espandi l'errore nella colonna Dettagli e fai clic su Visualizza dettagli per visualizzare maggiori informazioni nel riquadro Dettagli del log delle attività.
2. Nel riquadro Dettagli log attività, fai clic su Visualizza log degli errori completi per visualizzare l'errore in Esplora log.

REST

Per importare collettivamente gli eventi utente storici da Cloud Storage:

Importa gli eventi utente inviando una richiesta POST al metodo userEvents:import, specificando 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.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1beta/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"
      }
    }'

Importare 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 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 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
      }
    ]
  }
}
```

Importa gli eventi inviando 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/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"