Importare gli eventi utente storici

Questa pagina descrive come importare collettivamente i dati sugli eventi utente da eventi passati. I modelli di Vertex AI Search per il retail richiedono dati sugli eventi utente per l'addestramento.

Dopo aver configurato la registrazione degli eventi in tempo reale, può essere necessario un tempo considerevole per registrare dati sugli eventi utente sufficienti per addestrare i modelli. Puoi accelerare l'addestramento iniziale del modello importando collettivamente i dati sugli eventi utente da eventi passati. Prima di farlo, consulta le best practice per la registrazione degli eventi utente e la sezione Prima di iniziare in questa pagina.

Le procedure di importazione in questa pagina si applicano sia ai consigli sia alla ricerca. Dopo aver importato i dati, entrambi i servizi possono utilizzare questi eventi, quindi non è necessario importare gli stessi dati due volte se utilizzi entrambi i servizi.

Puoi:

• Importa gli eventi da Cloud Storage.
• Importa gli eventi da BigQuery.
• Importa gli eventi di Google Analytics 360 da BigQuery.
• Importare gli eventi di Google Analytics 4 da BigQuery.
• Importa gli eventi in linea con il metodo userEvents.import.

Tutorial sull'importazione di eventi da Cloud Storage

Questo tutorial mostra come importare gli eventi utente da Cloud Storage.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Tutorial sull'importazione di eventi da BigQuery

Questo tutorial mostra come importare gli eventi utente da BigQuery.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Tutorial sull'importazione di eventi in linea

Questo tutorial mostra come importare i dati sugli eventi utente in linea.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Prima di iniziare

Per evitare errori di importazione e assicurarti che siano disponibili dati sufficienti per generare buoni risultati, esamina le seguenti informazioni prima di importare gli eventi utente.

• Consulta le best practice per la registrazione degli eventi utente.

• La formattazione degli eventi utente varia a seconda del tipo di evento utente. Consulta Schema di tipi ed esempi di eventi utente per il formato da specificare quando crei tabelle per ogni tipo di evento.

• I consigli e la ricerca hanno requisiti minimi dei dati diversi. Assicurati che gli eventi utente soddisfino i requisiti del servizio che intendi utilizzare:

  • Consulta la sezione Requisiti e best practice per gli eventi utente per conoscere i requisiti per la ricerca e i consigli.

  • Se utilizzi modelli di consigli, consulta anche Requisiti per i dati sugli eventi utente, che elenca i requisiti aggiuntivi a seconda del tipo di modello di consigli e dell'obiettivo di ottimizzazione che prevedi di utilizzare.

Considerazioni sull'importazione degli eventi

Questa sezione descrive i metodi che possono essere utilizzati per l'importazione collettiva degli eventi utente storici, quando è possibile utilizzare ciascun metodo e alcuni dei relativi limiti.

Importa eventi utente da Cloud Storage

Importa gli eventi utente da Cloud Storage utilizzando la console Google Cloud o il metodo userEvents.import.

Importa eventi utente da BigQuery

Importa gli eventi utente da BigQuery utilizzando la console Google Cloud o il metodo userEvents.import.

Configurare l'accesso a BigQuery

Segui le istruzioni riportate in Configurare l'accesso al set di dati BigQuery per assegnare all'account di servizio Vertex AI Search for Retail il ruolo Proprietario dati BigQuery per il set di dati BigQuery.

Importa gli eventi utente da BigQuery

Puoi importare gli eventi 360 utilizzando la console di ricerca per la vendita al dettaglio o il metodo userEvents.import.

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 application-default print-access-token)"" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \
--data '{
  "inputConfig": {
    "bigQuerySource": {
      "datasetId": "DATASET_ID",
      "tableId": "TABLE_ID",
      "dataSchema": "SCHEMA_TYPE"
  }
}
}'

Importare gli eventi utente di Analytics 360 con BigQuery

Puoi importare gli eventi utente di Analytics 360 se hai integrato Analytics 360 con BigQuery e utilizzi E-commerce avanzato.

Le procedure riportate di seguito presuppongono che tu abbia dimestichezza con l'utilizzo di BigQuery e Analytics 360.

Prima di iniziare

Prima di procedere con i passaggi successivi, assicurati che:

• Stai utilizzando l'E-commerce avanzato.
• Hai collegato BigQuery ad Analytics 360.

Controlla l'origine dati

1. Assicurati che i dati sugli eventi utente da importare siano formattati correttamente in una tabella BigQuery a cui hai accesso.

   Assicurati che la tabella sia denominata project_id:ga360_export_dataset.ga_sessions_YYYYMMDD.

   Per saperne di più sul formato e sulla denominazione delle tabelle, consulta la documentazione di Google Analytics.

2. Nella console Google Cloud BigQuery, seleziona la tabella dal pannello Explorer per visualizzarne l'anteprima.

   Verifica che:

   1. La colonna clientId ha un valore valido, ad esempio 123456789.123456789.

      Tieni presente che questo valore è diverso dal valore completo del cookie _ga (che ha un formato come GA1.3.123456789.123456789).

   2. La colonna hits.transaction.currencyCode ha un codice valuta valido.

   3. Se prevedi di importare eventi search, verifica che sia presente una colonna hits.page.searchKeyword o hits.customVariable.searchQuery.

      Sebbene Vertex AI Search for Retail richieda sia searchQuery sia productDetails per restituire un elenco di risultati di ricerca, Analytics 360 non memorizza sia le query di ricerca sia le impressioni dei prodotti in un unico evento. Affinché Vertex AI Search for Retail funzioni, devi creare un tag a livello di livello dati o un pixel JavaScript per poter importare entrambi i tipi di eventi utente dalle origini Google Analytics:

      • searchQuery, che viene letto dal parametro search_term o dagli eventi view_search_results, è derivato da hits.page.searchKeyword o da hits.customVariables.customVarValue se hits.customVariables.customVarName è searchQuery.
      • productDetails, l'impressione del prodotto letta dal parametro items dell'evento view_item_list, viene presa da hits.product se hits.product.isImpressions è TRUE.

3. Controlla la coerenza degli ID articolo tra il catalogo caricato e la tabella degli eventi utente di Analytics 360.

   Utilizza un ID prodotto qualsiasi della colonna hits.product.productSKU nell'anteprima della tabella BigQuery e il metodo product.get per assicurarti che lo stesso prodotto sia presente nel catalogo caricato.

   export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
   
      curl \
        -v \
        -X GET \
        -H "Content-Type: application/json; charset=utf-8" \
        -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

Importa gli eventi di Analytics 360

Puoi importare gli eventi di Google Analytics 360 utilizzando la console Search for Retail o il metodo userEvents.import.

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 application-default print-access-token)"" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "some_ga360_export_dataset",
        "tableId": "ga_sessions_YYYYMMDD",
        "dataSchema": "user_event_ga360"
    }
  }
}'

public static String importUserEventsFromBigQuerySource()
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  BigQuerySource bigQuerySource = BigQuerySource.newBuilder()
      .setProjectId(PROJECT_ID)
      .setDatasetId(DATASET_ID)
      .setTableId(TABLE_ID)
      .setDataSchema("user_event")
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setBigQuerySource(bigQuerySource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Importare le visualizzazioni della home page di Analytics 360 con BigQuery

In Analytics 360, gli eventi di visualizzazione della home page non sono distinta dagli altri eventi di visualizzazione di pagina. Ciò significa che gli eventi di visualizzazione della home page non vengono importati come eventi con gli altri tipi di eventi (ad esempio visualizzazione-pagina-dettagli) in Importare gli eventi di Analytics 360.

La procedura riportata di seguito spiega come estrarre gli eventi di visualizzazione della home page dai dati di Analytics 360 e importarli in Vertex AI Search per il retail. In breve, questo viene fatto estraendo le visualizzazioni della home page degli utenti (identificate dal percorso della home page) in una nuova tabella BigQuery e poi importando i dati da questa nuova tabella in Vertex AI Search per il retail.

Per importare gli eventi di visualizzazione della home page da Analytics 360 in Vertex AI Search for Retail:

1. Crea un set di dati BigQuery o assicurati di avere un set di dati BigQuery a cui puoi aggiungere una tabella.

   Questo set di dati può trovarsi nel progetto Vertex AI Search for Retail o nel progetto in cui hai i dati di Analytics 360. Si tratta del set di dati di destinazione in cui copierai gli eventi di visualizzazione della home page di Analytics 360.

2. Crea una tabella BigQuery nel set di dati come segue:

   1. Sostituisci le variabili nel seguente codice SQL come segue.

      • target_project_id: il progetto in cui si trova il set di dati del passaggio 1.

      • target_dataset: il nome del set di dati del passaggio 1.

      CREATE TABLE TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage (
       eventType STRING NOT NULL,
       visitorId STRING NOT NULL,
       userId STRING,
       eventTime STRING NOT NULL
      );

   2. Copia l'esempio di codice SQL.

   3. Apri la pagina BigQuery nella console Google Cloud.

      Vai alla pagina BigQuery

   4. Se non è già selezionato, seleziona il progetto di destinazione.

   5. Nel riquadro Editor, incolla il codice SQL di esempio.

   6. Fai clic su play_circle Esegui e attendi il completamento dell'esecuzione della query.

   L'esecuzione di questo codice crea una tabella nel formatotarget_project_id:target_dataset.ga_homepage_YYYYMMDD, ad esempiomy-project:view_events.ga_homepage_20230115.

3. Copia gli eventi di visualizzazione della home page di Analytics 360 dalla tabella di dati di Analytics 360 nella tabella creata nel passaggio 2 precedente.

   1. Sostituisci le variabili nel seguente codice di esempio SQL come segue:

      • source_project_id::l'ID del progetto che contiene i dati di Analytics 360 in una tabella BigQuery.

      • source_dataset::il set di dati nel progetto di origine che contiene i dati di Analytics 360 in una tabella BigQuery.

      • source_table::la tabella nel progetto di origine che contiene i dati di Analytics 360.

      • target_project_id::lo stesso ID progetto di destinazione del passaggio 2 precedente.

      • target_dataset: lo stesso set di dati di destinazione del precedente passaggio 2.

      • path: è il percorso alla home page. Di solito si tratta di /, ad esempio se la home page è example.com/. Tuttavia, se la home page è simile a examplepetstore.com/index.html, il percorso è /index.html.

      INSERT INTO `TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage(eventType,visitorId,userID,eventTime)`
      
      SELECT
        "home-page-view" as eventType,
        clientId as visitorId,
        userId,
        CAST(FORMAT_TIMESTAMP("%Y-%m-%dT%H:%M:%SZ",TIMESTAMP_SECONDS(visitStartTime)) as STRING) AS eventTime
      
      FROM
        `SOURCE_PROJECT_ID.SOURCE_DATASET.SOURCE_TABLE`, UNNEST(hits) as hits
      
      WHERE hits.page.pagePath = "PATH" AND visitorId is NOT NULL;

   2. Copia l'esempio di codice SQL.

   3. Apri la pagina BigQuery nella console Google Cloud.

      Vai alla pagina BigQuery

   4. Se non è già selezionato, seleziona il progetto di destinazione.

   5. Nel riquadro Editor, incolla il codice SQL di esempio.

   6. Fai clic su play_circle Esegui e attendi il completamento dell'esecuzione della query.

4. Segui le istruzioni riportate in Importa eventi utente da BigQuery per importare gli eventi di visualizzazione della home page dalla tabella di destinazione. Durante la selezione dello schema, se lo importi utilizzando la console, seleziona Schema eventi utente per la vendita al dettaglio; se lo importi utilizzando userEvents.import, specifica user_event per il valore dataSchema.

5. Elimina la tabella e il set di dati creati nei passaggi 1 e 2.

Importa gli eventi utente di Google Analytics 4 con BigQuery

Puoi importare gli eventi utente di Google Analytics 4 se hai integrato Google Analytics 4 con BigQuery e utilizzi Google Analytics E-commerce.

Le procedure riportate di seguito presuppongono che tu abbia dimestichezza con l'utilizzo di BigQuery e Google Analytics 4.

Prima di iniziare

Prima di procedere con i passaggi successivi, assicurati che:

• Utilizzi Google Analytics E-commerce.
• Hai collegato BigQuery a Google Analytics 4.

Controlla l'origine dati

Per assicurarti che i dati sugli eventi utente siano pronti per l'importazione, segui questi passaggi.

Per una tabella dei campi Google Analytics 4 utilizzati da Vertex AI Search per il retail e a quali campi di Vertex AI Search per il retail vengono mappati, consulta Campi evento utente di Google Analytics 4.

Per tutti i parametri evento di Google Analytics, consulta la documentazione di riferimento sugli eventi di Google Analytics.

1. Assicurati che i dati sugli eventi utente da importare siano formattati correttamente in una tabella BigQuery a cui hai accesso.

   • Il set di dati deve avere il nome analytics_PROPERTY_ID.
   • La tabella deve avere il nome events_YYYYMMDD.

   Per informazioni sui nomi e sul formato delle tabelle, consulta la documentazione di Google Analytics.

2. Nella console Google Cloud BigQuery, seleziona il set di dati dal riquadro Explorer e individua la tabella degli eventi dell'utente che prevedi di importare.

   Verifica che:

   1. La colonna event_params.key ha una chiave currency e il suo valore di stringa associato è un codice valuta valido.

   2. Se prevedi di importare eventi search, controlla che la colonna event.event_params.key abbia una chiave search_term e un valore associato.

      Sebbene Vertex AI Search per il retail richieda sia searchQuery sia productDetails per restituire un elenco di risultati di ricerca, Google Analytics 4 non memorizza sia le query di ricerca sia le impressioni dei prodotti in un unico evento. Affinché Vertex AI Search for Retail funzioni, devi creare un tag a livello di livello dati o da un pixel JavaScript per poter importare entrambi i tipi di eventi utente dalle origini Google Analytics:

      • searchQuery, che viene letto dal parametro search_term o dagli eventi view_search_results.
      • productDetails, l'impressione del prodotto che viene letta dal parametro items dell'evento view_item_list.

      Per informazioni su search in Google Analytics 4, consulta search nella documentazione di Google Analytics.

3. Verifica la coerenza degli ID articolo tra il catalogo caricato e la tabella degli eventi utente di Google Analytics 4.

   Per assicurarti che un prodotto nella tabella utente di Google Analytics 4 sia anche nel catalogo caricato, copia un ID prodotto dalla colonna event.items.item_id nell'anteprima della tabella BigQuery e utilizza il metodo product.get per verificare se l'ID prodotto è presente nel catalogo caricato.

   export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
   
      curl \
        -v \
        -X GET \
        -H "Content-Type: application/json; charset=utf-8" \
        -H "Authorization: Bearer "$(gcloud auth application-default print-access-token)"" \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

Configurare l'accesso a BigQuery

Segui le istruzioni riportate in Configurare l'accesso al set di dati BigQuery per assegnare all'account di servizio Vertex AI Search for Retail il ruolo Proprietario dati BigQuery per il set di dati BigQuery.

Importare gli eventi Google Analytics 4

Puoi importare gli eventi di Google Analytics 4 utilizzando la console Search for Retail o il metodo userEvents.import.

Importare gli eventi Google Analytics 4 utilizzando la console

1. Vai alla pagina Dati> nella console Ricerca per la vendita al dettaglio.
   
   Vai alla pagina Dati
2. Fai clic su Importa per aprire il riquadro Importa dati.
3. Scegli Eventi utente.
4. Seleziona BigQuery come origine dati.

5. Seleziona lo schema dei dati.

   • Google Analytics 4: da utilizzare per gli eventi di Google Analytics 4.
   • Google Analytics 360: da utilizzare per gli eventi Google Analytics 360, a meno che non importi solo gli eventi di visualizzazione della home page da Google Analytics 360 (in questo caso, utilizza lo schema Eventi utente per la vendita al dettaglio).
   • Schema degli eventi utente per la vendita al dettaglio: da utilizzare per importare eventi da origini diverse da Google Analytics e per importare solo gli eventi di visualizzazione della home page da Google Analytics 360.
6. Inserisci la tabella BigQuery in cui si trovano i dati.
7. (Facoltativo) Inserisci la posizione di un bucket Cloud Storage nel progetto come posizione temporanea per i dati.
   Se non specificato, viene utilizzata una posizione predefinita. Se specificato, i bucket BigQuery e Cloud Storage devono essere nella stessa regione.
8. (Facoltativo) In Mostra opzioni avanzate, inserisci la posizione di un bucket Cloud Storage nel tuo progetto come posizione temporanea per i dati.
   
   Se non specificato, viene utilizzata una posizione predefinita. Se specificato, i bucket BigQuery e Cloud Storage devono trovarsi nella stessa regione.
9. Fai clic su Importa.

Importare gli eventi Google Analytics 4 utilizzando l'API

Importa gli eventi utente includendo i dati relativi agli eventi nella chiamata al metodo userEvents.import. Consulta il riferimento all'API userEvents.import.

Per dataSchema, utilizza il valore user_event_ga4.

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 application-default print-access-token)"" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "projectId": "PROJECT_ID",
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event_ga4"
    }
  }
}'

Importa gli eventi utente in linea

Puoi importare gli eventi utente in linea includendo i dati relativi agli eventi nella chiamata al metodo userEvents.import.

Il modo più semplice per farlo è inserire i dati sugli eventi utente in un file JSON e fornire il file a cURL.

Per i formati dei tipi di eventi utente, consulta Informazioni sugli eventi utente.

public static String importUserEventsFromInlineSource(
    List<UserEvent> userEventsToImport)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  UserEventInlineSource inlineSource = UserEventInlineSource.newBuilder()
      .addAllUserEvents(userEventsToImport)
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setUserEventInlineSource(inlineSource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

Dati storici del catalogo

Puoi anche importare i dati storici del catalogo visualizzati negli eventi dell'utente storici. Questi dati storici del catalogo possono essere utili perché le informazioni sui prodotti passati possono essere utilizzate per arricchire gli eventi utente, il che può migliorare l'accuratezza del modello.

Per maggiori dettagli, vedi Importare i dati storici del catalogo.

Visualizzare gli eventi importati

Visualizza le metriche di integrazione degli eventi nella scheda Eventi della pagina Dati della console Ricerca per la vendita al dettaglio. Questa pagina mostra tutti gli eventi scritti o importati nell'ultimo anno. Potrebbero essere necessarie fino a 24 ore prima che le metriche vengano visualizzate dopo l'importazione dati.

Vai alla pagina Dati

Passaggi successivi

• Inizia a registrare gli eventi utente.
• Gestisci gli eventi utente.