Esportare i dati in BigQuery

Questa pagina descrive come caricare i dati degli eventi utente e dei prodotti retail in BigQuery. Una volta portati i tuoi dati in BigQuery, potrai utilizzarli per eseguire le previsioni di vendita con Vertex AI e visualizzare i dati nelle dashboard Looker predefinite.

Se i dati di vendita al dettaglio sono già nelle tabelle di eventi di prodotto e utente in BigQuery, nel formato dell'API Retail puoi saltare questa pagina e andare direttamente su Ottenere dashboard che mostrano gli indicatori chiave di prestazione e Generare previsioni di vendita dai dati di vendita al dettaglio. Per maggiori informazioni sul formato dell'API BigQuery Retail, consulta Schema retail e Informazioni sugli eventi utente.

Prima di iniziare

Prima di poter esportare i tuoi dati di vendita al dettaglio in BigQuery:

Devi aver completato le procedure indicate in Prima di iniziare. Questo include l'importazione delle informazioni del catalogo e degli eventi utente.

Per ulteriori informazioni sull'importazione, vedi:
Contatta il tuo account manager Google per ottenere l'inserimento nella lista consentita per l'esportazione dell'API Retail.

Crea un set di dati in BigQuery

Devi creare uno o due set di dati in BigQuery per archiviare i tuoi dati su eventi e prodotti. Puoi utilizzare un set di dati per contenere entrambi i tipi di dati oppure crearne due, uno per ogni tipo.

Devi creare i set di dati nello stesso progetto in cui hai implementato l'API Retail.

Se non hai mai utilizzato BigQuery nel progetto dell'API Retail, abilita l'API BigQuery e assicurati di disporre del ruolo IAM che consente di creare set di dati e tabelle.

Vedi Prima di iniziare e Controllo dell'accesso con IAM nella documentazione di BigQuery.
Crea un set di dati in BigQuery nell'area a più regioni USA (più regioni negli Stati Uniti). Ad esempio, nominala retail_data. Se crei il tuo set di dati in una regione diversa, l'esportazione dei dati in BigQuery non va a buon fine.

Per informazioni sulla creazione di un set di dati, consulta Creazione di set di dati nella documentazione di BigQuery.

Questo set di dati verrà utilizzato per archiviare le tabelle di dati che esporti. Le seguenti procedure descrivono come esportare.
(Facoltativo) Per inserire i dati sugli eventi utente in un set di dati separato dai dati di prodotto, crea un secondo set di dati. Ad esempio, assegnagli il nome retail_user_event_data.

Esportare il catalogo Retail in una tabella BigQuery

Utilizza il metodo products.export per esportare il catalogo al dettaglio in una tabella BigQuery.

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all' interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login, oppure utilizzando Cloud Shell, che esegue automaticamente l'accesso all'interfaccia a riga di comando di gcloud.

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

PROJECT_ID: l'ID del progetto dell'API Retail in cui hai creato il set di dati BigQuery.
BRANCH_ID: l'ID del ramo catalogo. Utilizza default_branch per recuperare dati dal ramo predefinito. Per saperne di più, consulta Ramo catalogo.
DATASET_ID: il nome del set di dati creato in Crea un set di dati in BigQuery. Ad esempio, utilizza retail_data o retail_product_data.
TABLE_ID_PREFIX: un prefisso per l'ID tabella. Il prefisso non può essere una stringa vuota. Per completare il nome della tabella viene aggiunto un suffisso retail_products. Ad esempio, se il prefisso è test, il nome della tabella è test_retail_products.

Corpo JSON richiesta:

{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

curl (Linux, macOS o Cloud Shell)

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:

cat > request.json << 'EOF'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
EOF

Quindi, esegui il comando seguente per inviare la richiesta REST:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/branches/BRANCH_ID/products:export"

PowerShell (Windows)

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:

@'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi, esegui il comando seguente per inviare la richiesta REST:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/branches/BRANCH_ID/products:export" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/operations/17986570020347019923",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ExportProductsResponse",
    "outputResult": {
      "bigqueryResult": [
        {
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID_PREFIX_retail_products"
        }
      ]
    }
  }
}

Esportare gli eventi utente in una tabella BigQuery

Utilizza il metodo userEvents.export per esportare gli eventi utente di vendita al dettaglio in una tabella BigQuery:

Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

PROJECT_ID: l'ID del progetto dell'API Retail in cui hai creato il set di dati BigQuery.
DATASET_ID: il nome del set di dati creato in Creare un set di dati in BigQuery. Ad esempio, utilizza retail_data o retail_product_data.
TABLE_ID_PREFIX: un prefisso per l'ID tabella. Il prefisso non può essere una stringa vuota. Per completare il nome della tabella viene aggiunto un suffisso retail_products. Ad esempio, se il prefisso è test, il nome della tabella è test_retail_products.

Corpo JSON richiesta:

{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}

Per inviare la richiesta, espandi una delle seguenti opzioni:

curl (Linux, macOS o Cloud Shell)

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:

cat > request.json << 'EOF'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
EOF

Quindi, esegui il comando seguente per inviare la richiesta REST:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:export"

PowerShell (Windows)

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory attuale:

@'
{
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Quindi, esegui il comando seguente per inviare la richiesta REST:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:export" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/17203443067109586170",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2alpha.ExportUserEventsResponse",
    "outputResult": {
      "bigqueryResult": [
        {
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID_PREFIX_retail_user_events"
        }
      ]
    }
  }
}

Informazioni sui dati esportati

Ecco alcune cose da sapere sui dati di vendita al dettaglio che esporti nelle tabelle BigQuery:

I dati esportati nelle tabelle BigQuery nel progetto API Retail sono viste autorizzate, non viste materializzate.
Non puoi modificare o aggiornare i dati in queste tabelle.
I dati vengono aggiornati in base alla pianificazione concordata con l'account manager.

Informazioni sui dati sugli eventi utente esportati

Di seguito sono riportate le informazioni sui prodotti incluse nei dati sugli eventi utente esportati.

Informazioni sui prezzi dei prodotti

Il modo in cui le informazioni sui prezzi dei prodotti vengono restituite dal metodo userEvents.export dipende da quanto segue:

Hai incluso informazioni sui prezzi nei dati degli eventi utente al momento dell'importazione da parte dell'API Retail. Quando chiami il metodo userEvents.export, il prezzo restituito con un evento utente è il prezzo del prodotto al momento dell'evento.
Non hai incluso le informazioni sui prezzi nei dati sugli eventi utente, ma hai incluso queste informazioni nei dati di prodotto al momento dell'importazione da parte dell'API Retail. Quando chiami il metodo userEvents.export, il prezzo restituito con un evento utente non è necessariamente il prezzo del prodotto al momento dell'evento. È il prezzo indicato nei dati di prodotto al momento dell'importazione da parte dell'API Retail.
Non hai incluso le informazioni sui prezzi nei dati sugli eventi utente e non sono disponibili informazioni sui prezzi nei dati di prodotto. Quando chiami il metodo userEvents.export, non viene restituito alcun prezzo con gli eventi utente.

Altre informazioni sul prodotto

Tutte le informazioni sui prodotti (tranne il prezzo) vengono aggiunte alle informazioni sugli eventi utente nel momento in cui chiami il metodo userEvents.export. I valori dei prodotti possono variare dal momento dell'evento utente al momento della chiamata al numero userEvents.export. Per questo motivo, i valori dei prodotti diversi dai prezzi restituiti nella tabella degli eventi utente potrebbero essere diversi dai valori dei prodotti al momento dell'evento utente.

(Facoltativo) Verifica che le nuove tabelle siano in BigQuery

Dopo aver esportato i dati di prodotto e quelli degli eventi utente in BigQuery, assicurati che siano presenti nuove tabelle.

In BigQuery, vai al set di dati o ai set di dati che hai creato in Creare un set di dati in BigQuery.
Apri i set di dati e assicurati di vedere le due tabelle esportate. Ad esempio, cerca le tabelle con nomi che terminano con retail_products e retail_user_events.