Crea un'API intelligente per prevedere la propensione dei clienti all'acquisto utilizzando Apigee, BigQuery ML e Cloud Spanner

Last reviewed 2022-06-29 UTC

Questo tutorial mostra come creare un'API in grado di prevedere la probabilità che un cliente effettui un acquisto. Per creare l'API, utilizzi Apigee, BigQuery ML e Cloud Spanner.

Questo tutorial è destinato agli sviluppatori di API e agli esperti di dati che vogliono generare più entrate attraverso le piattaforme omnicanale ed e-commerce offrendo un'esperienza più personalizzata agli utenti. Si presume che tu abbia familiarità con BigQuery, Apigee, Google Cloud CLI e Apache Maven.

L'API che crei utilizza previsioni online per eseguire azioni in tempo reale in base al comportamento degli utenti sul tuo sito web. Le previsioni online combinano informazioni di machine learning con un catalogo dei prodotti e altre informazioni, consentendoti di creare un'esperienza migliore ai clienti su più canali. L'architettura dell'API che crei viene mostrata nel seguente diagramma:

Architettura di un'API per prevedere la propensione dei clienti all'acquisto.

Il diagramma mostra la seguente architettura:

  1. Un'applicazione per dispositivi mobili invia una richiesta all'API di cui è stato eseguito il deployment sulla piattaforma Apigee. La richiesta recupera i dati relativi ai consigli sui prodotti per l'utente che ha eseguito l'accesso.
  2. Un proxy API riceve i dati sui suggerimenti per i prodotti per l'ID utente da un set di dati BigQuery.
  3. Il proxy API crea un callout per recuperare i dati dal database principale del prodotto su un'istanza Cloud Spanner.
  4. Il proxy API aggrega i dati dei consigli sui prodotti e dei set di dati principali del prodotto.
  5. Viene restituita una risposta all'applicazione per dispositivi mobili.

Obiettivi

  • Creare un set di dati sulla propensione all'acquisto dei clienti in BigQuery.
  • Importa i dati del catalogo dei prodotti nel database Cloud Spanner.
  • Importa ed esegui il deployment del proxy API Apigee.
  • Integra i dati sulla propensione all'acquisto dei clienti provenienti da BigQuery con il catalogo dei prodotti e le informazioni sui prezzi nel database Cloud Spanner.
  • Crea una visualizzazione aggregata dei consigli sui prodotti.

Costi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

  • Slot flessibili BigQuery e BigQuery ML
  • Cloud Spanner
  • Apigee

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi utenti di Google Cloud possono essere idonei a una prova senza costi aggiuntivi.

Prima di iniziare

  1. Nella pagina del selettore di progetti della console Google Cloud, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

  2. Assicurati che la fatturazione sia attivata per il tuo progetto Google Cloud.

  3. Abilita le API AI Platform Training & Prediction, BigQuery, BigQuery Reservation, BigQuery Storage, Cloud Spanner, Cloud Storage, Cloud Storage API, Dataflow, Google Cloud, Cloud Storage JSON, Service Management, Service Usage.

    Abilita le API

  4. Nella console Google Cloud, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.

  5. Concedi i ruoli al tuo Account Google. Esegui questo comando una volta per ciascuno dei seguenti ruoli IAM:

    • roles/apigee.admin
    • roles/bigquery.user
    • roles/bigquery.dataViewer
    • roles/spanner.admin
    • roles/spanner.databaseAdmin
    • roles/resourcemanager.projectIamAdmin
    • roles/serviceusage.serviceUsageConsumer

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE
    • Sostituisci PROJECT_ID con l'ID progetto.
    • Sostituisci EMAIL_ADDRESS con il tuo indirizzo email.
    • Sostituisci ROLE con ogni singolo ruolo.
  6. Se non hai già un account Apigee X, configura Apigee per eseguire il provisioning di un'istanza Apigee X. Il provisioning può richiedere fino a un'ora.
  7. Configura la tua organizzazione Apigee X per consentire l'accesso esterno.

Una volta completate le attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la pagina Pulizia.

Crea un set di dati per i suggerimenti di e-commerce utilizzando BigQuery ML

In questa sezione vengono utilizzate query SQL standard in BigQuery ML per creare un modello ML, addestrarlo sui dati dei clienti in BigQuery e quindi eseguirne il deployment. Non è necessario esportare i dati o creare una pipeline di addestramento e deployment dei modelli. BigQuery scala automaticamente per gestire tutte le risorse di computing di cui hai bisogno.

Il modello di ML creato in questo tutorial utilizza la fattorizzazione a matrice, un metodo comune ed efficace per creare un sistema di suggerimenti basato sui dati di preferenza degli utenti.

In questo tutorial, utilizzi il set di dati di esempio di Google Analytics, che è ospitato pubblicamente su BigQuery. Questo set di dati fornisce 12 mesi (da agosto 2016 ad agosto 2017) di dati offuscati di Analytics 360 dal Google Merchandise Store, un negozio di e-commerce reale che vende prodotti con il brand Google.

Elaborare i dati di esempio

Quando utilizzi la fattorizzazione matrice, valuti il feedback degli utenti esplicito o implicito per determinare le preferenze dei clienti. Per utilizzare un feedback esplicito, il set di dati deve contenere dati sulle preferenze del prodotto dell'utente, come le valutazioni a stelle comprese tra 1 e 5. Se non è disponibile un feedback esplicito, devi utilizzare altre metriche di comportamento per dedurre le preferenze dei clienti, ad esempio per considerare il tempo totale trascorso da un utente su una pagina dei dettagli del prodotto. In questo tutorial vengono utilizzati i dati relativi alla durata delle sessioni per dedurre le preferenze dei clienti.

Per addestrare il modello di fattorizzazione della matrice, è necessaria una tabella con colonne che identificano il cliente, l'elemento che viene valutato e la valutazione implicita. In questa sezione, creerai una tabella di questo tipo con le colonne userid, itemId e session_duration. La colonna session_duration contiene la durata della sessione dell'utente sulla pagina del prodotto dell'articolo in questione.

Per creare la tabella utilizzando i dati del set di dati di esempio di Analytics:

  1. In Google Cloud Marketplace, vai alla pagina Esempio di Analytics.

    Vai all'esempio di Analytics

  2. Fai clic su Visualizza set di dati. Si apre la pagina dell'area di lavoro SQL di BigQuery in cui è selezionato il set di dati di esempio di Analytics.

  3. Nella sezione Explorer, accanto al progetto, fai clic su Visualizza azioni, poi fai clic su Crea set di dati.

  4. Nella finestra di dialogo Crea set di dati che viene visualizzata, procedi come segue:

    1. Nel campo ID set di dati inserisci bqml.
    2. Nell'elenco Località dei dati, seleziona us (più aree geografiche negli Stati Uniti).
    3. Fai clic su Crea set di dati.

  5. Fai clic su Vai al set di dati, quindi su Scrivi nuova query.

  6. Nell'Editor query, crea una tabella che contenga i dati di addestramento eseguendo la seguente istruzione SQL:

    CREATE OR REPLACE TABLE bqml.aggregate_web_stats AS (
  WITH
    durations AS (
      --calculate pageview durations
      SELECT
        CONCAT(fullVisitorId,'-',
             CAST(visitNumber AS STRING),'-',
             CAST(hitNumber AS STRING) ) AS visitorId_session_hit,
        LEAD(time, 1) OVER (
          PARTITION BY CONCAT(fullVisitorId,'-',CAST(visitNumber AS STRING))
          ORDER BY
          time ASC ) - time AS pageview_duration
      FROM
        `bigquery-public-data.google_analytics_sample.ga_sessions_2017*`,
        UNNEST(hits) AS hit
    ),
    prodview_durations AS (
      --filter for product detail pages only
     SELECT
        CONCAT(fullVisitorId,'-',CAST(visitNumber AS STRING)) AS userId,
        productSKU AS itemId,
        IFNULL(dur.pageview_duration,
         1) AS pageview_duration,
      FROM
        `bigquery-public-data.google_analytics_sample.ga_sessions_2017*` t,
        UNNEST(hits) AS hits,
        UNNEST(hits.product) AS hits_product
      JOIN
        durations dur
      ON
        CONCAT(fullVisitorId,'-',
               CAST(visitNumber AS STRING),'-',
               CAST(hitNumber AS STRING)) = dur.visitorId_session_hit
      WHERE
      eCommerceAction.action_type = "2"
    ),
    aggregate_web_stats AS(
      --sum pageview durations by userId, itemId
      SELECT
        userId,
        itemId,
        SUM(pageview_duration) AS session_duration
      FROM
        prodview_durations
      GROUP BY
        userId,
        itemId )
    SELECT
    *
   FROM
      aggregate_web_stats
);

    La tabella bqml.aggregate_web_stats viene creata e completata con i dati di addestramento.

  7. Per visualizzare un esempio dei dati, in Query Editor esegui la seguente istruzione SQL:

    SELECT
*
FROM
  bqml.aggregate_web_stats
LIMIT
  10;

L'output mostra una tabella con una riga per ogni ID utente che include l'ID elemento visualizzato dall'utente e la durata della sessione. L'output è simile al seguente:

Riga ID utente ID articolo durata_sessione
1 6703373209489429228-1 GGOEAXXX0808 19523
2 868731560082458910-1 GGOEAXXX0808 8312
3 4805474958539278422-1 GGOEAXXX0808 62892
4 8353360074725418910-3 GGOEAXXX0808 4883
5 8253742246691621007-2 GGOEAXXX0808 10
6 7211254729136975568-1 GGOEAXXX0808 96090
7 66777488032155805-1 GGOEAXXX0808 3893
8 0804312527321649470-1 GGOEAXXX0808 7539
9 2965429397557124425-1 GGOEAXXX0808 21776
10 8459600677575627508-1 GGOEAXXX0808 6265

Acquista slot flessibili

Se utilizzi i prezzi on demand per BigQuery, per addestrare un modello di fattorizzazione matriciale devi acquistare slot flessibili e quindi creare prenotazioni e assegnazioni. Se utilizzi il modello a costo fisso con BigQuery, puoi saltare questa sezione e andare a Creare, addestrare ed eseguire il deployment del modello.

Per acquistare slot flessibili, devi avere un ruolo IAM che includa l'autorizzazione bigquery.reservations.create. Questa autorizzazione viene concessa al proprietario del progetto e viene inclusa nei ruoli IAM Amministratore di BigQuery (roles/bigquery.admin) e Amministratore risorsa BigQuery (roles/bigquery.resourceAdmin).

  1. In Google Cloud Console, vai alla pagina BigQuery:

    Vai a BigQuery

  2. Fai clic su Gestione della capacità e poi su Prenotazioni.

  3. Se sei reindirizzato alla pagina API BigQuery Reservation per abilitare l'API, fai clic su Abilita. In caso contrario, vai al passaggio successivo.

  4. Nella scheda Prenotazioni, fai clic su Acquista slot.

  5. Nella pagina Acquista slot:

    1. Nell'elenco Durata impegno, seleziona Flex.
    2. Nell'elenco Località, seleziona us (più aree geografiche negli Stati Uniti).
    3. Nell'elenco Numero di slot, seleziona 500.
    4. Fai clic su Avanti.

    5. Nel campo Conferma di acquisto, digita CONFIRM e fai clic su Acquisto.

  6. Fai clic su Visualizza impegni slot.

    Attendi fino a 20 minuti per il provisioning della capacità. Dopo aver eseguito il provisioning della capacità, nella colonna Stato dell'impegno slot viene visualizzato .

  7. Fai clic su Crea prenotazione, quindi imposta le seguenti opzioni:

    1. In Nome prenotazione, inserisci model.
    2. Nell'elenco Località, seleziona us (più aree geografiche negli Stati Uniti).
    3. In Numero di slot, inserisci 500.
    4. Fai clic su Salva. In questo modo tornerai alla pagina Prenotazioni.

  8. Accanto alla prenotazione model, nella colonna Azioni, seleziona Crea assegnazione.

  9. In Seleziona un'organizzazione, una cartella o un progetto, fai clic su Sfoglia.

  10. Inserisci il nome del progetto in cui stai completando questo tutorial o selezionalo dall'elenco.

  11. Fai clic su Seleziona, quindi su Crea.

Crea, addestra e sottoponi a deployment il modello

Per creare, addestrare ed eseguire il deployment del modello di fattorizzazione della matrice, procedi nel seguente modo:

  1. Nella pagina BigQuery di Google Cloud Console, fai clic su Scrivi nuova query.

  2. Esegui l'istruzione SQL CREATE MODEL:

    CREATE OR REPLACE MODEL bqml.retail_recommender`
  OPTIONS(model_type='matrix_factorization',
        user_col='userId',
        item_col='itemId',
        rating_col='session_duration',
        feedback_type='implicit'
        )
  AS
  SELECT * FROM bqml.aggregate_web_stats;

Una volta completato l'addestramento, viene eseguito il deployment del modello addestrato come bqml.retail_recommender.

Utilizza il modello addestrato per fare previsioni

In questa sezione, per ottenere le previsioni dal modello bqml.retail_recommender di cui è stato eseguito il deployment, utilizza la funzione SQL di ML.RECOMMEND.

  1. Nella pagina BigQuery di Google Cloud Console, scrivi una query e ottieni le previsioni che rappresentano i cinque consigli principali per un userId specificato:

    DECLARE MY_USERID STRING DEFAULT "0824461277962362623-1";

SELECT
 *
FROM
  ML.RECOMMEND(MODEL `bqml.retail_recommender`,
  (SELECT MY_USERID as userID)
              )
ORDER BY predicted_session_duration_confidence DESC
LIMIT 5;

    L'output mostra una riga relativa alla durata prevista della sessione prevista (più alta è meglio), l'ID utente associato e l'ID elemento visualizzati dall'utente. L'output è simile al seguente:

    Riga previsione_durata_sessione_prevista ID utente ID articolo
    1 29011.10454702254 0824461277962362623-1 GGOEGAAX0574
    2 28212,99840462358 0824461277962362623-1 GGOEGDHQ015399
    3 28126,79442866013 0824461277962362623-1 GGOEGETR014599
    4 27303.60852083874 0824461277962362623-1 GGOEGAAX0338
    5 25692.370609851147 0824461277962362623-1 GGOEGEFR024199

  2. Per ottenere le prime 5 previsioni per tutti gli utenti, esegui la seguente istruzione SQL. L'istruzione genera molte righe, quindi l'output viene scritto in una tabella e vengono recuperati i primi dieci record, in modo che tu possa visualizzare un esempio dei dati.

    -- Create output table of top 5 predictions
CREATE OR REPLACE TABLE bqml.prod_recommendations AS (
WITH predictions AS (
    SELECT
      userId,
      ARRAY_AGG(STRUCT(itemId,
                       predicted_session_duration_confidence)
                ORDER BY
                  predicted_session_duration_confidence DESC
                LIMIT 5) as recommended
    FROM ML.RECOMMEND(MODEL bqml.retail_recommender)
    GROUP BY userId
)
SELECT
  userId,
  itemId,
  predicted_session_duration_confidence
FROM
  predictions p,
  UNNEST(recommended)
);
-- Show table
SELECT
*
FROM
  bqml.prod_recommendations
ORDER BY
  userId
LIMIT
  10;

    L'output mostra più ID utente, l'ID elemento visualizzato dall'utente e la durata prevista della sessione prevista. L'output è simile al seguente:

    Riga ID utente ID articolo previsione_durata_sessione_prevista
    1 000170187170673177-6 GGOEGDHQ015399 15931,156936770309
    2 000170187170673177-6 GGOEGAAX0574 20178.608474922632
    3 000170187170673177-6 GGOEGAAX0338 20247,337545389437
    4 000170187170673177-6 GGOEGETR014599 15524,355852692066
    5 000170187170673177-6 GGOEGEFR024199 16443,307099088597
    6 000338059556124978-1 GGOEGAAX0338 18143,067737280064
    7 000338059556124978-1 GGOEGAAX0279 16531.718889063464
    8 000338059556124978-1 GGOEGAAX0574 20916,672241880347
    9 000338059556124978-1 GGOEGETR014599 16155.674211782945
    10 000338059556124978-1 GGOEGEFR024199 18417,17554202264

Configurare i dati di Cloud Spanner

Nelle sezioni seguenti di questo tutorial, utilizzerai gcloud CLI e Maven. Puoi eseguire i comandi per entrambi gli strumenti da Cloud Shell. Non è richiesta alcuna installazione per utilizzare gli strumenti.

  1. In Cloud Shell, clona il repository GitHut dei consigli sui prodotti contenente il bundle proxy e gli script dell'API Product-recommendations per configurare i dati in un database Cloud Spanner:

    git clone https://github.com/apigee/devrel/tree/main/references/product-recommendations
cd product-recommendations-v1

  2. Creare l'account di servizio datareader e assegnarvi ruoli IAM. L'account di servizio viene utilizzato per accedere ai dati in BigQuery e al database Cloud Spanner dal proxy API.

    gcloud iam service-accounts create datareader --display-name="Data reader for BigQuery and Spanner Demo"
gcloud iam service-accounts list | grep datareader
gcloud iam service-accounts create datareader --display-name="Data reader for Apigee, BigQuery, and Spanner Demo"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/spanner.databaseUser" --quiet
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/spanner.databaseReader" --quiet
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/bigquery.dataViewer" --quiet
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/bigquery.user" --quiet

  3. Imposta le variabili di ambiente:

    # For ApigeeX
export PROJECT_ID=APIGEEX_PROJECT
export ORG=$PROJECT_ID
export ENV=eval
export ENVGROUP_HOSTNAME=API_DOMAIN_NAME
export SA=datareader@$PROJECT_ID.iam.gserviceaccount.com

# For Cloud Spanner
export SPANNER_INSTANCE=product-catalog
export SPANNER_DATABASE=product-catalog-v1
export REGION=regional-us-east1

    Sostituisci quanto segue:

    • APIGEEX_PROJECT: il nome del tuo progetto Apigee X.
    • API_DOMAIN_NAME: il nome host configurato nella pagina Amministratori > Ambienti > dell'interfaccia utente di Apigee X.

  4. Nella pagina BigQuery di Google Cloud Console, seleziona la tabella prod_recommendations, quindi fai clic sulla scheda Anteprima per visualizzare i risultati.

    1. Copia qualsiasi valore di userId.

    2. In Cloud Shell, imposta una variabile di ambiente:

      export CUSTOMER_USERID=USER_ID

      Sostituisci USER_ID con il valore userId che hai copiato nel passaggio precedente.

  5. In Cloud Shell, mostra i risultati dei consigli sui prodotti ordinati per il valore CUSTOMER_USERID specificato:

    bq query --nouse_legacy_sql \
    "SELECT * FROM \`$PROJECT_ID.bqml.prod_recommendations\` AS A where A.userid = \"$CUSTOMER_USERID\"" \
    ORDER BY A.predicted_session_duration_confidence DESC

    L'output mostra un singolo ID utente, l'ID elemento visualizzato dall'utente e la durata prevista della sessione. L'output è simile al seguente:

    +-----------------------+----------------+--------------------------------------------+
|        userId         |     itemId     |      predicted_session_duration_confidence |
+-----------------------+----------------+--------------------------------------------+
| 6929470170340317899-1 | GGOEGAAX0037   |                          40161.10446942589 |
| 6929470170340317899-1 | GGOEYDHJ056099 |                          27642.28480729123 |
| 6929470170340317899-1 | GGOEGAAX0351   |                         27204.111219270915 |
| 6929470170340317899-1 | GGOEGDWC020199 |                         25863.861349754334 |
| 6929470170340317899-1 | GGOEGAAX0318   |                         24585.509088154067 |
+-----------------------+----------------+--------------------------------------------+

Creare un database Cloud Spanner e importare i dati del catalogo dei prodotti

  1. In Cloud Shell, crea un'istanza di Cloud Spanner nell'area geografica specificata, crea il database del catalogo dei prodotti e importa i dati:

    ./setup_spanner.sh

    Lo script utilizza la variabile di ambiente CUSTOMER_USERID e visualizza le voci che sono state create.

    Il catalogo dei prodotti Cloud Spanner contiene solo gli elementi utilizzati nel passaggio di addestramento di BigQuery per un utente specifico. Di conseguenza, se modifichi la variabile di ambiente CUSTOMER_USERID dopo aver creato i dati del catalogo dei prodotti nel database Cloud Spanner, devi eseguire nuovamente lo script della shell setup_spanner.sh per ricompilare i dati.

  2. Verifica i dati nel database Cloud Spanner:

    gcloud spanner databases execute-sql $SPANNER_DATABASE --sql='SELECT * FROM products'

    L'output mostra gli ID prodotto e le informazioni descrittive presenti nel catalogo dei prodotti Spanner, inclusi il prezzo e il percorso dell'immagine. L'output è simile al seguente:

    productid       name                description                price  discount  image
GGOEGAAX0037    Aviator Sunglasses  The ultimate sunglasses    42.42  0         products_Images/sunglasses.jpg
GGOEGAAX0318    Bamboo glass jar    Bamboo glass jar           19.99  0         products_Images/bamboo-glass-jar.jpg
GGOEGAAX0351    Loafers             Most comfortable loafers   38.99  0         products_Images/loafers.jpg
GGOEGDWC020199  Hair dryer          Hottest hair dryer         84.99  0         products_Images/hairdryer.jpg
GGOEYDHJ056099  Coffee Mug          Best Coffee Mug            4.2    0         products_Images/mug.jpg

Esegui il deployment del proxy Apigee

In questa sezione esegui un comando Maven per creare le seguenti risorse:

  • Un proxy con nome product-recommendations-v1
  • Un prodotto API denominato product-recommendations-v1-$ENV
  • Un utente dello sviluppatore di app di nome demo@any.com
  • Un'app chiamata product-recommendations-v1-app-$ENV

Per creare le risorse, Maven utilizza il file pom.xml del repository GitHub. Il file contiene le istruzioni e i passaggi per l'installazione.

La sezione del profilo del file pom.xml contiene valori per apigee.org, apigee.env, api.northbound.domain, gcp.projectid, googletoken.email e api.userid. Questi valori variano in base al progetto e vengono impostati utilizzando la riga di comando. L'esempio seguente mostra la sezione del file pom.xml che contiene i valori:

<profile>
  <id>eval</id>
  <properties>
    <apigee.profile>eval</apigee.profile>
    <apigee.org>${apigeeOrg}</apigee.org>
    <apigee.env>${apigeeEnv}</apigee.env>
    <api.northbound.domain>${envGroupHostname}</api.northbound.domain>
    <gcp.projectid>${gcpProjectId}</gcp.projectid>
<apigee.googletoken.email>${googleTokenEmail}</apigee.googletoken.email>
    <api.userid>${customerUserId}</api.userid>
  </properties>
</profile>

Puoi impostare questi valori in precedenza durante la configurazione dei dati di Cloud Spanner.

Per eseguire il deployment del proxy, procedi come segue:

  • In Cloud Shell, installa il proxy e gli artefatti associati, quindi testa l'API:

    mvn -P eval clean install -Dbearer=$(gcloud auth print-access-token) \
    -DapigeeOrg=$ORG \
    -DapigeeEnv=$ENV \
    -DenvGroupHostname=$ENVGROUP_HOSTNAME \
    -DgcpProjectId=$PROJECT_ID \
    -DgoogleTokenEmail=$SA \
    -DcustomerUserId=$CUSTOMER_USERID

    L'output mostra l'esecuzione dei passaggi di installazione e i risultati delle chiamate API del test di integrazione. C'è una chiamata all'endpoint /openapi e un'altra all'endpoint /products. I risultati del test verificano che il proxy API sia stato installato, sottoposto a deployment e che sia operativo. L'output mostra anche le credenziali dell'app, che puoi utilizzare per le chiamate di prova API successive.

Testare l'API Recommendations

  1. In Cloud Shell, imposta una variabile di ambiente per la chiave API dell'app effettuando una chiamata curl all'API Apigee:

    APIKEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://apigee.googleapis.com/v1/organizations/$ORG/developers/demo@any.com/apps/product-recommendations-v1-app-$ENV \
    | jq -r .credentials[0].consumerKey)

    Prendi nota del valore APIKEY, avrai bisogno di queste informazioni se crei un'app AppSheet facoltativamente in un secondo momento.

  2. Per ottenere i risultati per il valore CUSTOMER_USERID specificato quando hai installato il proxy API, effettua una chiamata di prova:

    curl -s https://$ENVGROUP_HOSTNAME/v1/recommendations/products \
-H "x-apikey:$APIKEY" | jq

L'API definita dalla specifica OpenAPI consente alla richiesta di specificare le intestazioni seguenti:

  • x-apikey: la chiave consumer dell'app dello schema di sicurezza.
  • x-userid: l'identificatore utente che effettua la richiesta. Se non specificato, il valore predefinito è il valore CUSTOMER_USERID configurato nel proxy.
  • cache-control: il periodo di tempo nella cache della risposta. Questa intestazione consente di memorizzare nella cache la risposta per 300 secondi o di eseguire l'override di no-cache.

Per modificare il valore CUSTOMER_USERID o controllare la memorizzazione nella cache, puoi impostare i valori dell'intestazione come mostrato nell'esempio di chiamata seguente:

curl -s "https://$ENVGROUP_HOSTNAME/v1/recommendations/products" \
-H "x-apikey:$APIKEY" \
-H "x-userid:$CUSTOMER_USERID" \
-H "Cache-Control:no-cache" | jq

La risposta alla chiamata di esempio è simile alla seguente:

{
  "products": [
    {
      "productid": "GGOEGAAX0037",
      "name": "Aviator Sunglasses",
      "description": "The ultimate sunglasses",
      "price": "42.42",
      "image": "products_Images/sunglasses.jpg"
    },
    {
      "productid": "GGOEYDHJ056099",
      "name": "Coffee Mug",
      "description": "Best Coffee Mug",
      "price": "4.2",
      "image": "products_Images/mug.jpg"
    },
    {
      "productid": "GGOEGAAX0351",
      "name": "Loafers",
      "description": "Most comfortable loafers",
      "price": "38.99",
      "image": "products_Images/loafers.jpg"
    },
    {
      "productid": "GGOEGDWC020199",
      "name": "Hairdryer",
      "description": "Hotest hairdryer",
      "price": "84.99",
      "image": "products_Images/hairdryer.jpg"
    },
    {
      "productid": "GGOEGAAX0318",
      "name": "Bamboo glass jar",
      "description": "Bamboo glass jar",
      "price": "19.99",
      "image": "products_Images/bamboo-glass-jar.jpg"
    }
  ]
}

Criteri Apigee

I criteri Apigee elencati nelle seguenti sezioni vengono utilizzati nel bundle proxy dell'API in questo tutorial.

Pre-flusso

SpikeArrest
Proteggi il servizio BigQuery di backend dai picchi di traffico.
Quota
Limita le richieste API in base all'applicazione e allo sviluppatore consumer. I limiti di limitazione sono configurati nel prodotto API.
ResponseCache - URI
Riduci le richieste al data warehouse BigQuery memorizzando nella cache la risposta dal servizio.

Flusso di prodotti

AssegnaMessage - Creazione richiesta di query
Imposta la richiesta HTTP con una query SQL per recuperare l'elenco dei suggerimenti sul prodotto dal set di dati BigQuery.
Norme JavaScript ed ExtractVariable
Formatta i dati del servizio BigQuery e crea un messaggio di risposta più facile da usare.
SearchCache - Sessione Cloud Spanner
Cerca l'ID sessione del database Cloud Spanner dalla cache di Apigee.
ServiceCallout - Sessione Cloud Spanner
Fai una richiesta al servizio Cloud Spanner e crea una sessione di database se la cache di Apigee non ha un ID sessione o l'ID è scaduto.
PopulateCache - Sessione Cloud Spanner
Completa l'ID sessione di Cloud Spanner nella cache di Apigee.
ServiceCallout - ricerca nel catalogo dei prodotti
Recupera i dettagli del prodotto dal database del catalogo dei prodotti Cloud Spanner.
JavaScript: formato dei dati di prodotto
Crea un messaggio di risposta dell'API conforme all'OAS formattando i dati del database di prodotti.

Flusso OpenAPI

AssegnaMessaggio - JSON OAS
Imposta la risposta JSON OAS per l'API.

(Facoltativo) Creare un'app AppSheet utilizzando Apigee come origine dati.

Per mostrare i consigli sui prodotti agli utenti finali dei siti web di e-commerce e agli utenti aziendali, puoi creare un'app AppSheet come illustrato in questa sezione.

Creare un account AppSheet

Crea un account AppSheet utilizzando il tuo indirizzo email.

Creare un'origine dati

AppSheet utilizza il proxy API come origine dati per la nuova app. Per creare un'origine dati, procedi nel seguente modo:

  1. Accedi ad AppSheet.
  2. Nella pagina Il mio account, fai clic su Origini > Nuova origine dati.
  3. Nella finestra di dialogo Aggiungi una nuova origine dati, inserisci il nome del proxy product-recommendations-v1, quindi fai clic su Apigee.

  4. Nella finestra di dialogo Aggiungi informazioni sulla connessione dell'API Apigee, imposta le seguenti opzioni:

    1. Seleziona Manuale.
    2. Nel campo Chiave API Apigee, inserisci la chiave API dell'app, che hai utilizzato per testare il proxy. Se non hai la chiave API, recuperala in Cloud Shell eseguendo echo $APIKEY.

    3. Nel campo Percorso base API Apigee, inserisci quanto segue:

      https://ENVGROUP_HOSTNAME/v1/recommendations

      Sostituisci ENVGROUP_HOSTNAME con il nome host configurato nell'interfaccia utente di Apigee X per Admin > Ambienti> Gruppi.

    4. Nel campo API Resource Paths (Percorsi risorse risorsa), inserisci il suffisso del percorso products.

    5. Fai clic su Test.

    6. Al termine dei test, fai clic su Autorizza accesso.

Dopo aver autorizzato l'accesso, la console di AppSheet mostra un nuovo riquadro per product-recommendations-v1.

Crea l'app

  1. Vai alla pagina dell'app del modello di prodotto di AppSheet.
  2. Fai clic su Copia e personalizza. Viene visualizzata la finestra di dialogo Clona l'app.
  3. Nel campo Nome app, inserisci il nome del proxy, product-recommendations-v1, quindi fai clic su Copia app. Attendi qualche istante per la creazione della tua app.
  4. Nella pagina Ti diamo il benvenuto nella tua app, fai clic su Personalizza app. Per impostazione predefinita, l'app utilizza un'origine dati di esempio in un foglio Google.

  5. Modifica l'origine dati in modo che corrisponda all'origine dati Apigee che hai creato in precedenza:

    1. Fai clic su + Nuova tabella e poi su Consigli sui prodotti v1.
    2. Nella finestra di dialogo Scegli un foglio/una tabella, seleziona Prodotti.
    3. Nella finestra di dialogo Crea una nuova tabella, fai clic su Sola lettura, quindi su Aggiungi questa tabella.

    L'app viene visualizzata con una scheda prodotti 2 e una visualizzazione dati diversa. La nuova visualizzazione dati contiene valori diversi per la descrizione e il prezzo di ciascun articolo. Tieni presente che l'ordine degli articoli non corrisponde all'ordine delle previsioni.

  6. Modifica l'ordine di restituzione degli elementi dall'origine dati rimuovendo l'ordinamento predefinito di AppSheet:

    1. Nel menu di navigazione laterale, seleziona UX.
    2. Nella sezione Visualizzazioni principali, seleziona prodotti 2.
    3. Nella sezione Opzioni di visualizzazione, accanto a Ordina per, elimina la voce nome, Crescente. Osserva che l'ordine visualizzato in AppSheet è ora lo stesso risultato della chiamata API, con l'ultimo elemento della risposta in basso.

  7. Salva l'app.

Facoltativamente, puoi eliminare la tabella dei prodotti e l'esperienza utente originali e rinominare la tabella "products 2" e visualizzare la sezione "Consigli dei prodotti".

Esegui la pulizia

Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

  1. Nella console Google Cloud, vai alla pagina Gestisci risorse.

    Vai a Gestisci risorse

  2. Nell'elenco dei progetti, seleziona il progetto che vuoi eliminare, quindi fai clic su Elimina.
  3. Nella finestra di dialogo, digita l'ID del progetto e fai clic su Chiudi per eliminare il progetto.

Elimina le singole risorse

Per evitare costi ricorrenti, elimina le prenotazioni degli slot flessibili di BigQuery, il set di dati BigQuery e il modello AI Platform.

Elimina le prenotazioni di slot flessibili di BigQuery

  1. Nella pagina BigQuery di Google Cloud Console, seleziona Gestione della capacità, quindi fai clic sulla scheda Prenotazioni.
  2. Apri la voce model.
  3. Accanto alla prenotazione, fai clic su Visualizza azioni, quindi fai clic su Elimina.
  4. Accanto alla voce model, fai clic su Visualizza azioni, poi fai clic su Elimina.

  5. In Cloud Shell, elimina il deployment, il proxy e gli artefatti associati:

    mvn -P eval process-resources -Dbearer=$(gcloud auth print-access-token) \
    -DapigeeOrg=$ORG -DapigeeEnv=$ENV -Dskip.integration=true \
    apigee-config:apps apigee-config:apiproducts apigee-config:developers -Dapigee.config.options=delete \
    apigee-enterprise:deploy -Dapigee.options=clean

  6. Rimuovi le risorse Spanner:

    ./cleanup_spanner.sh

Elimina il set di dati BigQuery

  1. Nella sezione Risorse della pagina BigQuery di Google Cloud Console, espandi il progetto in cui hai completato il tutorial.
  2. Seleziona il set di dati bqml, quindi fai clic su Elimina set di dati.
  3. Nella finestra dell'overlay visualizzata, inserisci bqml e fai clic su Elimina.

Elimina il modello AI Platform

  1. Nella console Google Cloud, vai alla pagina Modelli AI Platform.

    Vai ai modelli di AI Platform

  2. Nell'elenco dei modelli, fai clic su rpm_bqml_model.

  3. Nella pagina Dettagli modello, seleziona la casella di controllo per la versione V_1 (predefinita).

  4. Fai clic su Altro e poi su Elimina.

  5. Una volta terminata l'eliminazione della versione, fai clic su Indietro per tornare all'elenco dei modelli.

  6. Seleziona la casella di controllo per il modello rpm_bqml_model.

  7. Fai clic su Altro e poi su Elimina.

  8. In Cloud Shell, elimina l'account di servizio:

    gcloud iam service-accounts delete $SA

Passaggi successivi