Créer une API intelligente pour prédire les tendances d'achat des clients à l'aide d'Apigee, de BigQuery ML et de Cloud Spanner

Ce tutoriel explique comment créer une API permettant de prédire la probabilité qu'un client effectue un achat. Pour créer l'API, vous devez utiliser Apigee, BigQuery ML et Cloud Spanner.

Ce tutoriel est destiné aux développeurs d'API et aux spécialistes des données qui souhaitent générer des revenus plus élevés via des plates-formes omnicanales et d'e-commerce en offrant une expérience plus personnalisée aux utilisateurs. Nous partons du principe que vous connaissez BigQuery, Apigee, Google Cloud CLI et Apache Maven.

L'API que vous créez utilise des prédictions en ligne pour effectuer des actions en temps réel en fonction du comportement des utilisateurs sur votre site Web. Les prédictions en ligne combinent des insights de machine learning (ML) et un catalogue de produits, ainsi que d'autres informations, afin de vous aider à améliorer l'expérience client sur plusieurs canaux. L'architecture de l'API que vous créez est illustrée dans le schéma suivant :

Architecture d'une API permettant de prédire les tendances d'achat des clients.

Le schéma présente l'architecture suivante :

  1. Une application mobile envoie une requête à l'API déployée sur la plate-forme Apigee. La requête extrait les données des recommandations de produits pour l'utilisateur connecté.
  2. Un proxy d'API récupère les données des recommandations de produits pour l'ID utilisateur à partir d'un ensemble de données BigQuery.
  3. Le proxy d'API effectue un appel pour extraire les données de la base de données principale des produits sur une instance Cloud Spanner.
  4. Le proxy d'API agrège les données des recommandations de produits et des ensembles de données principaux des produits.
  5. Une réponse est renvoyée sur l'application mobile.

Objectifs

  • Créer un ensemble de données sur les tendances d'achat des clients dans BigQuery
  • Importer des données du catalogue de produits dans la base de données Cloud Spanner
  • Importer et déployer un proxy d'API Apigee
  • Intégrer les données sur les tendances d'achats des clients de BigQuery au catalogue de produits et aux informations tarifaires dans la base de données Cloud Spanner
  • Créer une vue agrégée des recommandations de produits

Coûts

Ce tutoriel utilise les composants facturables suivants de Google Cloud :

  • Emplacements Flex BigQuery et BigQuery ML
  • Cloud Spanner
  • Apigee

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Avant de commencer

  1. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  2. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

  3. Activer les 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.

    Activer les API

  4. Dans la console, activez Cloud Shell.

    Activer Cloud Shell

    En bas de la fenêtre de la console, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

  5. Attribuez des rôles à votre compte Google. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants :

    • 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
    • en remplaçant PROJECT_ID par l'ID de votre projet :
    • Remplacez EMAIL_ADDRESS par votre adresse e-mail.
    • Remplacez ROLE par chaque rôle individuel.
  6. Si vous ne possédez pas encore de compte Apigee X, configurez Apigee pour provisionner une instance Apigee X. Le provisionnement peut prendre jusqu'à une heure.
  7. Configurez votre organisation Apigee X pour autoriser l'accès externe.

Une fois que vous avez terminé ce tutoriel, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Créer un ensemble de données de recommandations pour le e-commerce avec BigQuery ML

Dans cette section, vous allez utiliser des requêtes SQL standards dans BigQuery ML pour créer un modèle de ML, l'entraîner sur des données client dans BigQuery, puis le déployer. Vous n'avez pas besoin d'exporter vos données ni de créer un pipeline d'entraînement et de déploiement de modèle. BigQuery s'adapte automatiquement pour gérer toutes les ressources de calcul dont vous avez besoin.

Le modèle de ML que vous créez dans ce tutoriel utilise la factorisation matricielle, une méthode courante et efficace qui permet de créer un système de recommandation basé sur les données des préférences des utilisateurs.

Dans ce tutoriel, vous allez utiliser l'exemple d'ensemble de données Google Analytics, qui est hébergé publiquement sur BigQuery. Cet ensemble de données offre 12 mois (août 2016 à août 2017) de données Analytics 360 masquées provenant du Google Merchandise Store, un magasin d'e-commerce qui vend des produits Google.

Traiter l'exemple de données

Lorsque vous utilisez la factorisation matricielle, vous évaluez les commentaires explicites ou implicites des utilisateurs afin de déterminer les préférences des clients. Pour pouvoir utiliser des commentaires explicites, l'ensemble de données doit contenir des données concernant les préférences des utilisateurs, comme les notes (de 1 à 5) qu'ils ont laissées sur un produit. Si aucun commentaire explicite n'est disponible, vous devez utiliser d'autres métriques de comportement pour déduire les préférences des clients, comme le temps total passé par un utilisateur sur la page d'informations d'un produit. Dans ce tutoriel, vous allez utiliser les données de durée des sessions pour déduire les préférences des clients.

Pour entraîner le modèle de factorisation matricielle, vous devez disposer d'une table comportant des colonnes qui identifient le client, l'élément évalué et la note implicite. Dans cette section, vous allez créer une table de ce type avec les colonnes userid, itemId et session_duration. La colonne session_duration contient la durée de la session de l'utilisateur sur la page d'un produit donné.

Pour créer la table à l'aide des données de l'exemple d'ensemble de données Analytics, procédez comme suit :

  1. Dans Google Cloud Marketplace, accédez à la page Exemple Analytics.

    Accéder à l'exemple Analytics

  2. Cliquez sur Afficher l'ensemble de données. La page de l'espace de travail BigQuery SQL s'ouvre avec l'exemple d'ensemble de données Analytics sélectionné.

  3. Dans la section Explorateur à côté de votre projet, cliquez sur  Afficher les actions, puis sur Créer un ensemble de données.

  4. Dans la boîte de dialogue Créer un ensemble de données qui s'affiche, procédez comme suit :

    1. Dans le champ ID de l'ensemble de données, saisissez bqml.
    2. Dans la liste Emplacement des données, sélectionnez us (plusieurs régions aux États-Unis).
    3. Cliquez sur Créer un ensemble de données.
  5. Cliquez sur Accéder à l'ensemble de données, puis sur Saisir une nouvelle requête.

  6. Dans l'éditeur de requête, créez une table contenant les données d'entraînement en exécutant l'instruction SQL suivante :

    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 table bqml.aggregate_web_stats est créée et renseignée avec les données d'entraînement.

  7. Pour afficher un exemple de données, exécutez l'instruction SQL suivante dans l'éditeur de requête :

    SELECT
    *
    FROM
      bqml.aggregate_web_stats
    LIMIT
      10;
    

Le résultat affiche une table comportant une ligne pour chaque ID utilisateur, qui inclut l'ID de l'article affiché par l'utilisateur, et la durée de sa session. Le résultat ressemble à ce qui suit :

Row userId itemId session_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

Acheter des emplacements Flex

Si vous utilisez la tarification à la demande pour BigQuery, vous devez acheter des emplacements Flex, puis créer des réservations et des attributions associées afin d'entraîner un modèle de factorisation matricielle. Si vous avez opté pour des tarifs forfaitaires avec BigQuery, vous pouvez ignorer cette section et passer à la section Créer, entraîner et déployer le modèle.

Pour acheter des emplacements Flex, vous devez disposer d'un rôle IAM qui inclut l'autorisation bigquery.reservations.create. Cette autorisation est accordée au propriétaire du projet. Elle est incluse dans les rôles IAM d'administrateur BigQuery (roles/bigquery.admin) et d'administrateur de ressources BigQuery (roles/bigquery.resourceAdmin).

  1. Dans la console, accédez à la page BigQuery.

    Accéder à BigQuery

  2. Cliquez sur Gestion de la capacité, puis sur Réservations.

  3. Si vous êtes redirigé vers la page API BigQuery Reservation pour activer l'API, cliquez sur Activer. Sinon, passez à l'étape suivante.

  4. Dans l'onglet Réservations, cliquez sur Acheter des emplacements.

  5. Sur la page Acheter des emplacements, procédez comme suit :

    1. Dans la liste Durée d'engagement, sélectionnez Flex.
    2. Dans la liste Emplacement, sélectionnez us (plusieurs régions aux États-Unis).
    3. Dans la liste Nombre d'emplacements, sélectionnez 500.
    4. Cliquez sur Suivant.
    5. Dans le champ Confirmation d'achat, saisissez CONFIRM, puis cliquez sur Acheter.

  6. Cliquez sur Afficher les engagements d'emplacements.

    Patientez jusqu'à 20 minutes pour que la capacité soit provisionnée. Une fois la capacité provisionnée, la colonne État de l'engagement d'emplacements affiche .

  7. Cliquez sur Créer une réservation, puis définissez les options suivantes :

    1. Dans le champ Nom de la réservation, saisissez model.
    2. Dans la liste Emplacement, sélectionnez us (plusieurs régions aux États-Unis).
    3. Dans le champ Nombre d'emplacements, saisissez 500.
    4. Cliquez sur Enregistrer. Vous revenez à la page Réservations.
  8. À côté de la réservation model, dans la colonne Actions, sélectionnez Créer une attribution.

  9. Dans le champ Sélectionner une organisation, un dossier ou un projet, cliquez sur Parcourir.

  10. Saisissez le nom du projet utilisé pour ce tutoriel ou sélectionnez-le dans la liste.

  11. Cliquez sur Sélectionner, puis sur Créer.

Créer, entraîner et déployer le modèle

Pour créer, entraîner et déployer le modèle de factorisation matricielle, procédez comme suit :

  1. Sur la page BigQuery de la console, cliquez sur  Saisir une nouvelle requête.
  2. Exécutez l'instruction 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;
    

Une fois l'entraînement terminé, le modèle entraîné est déployé en tant que modèle bqml.retail_recommender.

Utiliser le modèle entraîné pour effectuer des prédictions

Dans cette section, vous utilisez la fonction SQL ML.RECOMMEND pour obtenir des prédictions à partir du modèle bqml.retail_recommender déployé.

  1. Sur la page BigQuery de la console, saisissez une requête et obtenez des prédictions représentant les cinq meilleures recommandations pour un ID d'utilisateur spécifié :

    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;
    

    Le résultat affiche une ligne pour le niveau de confiance de la durée de session prédite (plus il est élevé, mieux c'est), l'ID d'utilisateur associé et l'ID de l'article affiché par l'utilisateur. Le résultat ressemble à ce qui suit :

    Row predicted_session_duration_confidence userId itemId
    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. Pour obtenir les cinq meilleures prédictions pour tous les utilisateurs, exécutez l'instruction SQL suivante. Cette instruction génère de nombreuses lignes. La sortie est donc écrite dans une table, puis les dix premiers enregistrements sont récupérés afin que vous puissiez consulter un exemple de données.

    -- 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;
    

    Le résultat affiche plusieurs ID utilisateur, l'ID de l'article affiché par l'utilisateur et le niveau de confiance de la durée de session prédite. Le résultat ressemble à ce qui suit :

    Row userId itemId predicted_session_duration_confidence
    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

Configurer les données Cloud Spanner

Dans les sections suivantes de ce tutoriel, vous allez utiliser gcloud CLI et Maven. Vous exécutez des commandes pour les deux outils à partir de Cloud Shell. Aucune installation n'est requise pour utiliser les outils.

  1. Dans Cloud Shell, clonez le dépôt GitHub de recommandations de produits qui contient le groupe de proxys d'API de recommandations de produits et les scripts permettant de configurer les données dans une base de données Cloud Spanner :

    git clone https://github.com/apigee/devrel/tree/main/references/product-recommendations
    cd product-recommendations-v1
    
  2. Créez le compte de service datareader et attribuez-lui des rôles IAM. Le compte de service permet d'accéder aux données de BigQuery et à la base de données Cloud Spanner à partir du proxy d'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. Définissez les variables d'environnement :

    # 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
    

    Remplacez les éléments suivants :

    • APIGEEX_PROJECT : nom de votre projet Apigee X.
    • API_DOMAIN_NAME : nom d'hôte configuré sur la page Administration > Environnements > Groupes dans l'interface utilisateur d'Apigee X.
  4. Sur la page BigQuery de la console, sélectionnez la table prod_recommendations, puis cliquez sur l'onglet Aperçu pour afficher les résultats.

    1. Copiez n'importe quelle valeur userId.
    2. Dans Cloud Shell, définissez une variable d'environnement :

      export CUSTOMER_USERID=USER_ID
      

      Remplacez USER_ID par la valeur userId que vous avez copiée à l'étape précédente.

  5. Dans Cloud Shell, affichez les résultats de recommandations de produits triés pour la valeur CUSTOMER_USERID spécifiée :

    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
    

    Le résultat affiche un ID utilisateur individuel, l'ID de l'article affiché par l'utilisateur et le niveau de confiance de la durée de session prédite. Le résultat ressemble à ce qui suit :

    +-----------------------+----------------+--------------------------------------------+
    |        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 |
    +-----------------------+----------------+--------------------------------------------+
    

Créer une base de données Cloud Spanner et importer les données du catalogue de produits

  1. Dans Cloud Shell, créez une instance Cloud Spanner dans la région spécifiée, créez la base de données du catalogue de produits et importez les données :

    ./setup_spanner.sh
    

    Le script utilise la variable d'environnement CUSTOMER_USERID et affiche les entrées créées.

    Le catalogue de produits Cloud Spanner ne contient que les éléments utilisés lors de l'étape d'entraînement BigQuery pour un utilisateur spécifique. Par conséquent, si vous modifiez la variable d'environnement CUSTOMER_USERID après avoir créé les données du catalogue de produits dans la base de données Cloud Spanner, vous devez réexécuter le script shell setup_spanner.sh pour insérer à nouveau les données.

  2. Vérifiez les données dans la base de données Cloud Spanner :

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

    Le résultat affiche les ID produit et les informations descriptives du catalogue de produits Spanner, y compris le prix et le chemin d'accès de l'image. Le résultat ressemble à ce qui suit :

    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
    

Déployer un proxy Apigee

Dans cette section, vous allez exécuter une commande Maven pour créer les ressources suivantes :

  • Un proxy nommé product-recommendations-v1
  • Un produit d'API nommé product-recommendations-v1-$ENV
  • Un développeur d'applications nommé demo@any.com
  • Une application nommée product-recommendations-v1-app-$ENV

Pour créer les ressources, Maven utilise le fichier pom.xml du dépôt GitHub. Ce fichier contient les instructions et les étapes d'installation.

La section "profil" du fichier pom.xml contient les valeurs de apigee.org, apigee.env, api.northbound.domain, gcp.projectid, googletoken.email et api.userid. Ces valeurs varient en fonction du projet et sont définies à l'aide de la ligne de commande. L'exemple suivant montre la section du fichier pom.xml contenant les valeurs :

<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>

Vous avez défini ces valeurs précédemment lors de la configuration des données Cloud Spanner.

Pour déployer le proxy, procédez comme suit :

  • Dans Cloud Shell, installez le proxy et les artefacts associés, puis testez 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
    

    La sortie affiche l'exécution des étapes d'installation et les résultats des appels d'API du test d'intégration. Il existe un appel au point de terminaison /openapi et un autre au point de terminaison /products. Les résultats du test vérifient que le proxy d'API a été installé, déployé et est opérationnel. La sortie affiche également les identifiants de l'application, que vous pouvez utiliser pour les appels de test de l'API ultérieurs.

Tester l'API de recommandations

  1. Dans Cloud Shell, définissez une variable d'environnement pour la clé API de l'application en effectuant un appel curl vers l'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)
    

    Notez la valeur APIKEY. Vous en aurez besoin si vous créez une application AppSheet ultérieurement.

  2. Pour obtenir les résultats de la valeur CUSTOMER_USERID que vous avez spécifiée lors de l'installation du proxy d'API, effectuez un appel de test :

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

L'API définie par la spécification OpenAPI (OAS) permet à la requête de spécifier les en-têtes suivants :

  • x-apikey : clé client de l'application provenant du schéma de sécurité.
  • x-userid : identifiant de l'utilisateur effectuant la requête. S'il n'est pas spécifié, cette valeur est définie par défaut sur la valeur CUSTOMER_USERID configurée dans le proxy.
  • cache-control : durée pendant laquelle mettre en cache la réponse. Cet en-tête vous permet de mettre en cache la réponse pendant 300 secondes ou de la remplacer en spécifiant no-cache.

Pour modifier la valeur CUSTOMER_USERID ou contrôler la mise en cache, vous pouvez définir les valeurs d'en-tête comme indiqué dans l'exemple d'appel suivant :

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

La réponse à l'exemple d'appel ressemble à ce qui suit :

{
  "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"
    }
  ]
}

Règles Apigee

Les règles Apigee répertoriées dans les sections suivantes sont utilisées dans le groupe de proxys d'API de ce tutoriel.

Pré-flux

SpikeArrest
Protégez le service de backend BigQuery contre les pics de trafic.
Quota
Limitez les requêtes API en fonction de l'application consommateur et du développeur. Les limites sont configurées dans le produit d'API.
ResponseCache - uri
Réduisez le nombre de requêtes adressées à l'entrepôt de données BigQuery en mettant en cache la réponse du service.

Flux de produits

AssignMessage - requête de création de requête
Définissez la requête HTTP avec une requête SQL pour extraire la liste des recommandations de produits de l'ensemble de données BigQuery.
Règles JavaScript et ExtractVariable
Formatez les données du service BigQuery et créez un message de réponse plus convivial.
LookupCache - session Cloud Spanner
Recherchez l'ID de session de la base de données Cloud Spanner à partir du cache Apigee.
ServiceCallout - session Cloud Spanner
Envoyez une requête au service Cloud Spanner et créez une session de base de données si le cache Apigee ne possède pas d'ID de session ou si l'ID est arrivé à expiration.
PopulateCache - session Cloud Spanner
Remplissez l'ID de session Cloud Spanner dans le cache Apigee.
ServiceCallout - recherche dans le catalogue de produits
Récupérez les informations détaillées sur le produit dans la base de données du catalogue de produits Cloud Spanner.
JavaScript - mettre en forme les données produit
Créez un message de réponse d'API conforme à OAS en formatant les données de la base de données du catalogue de produits.

Flux OpenAPI

AssignMessage - OAS JSON
Définissez la réponse JSON OAS pour l'API.

Facultatif : Créer une application AppSheet à l'aide d'Apigee en tant que source de données

Pour afficher des recommandations de produits aux utilisateurs finaux et aux utilisateurs professionnels d'un site Web d'e-commerce, vous pouvez créer une application AppSheet, comme indiqué dans cette section.

Créer un compte AppSheet

Créez un compte AppSheet à l'aide de votre adresse e-mail.

Créer une source de données

AppSheet utilise le proxy d'API en tant que source de données pour votre nouvelle application. Pour créer une source de données, procédez comme suit :

  1. Connectez-vous à AppSheet.
  2. Sur la page Mon compte, cliquez sur Sources > Nouvelle source de données.
  3. Dans la boîte de dialogue Ajouter une source de données, saisissez le nom du proxy product-recommendations-v1, puis cliquez sur Apigee.
  4. Dans la boîte de dialogue Ajouter des informations de connexion à l'API Apigee, définissez les options suivantes :

    1. Sélectionnez Manuel.
    2. Dans le champ Clé API Apigee, saisissez la clé API de votre application que vous avez utilisée pour tester le proxy. Si vous ne possédez pas la clé API, obtenez-la dans Cloud Shell en exécutant la commande echo $APIKEY..
    3. Dans le champ Chemin de base de l'API Apigee, saisissez les informations suivantes :

      https://ENVGROUP_HOSTNAME/v1/recommendations
      

      Remplacez ENVGROUP_HOSTNAME par le nom d'hôte configuré dans l'interface utilisateur d'Apigee X pour Administration > Environnements > Groupes.

    4. Dans le champ Chemins d'accès aux ressources d'API, saisissez le suffixe de chemin products.

    5. Cliquez sur Test.

    6. Une fois les tests terminés, cliquez sur Autoriser l'accès.

Une fois l'accès autorisé, la console AppSheet affiche un nouveau bloc pour product-recommendations-v1.

Créer l'application

  1. Accédez à la page de l'application products-template d'AppSheet.
  2. Cliquez sur Copier et personnaliser. La boîte de dialogue Cloner votre application s'affiche.
  3. Dans le champ Nom de l'application, saisissez le nom du proxy, product-recommendations-v1, puis cliquez sur Copier l'application. Attendez quelques instants que l'application soit créée.
  4. Sur la page Bienvenue dans votre application, cliquez sur Personnaliser l'application. Par défaut, l'application utilise un exemple de source de données dans une feuille de calcul Google Sheets.
  5. Modifiez la source de données pour qu'elle corresponde à la source de données Apigee que vous avez créée précédemment :

    1. Cliquez sur + Nouvelle table, puis sur product recommandations v1.
    2. Dans la boîte de dialogue Sélectionner une feuille/table, sélectionnez products.
    3. Dans la boîte de dialogue Créer une table, cliquez sur Lecture seule, puis sur Ajouter cette table.

    L'application s'affiche avec un onglet products 2 et une vue de données différente. La nouvelle vue des données présente des valeurs différentes pour la description et le prix de chaque article. Notez que l'ordre des éléments n'est pas le même que celui des prédictions.

  6. Modifiez l'ordre dans lequel les éléments sont renvoyés depuis la source de données en supprimant le tri par défaut d'AppSheet :

    1. Dans le menu de navigation latéral, sélectionnez Expérience utilisateur.
    2. Dans la section Vues principales, sélectionnez products 2.
    3. Dans la section Options d'affichage à côté de Trier par, supprimez l'entrée pour nom, Ordre croissant. Notez que l'ordre affiché dans AppSheet est désormais identique au résultat de l'appel d'API, le dernier élément de la réponse étant affiché en bas.
  7. Enregistrez l'application.

Vous pouvez éventuellement supprimer la table "product" et l'expérience utilisateur d'origine, puis renommer la table "products 2" et l'afficher sous "Recommandations de produits".

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Supprimer le projet

  1. Dans la console, accédez à la page Gérer les ressources.

    Accéder à la page Gérer les ressources

  2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Supprimer les ressources individuelles

Pour éviter des frais récurrents, supprimez les réservations d'emplacements Flex BigQuery, l'ensemble de données BigQuery et le modèle AI Platform.

Supprimer les réservations d'emplacements Flex BigQuery

  1. Dans la page BigQuery de la console, sélectionnez Gestion de la capacité, puis cliquez sur l'onglet Réservations.
  2. Ouvrez l'entrée model.
  3. À côté de la réservation, cliquez sur  Afficher les actions, puis sur Supprimer.
  4. À côté de l'entrée model, cliquez sur  Afficher les actions, puis sur Supprimer.
  5. Dans Cloud Shell, supprimez le déploiement, le proxy et les artefacts associés :

    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. Supprimez les ressources Spanner :

    ./cleanup_spanner.sh
    

Supprimer l'ensemble de données BigQuery

  1. Dans la section Ressources de la page BigQuery de la console, développez le projet dans lequel vous avez effectué ce tutoriel.
  2. Sélectionnez l'ensemble de données bqml, puis cliquez sur Supprimer l'ensemble de données.
  3. Dans la fenêtre qui apparaît en superposition, saisissez bqml, puis cliquez sur Supprimer.

Supprimer le modèle AI Platform

  1. Dans la console Google Cloud, accédez à la page Modèles AI Platform.

    Accédez aux modèles AI Platform.

  2. Dans la liste des modèles, cliquez sur rpm_bqml_model.

  3. Sur la page Détails du modèle, cochez la case correspondant à la version V_1 (par défaut).

  4. Cliquez sur Plus, puis sur Supprimer.

  5. Lorsque la version est supprimée, cliquez sur Retour pour revenir à la liste des modèles.

  6. Cochez la case correspondant au modèle rpm_bqml_model.

  7. Cliquez sur Plus , puis sur Supprimer.

  8. Dans Cloud Shell, supprimez le compte de service :

    gcloud iam service-accounts delete $SA
    

Étape suivante