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 :
Le schéma présente l'architecture suivante :
- 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é.
- 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.
- 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.
- Le proxy d'API agrège les données des recommandations de produits et des ensembles de données principaux des produits.
- 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
Dans ce document, vous utilisez 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.
Avant de commencer
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Vérifiez que la facturation est activée pour votre projet Google Cloud.
-
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.
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
Grant roles to your user account. Run the following command once for each of the following IAM roles:
- 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_IDENTIFIER" --role=ROLE
- Replace
PROJECT_ID
with your project ID. -
Replace
USER_IDENTIFIER
with the identifier for your user account. For example,user:myemail@example.com
. - Replace
ROLE
with each individual role.
- 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.
- Configurez votre organisation Apigee X pour autoriser l'accès externe.
Une fois que vous avez terminé les tâches décrites dans ce document, 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 :
Dans Google Cloud Marketplace, accédez à la page Exemple Analytics.
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é.
Dans la section Explorateur à côté de votre projet, cliquez sur
Afficher les actions, puis sur Créer un ensemble de données.Dans la boîte de dialogue Créer un ensemble de données qui s'affiche, procédez comme suit :
- Dans le champ ID de l'ensemble de données, saisissez
bqml
. - Dans la liste Emplacement des données, sélectionnez us (plusieurs régions aux États-Unis).
- Cliquez sur Créer un ensemble de données.
- Dans le champ ID de l'ensemble de données, saisissez
Cliquez sur Accéder à l'ensemble de données, puis sur Saisir une nouvelle requête.
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.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
).
Dans la console Google Cloud, accédez à la page BigQuery.
Cliquez sur Gestion de la capacité, puis sur Réservations.
Si vous êtes redirigé vers la page API BigQuery Reservation pour activer l'API, cliquez sur Activer. Sinon, passez à l'étape suivante.
Dans l'onglet Réservations, cliquez sur Acheter des emplacements.
Sur la page Acheter des emplacements, procédez comme suit :
- Dans la liste Durée d'engagement, sélectionnez Flex.
- Dans la liste Emplacement, sélectionnez us (plusieurs régions aux États-Unis).
- Dans la liste Nombre d'emplacements, sélectionnez 500.
- Cliquez sur Suivant.
Dans le champ Confirmation d'achat, saisissez
CONFIRM
, puis cliquez sur Acheter.
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
.Cliquez sur Créer une réservation, puis définissez les options suivantes :
- Dans le champ Nom de la réservation, saisissez
model
. - Dans la liste Emplacement, sélectionnez us (plusieurs régions aux États-Unis).
- Dans le champ Nombre d'emplacements, saisissez
500
. - Cliquez sur Enregistrer. Vous revenez à la page Réservations.
- Dans le champ Nom de la réservation, saisissez
À côté de la réservation
model
, dans la colonne Actions, sélectionnez Créer une attribution.Dans le champ Sélectionner une organisation, un dossier ou un projet, cliquez sur Parcourir.
Saisissez le nom du projet utilisé pour ce tutoriel ou sélectionnez-le dans la liste.
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 :
- Sur la page BigQuery de la console Google Cloud, cliquez sur Saisir une nouvelle requête.
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é.
Sur la page BigQuery de la console Google Cloud, 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 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.
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
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
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.
Sur la page BigQuery de la console Google Cloud, sélectionnez la table
prod_recommendations
, puis cliquez sur l'onglet Aperçu pour afficher les résultats.- Copiez n'importe quelle valeur
userId
. Dans Cloud Shell, définissez une variable d'environnement :
export CUSTOMER_USERID=USER_ID
Remplacez
USER_ID
par la valeuruserId
que vous avez copiée à l'étape précédente.
- Copiez n'importe quelle valeur
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
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 shellsetup_spanner.sh
pour insérer à nouveau les données.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
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.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 valeurCUSTOMER_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écifiantno-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.
- Quotas
- 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 :
- Connectez-vous à AppSheet.
- Sur la page Mon compte, cliquez sur Sources > Nouvelle source de données.
- Dans la boîte de dialogue Ajouter une source de données, saisissez le nom du proxy
product-recommendations-v1
, puis cliquez sur Apigee. Dans la boîte de dialogue Ajouter des informations de connexion à l'API Apigee, définissez les options suivantes :
- Sélectionnez Manuel.
- 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.
. 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.
Dans le champ Chemins d'accès aux ressources d'API, saisissez le suffixe de chemin
products
.Cliquez sur Test.
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
- Accédez à la page de l'application products-template d'AppSheet.
- Cliquez sur Copier et personnaliser. La boîte de dialogue Cloner votre application s'affiche.
- 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. - 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.
Modifiez la source de données pour qu'elle corresponde à la source de données Apigee que vous avez créée précédemment :
- Cliquez sur + Nouvelle table, puis sur product recommandations v1.
- Dans la boîte de dialogue Sélectionner une feuille/table, sélectionnez products.
- 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.
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 :
- Dans le menu de navigation latéral, sélectionnez Expérience utilisateur.
- Dans la section Vues principales, sélectionnez products 2.
- 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.
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
- Dans la console Google Cloud, accédez à la page Gérer les ressources.
- Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
- 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
- Sur la page BigQuery de la console Google Cloud, sélectionnez Gestion de la capacité, puis cliquez sur l'onglet Réservations.
- Ouvrez l'entrée model.
- À côté de la réservation, cliquez sur Afficher les actions, puis sur Supprimer.
- À côté de l'entrée model, cliquez sur Afficher les actions, puis sur Supprimer.
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
Supprimez les ressources Spanner :
./cleanup_spanner.sh
Supprimer l'ensemble de données BigQuery
- Dans la section Ressources de la page BigQuery de la console Google Cloud, développez le projet dans lequel vous avez effectué ce tutoriel.
- Sélectionnez l'ensemble de données bqml, puis cliquez sur Supprimer l'ensemble de données.
- Dans la fenêtre qui apparaît en superposition, saisissez
bqml
, puis cliquez sur Supprimer.
Supprimer le modèle AI Platform
Dans la console Google Cloud, accédez à la page Modèles AI Platform.
Dans la liste des modèles, cliquez sur rpm_bqml_model.
Sur la page Détails du modèle, cochez la case correspondant à la version V_1 (par défaut).
Cliquez sur Plus, puis sur Supprimer.
Lorsque la version est supprimée, cliquez sur Retour pour revenir à la liste des modèles.
Cochez la case correspondant au modèle rpm_bqml_model.
Cliquez sur Plus , puis sur Supprimer.
Dans Cloud Shell, supprimez le compte de service :
gcloud iam service-accounts delete $SA
Étape suivante
- Découvrez comment appeler des services Google Cloud à partir de proxys d'API Apigee.
- Pour découvrir d'autres architectures de référence, schémas, tutoriels et bonnes pratiques, consultez le Centre d'architecture cloud.