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

Questo tutorial illustra come creare un'API che possa prevedere la probabilità con cui un cliente effettui un acquisto. Per creare l'API, devi utilizzare Apigee, BigQuery ML e Cloud Spanner.

Questo tutorial è destinato agli sviluppatori di API e agli esperti di dati che vogliono generare più entrate tramite le piattaforme omnicanale ed e-commerce, fornendo un'esperienza più personalizzata agli utenti. Presuppone la tua conoscenza di BigQuery, Apigee, interfaccia a riga di comando di Google Cloud e Apache Maven.

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

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

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 relativi ai suggerimenti sui prodotti per lo User-ID 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 provenienti dai consigli sui prodotti e dai set di dati principali dei prodotti.
  5. Viene restituita una risposta all'applicazione per dispositivi mobili.

Obiettivi

  • Creare un set di dati di propensione all'acquisto di 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 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

Questo tutorial utilizza i seguenti componenti fatturabili di Google Cloud:

  • Slot flessibili di 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 beneficiare di una prova gratuita.

Prima di iniziare

  1. Nella pagina del selettore dei progetti in Google Cloud Console, seleziona o crea un progetto Google Cloud.

    Vai al selettore progetti

  2. Assicurati che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata su un progetto.

  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, attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console, viene avviata una sessione di Cloud Shell e viene visualizzato 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 corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

  5. Concedi i ruoli per il tuo Account Google. Esegui una volta il comando seguente 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.

Al termine di questo tutorial, puoi evitare una fatturazione continua eliminando le risorse che hai creato. Per scoprire di più, vedi Pulizia.

Creare un set di dati di suggerimenti per l'e-commerce utilizzando BigQuery ML

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

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

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

Elaborare i dati di esempio

Quando utilizzi la fattorizzazione della matrice, valuti il feedback esplicito o implicito dell'utente 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 tra 1 e 5. Se non sono disponibili feedback espliciti, devi utilizzare altre metriche di comportamento per dedurre le preferenze dei clienti, ad esempio il tempo totale trascorso da un utente su una pagina dei dettagli del prodotto. In questo tutorial utilizzerai i dati sulla durata delle sessioni per dedurre le preferenze dei clienti.

Per addestrare il modello di fattorizzazione della matrice, devi avere una tabella con colonne che identificano il cliente, l'elemento che viene valutato e la valutazione implicita. In questa sezione, crei una tabella di questo tipo con le colonne userid, itemId e session_duration. La colonna session_duration contiene la durata della sessione dell'utente nella pagina del prodotto dell'elemento 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 SQL. Con il set di dati di esempio di Analytics selezionato.

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

  4. Nella finestra di dialogo Crea set di dati visualizzata, procedi nel seguente modo:

    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 Crea nuova query.

  6. Nell'Editor query, crea una tabella contenente 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 compilata con i dati di addestramento.

  7. Per visualizzare un esempio dei dati, nell'Editor query esegui la seguente istruzione SQL:

    SELECT
    *
    FROM
      bqml.aggregate_web_stats
    LIMIT
      10;
    

L'output mostra una tabella che contiene 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 sessione_duration
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 prezzi on demand per BigQuery, per addestrare un modello di fattorizzazione matrice, devi acquistare slot flessibili e quindi creare prenotazioni e assegnazioni. Se utilizzi il modello a costo fisso con BigQuery, puoi ignorare 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 di risorse BigQuery (roles/bigquery.resourceAdmin).

  1. Nella console, vai alla pagina BigQuery:

    Vai a BigQuery

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

  3. Se hai effettuato il reindirizzamento alla pagina BigQuery Reservation API per abilitare l'API, fai clic su Enable (Attiva). Altrimenti, procedi al passaggio successivo.

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

  5. Nella pagina Acquista slot, procedi nel seguente modo:

    1. Nell'elenco Durata dell'impegno, seleziona Flessibile.
    2. Nell'elenco Località, seleziona us (più aree geografiche negli Stati Uniti).
    3. Nell'elenco Numero di slot, seleziona 500.
    4. Tocca Avanti.
    5. Nel campo Conferma acquisto, digita CONFIRM e fai clic su Acquisto.

  6. Fai clic su Visualizza impegni di slot.

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

  7. Fai clic su Crea prenotazione e 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 con 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, poi su Crea.

Crea, addestra ed esegui il deployment del modello

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

  1. Nella pagina BigQuery della console, fai clic su Crea 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 modello 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 ML.RECOMMEND.

  1. Nella pagina BigQuery della console, scrivi una query e ottieni previsioni che rappresentano i 5 consigli principali per un utenteId 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;
    

    Nell'output è visualizzata una riga relativa alla durata della sessione prevista (maggiore è il valore più alto), l'ID utente associato e l'ID elemento visualizzato dall'utente. L'output è simile al seguente:

    Riga previsione_durata_sessione_previsione 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 visualizzare 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 da poter 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_previsione
    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

Le sezioni seguenti di questo tutorial utilizzano l'interfaccia a riga di comando gcloud e Maven. Esegui 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 per i consigli sui prodotti contenente il bundle proxy e gli script Product-recommendations per la configurazione dei dati in un database Cloud Spanner:

    git clone https://github.com/apigee/devrel/tree/main/references/product-recommendations
    cd product-recommendations-v1
    
  2. Crea l'account di servizio datareader e assegnagli i ruoli IAM. L'account di servizio viene utilizzato per accedere ai dati in BigQuery e nel 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 > Gruppi nella UI di Apigee X.
  4. Nella pagina BigQuery della console, seleziona la tabella prod_recommendations e 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 ordinati per i suggerimenti sui prodotti 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 di catalogo del prodotto e importa i dati:

    ./setup_spanner.sh
    

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

    Il catalogo prodotti di 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 prodotti nel database Cloud Spanner, devi ripetere lo script 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 di Spanner, inclusi prezzo e 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 eseguirai un comando Maven per creare le seguenti risorse:

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

Per creare le risorse, Maven utilizza il file pom.xml del repository di 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>

Questi valori vengono impostati in precedenza durante la configurazione dei dati di Cloud Spanner.

Per eseguire il deployment del proxy, procedi nel seguente modo:

  • 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 per il test di integrazione. C'è una chiamata all'/openapiendpoint e un'altra all'/productsendpoint. 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 Reports

  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 facoltativamente crei un'app AppSheet 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 OpenAPI Specification (OAS) consente alla richiesta di specificare le seguenti intestazioni:

  • x-apikey: il token consumer dell'app dello schema di sicurezza.
  • x-userid: l'identificatore utente che effettua la richiesta. Se non viene fornito, questo valore predefinito è il valore CUSTOMER_USERID configurato nel proxy.
  • cache-control: il tempo necessario per memorizzare la risposta. Questa intestazione consente di memorizzare nella cache la risposta per 300 secondi o di specificare l'override specificando 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 sezioni seguenti vengono utilizzati nel bundle proxy dell'API in questo tutorial.

Pre-flusso

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

Flusso di prodotti

AssegnaMessaggio: creazione della richiesta di query
Imposta la richiesta HTTP con una query SQL per recuperare l'elenco dei suggerimenti sui prodotti dal set di dati BigQuery.
Norme JavaScript ed EstVariable
Formatta i dati dal servizio BigQuery e crea un messaggio di risposta più facile da utilizzare.
LookupCache - Sessione Cloud Spanner
Cerca l'ID sessione del database Cloud Spanner nella cache di Apigee.
Servizio callout - Sessione Cloud Spanner
Invia una richiesta al servizio Cloud Spanner e crea una sessione di database se la cache di Apigee non ha un ID di sessione o se 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 di catalogo del prodotto di Cloud Spanner.
JavaScript: formatta i dati di prodotto
Crea un messaggio di risposta API conforme all'ASA formattando i dati dal database di catalogo dei 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 del sito web di e-commerce e agli utenti aziendali, puoi creare un'app AppSheet 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 tua nuova app. Per creare un'origine dati:

  1. Accedi ad AppSheet.
  2. Nella pagina Account personale, 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 e 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, eseguila in Cloud Shell eseguendo il echo $APIKEY.
    3. Nel campo Apigee API Base Path (Percorso di 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 > ambienti > Gruppi.

    4. Nel campo Percorso risorse API, inserisci il suffisso 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 relativo a product-recommendations-v1.

Crea l'app

  1. Vai alla pagina dell'app per i modelli di prodotto di AppSheet.
  2. Fai clic su Copia e personalizza. Viene visualizzata la finestra di dialogo Clona la tua app.
  3. Nel campo Nome app, inserisci il nome del proxy, product-recommendations-v1, quindi fai clic su Copia app. Attendi qualche istante per creare la 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 creata 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 e poi su Aggiungi questa tabella.

    L'app viene mostrata con una scheda prodotti 2 e una visualizzazione dati diversa. La nuova visualizzazione dati contiene valori diversi per la descrizione e il prezzo di ogni elemento. Tieni presente che l'ordine degli elementi non è lo stesso ordine delle previsioni.

  6. Modifica l'ordine in cui vengono restituiti gli elementi dall'origine dati rimuovendo l'ordinamento predefinito di AppSheet:

    1. Nel menu di navigazione laterale, seleziona UX.
    2. Nella sezione Viste principali, seleziona Prodotti 2.
    3. Nella sezione Opzioni di visualizzazione, accanto a Ordina per, elimina la voce nome, Crescente. Tieni presente che l'ordine visualizzato in AppSheet è ora lo stesso risultato della chiamata API, con l'ultimo elemento dalla risposta in fondo.
  7. Salva l'app.

Se vuoi, puoi eliminare la tabella prodotto originale e l'esperienza utente e rinominare la tabella e la visualizzazione in "Consigli sui 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, vai alla pagina Gestisci risorse.

    Vai a Gestisci risorse

  2. Nell'elenco dei progetti, seleziona il progetto da 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.

Eliminare 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 della console, seleziona Gestione della capacità e poi 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, quindi 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 della console, espandi il progetto in cui hai completato il tutorial.
  2. Seleziona il set di dati bqml e fai clic su Elimina set di dati.
  3. Nella finestra overlay visualizzata, inserisci bqml e fai clic su Elimina.

Elimina il modello AI Platform

  1. In Google Cloud Console, 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 relativa alla versione V_1 (predefinita).

  4. Fai clic su Altro, quindi su Elimina.

  5. Al termine dell'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