In dieser Anleitung erfahren Sie, wie Sie eine API erstellen, mit der Sie vorhersagen können, wie wahrscheinlich ein Kunde etwas kauft. Zum Erstellen der API verwenden Sie Apigee, BigQuery ML und Cloud Spanner.
Diese Anleitung richtet sich an API-Entwickler und Datenexperten, die über Omni-Channel- und E-Commerce-Plattformen mehr Umsatz generieren möchten, indem sie eine personalisiertere Nutzererfahrung bieten. Dabei wird davon ausgegangen, dass Sie mit BigQuery, Apigee, der Google Cloud-Befehlszeile und Apache Maven vertraut sind.
Die von Ihnen erstellte API verwendet Onlinevorhersagen, um Aktionen anhand des Nutzerverhaltens auf Ihrer Website in Echtzeit auszuführen. Onlinevorhersagen kombinieren Informationen zum maschinellen Lernen (ML) mit einem Produktkatalog und anderen Informationen. So können Sie den Kunden Folgendes über mehrere Kanäle bieten. Die Architektur der von Ihnen erstellten API ist im folgenden Diagramm dargestellt:
Das Diagramm zeigt die folgende Architektur:
- Eine mobile Anwendung sendet eine Anfrage an die API, die auf der Apigee-Plattform bereitgestellt wird. Mit der Anfrage werden die Produktempfehlungsdaten für den angemeldeten Nutzer abgerufen.
- Ein API-Proxy ruft die Produktempfehlungsdaten für die Nutzer-ID aus einem BigQuery-Dataset ab.
- Der API-Proxy erstellt ein Callout zum Abrufen der Daten aus der primären Produktdatenbank in einer Cloud Spanner-Instanz.
- Der API-Proxy aggregiert die Daten aus den Produktempfehlungen und den primären Datasets des Produkts.
- Eine Antwort wird an die mobile Anwendung zurückgegeben.
Ziele
- Erstellen Sie in BigQuery ein Dataset zur Kundenkaufneigung.
- Importieren Sie Produktkatalogdaten in die Cloud Spanner-Datenbank.
- Importieren und stellen Sie den Apigee API-Proxy bereit.
- Binden Sie Daten zur Kaufneigung von Kunden aus BigQuery in den Produktkatalog und die Preisinformationen in der Cloud Spanner-Datenbank ein.
- Zusammengefasste Ansicht der Produktempfehlungen erstellen
Kosten
In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:
- Flex-Slots in BigQuery und BigQuery ML
- Cloud Spanner
- Apigee
Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.
Vorbereitung
-
Wählen Sie in der Google Cloud Console auf der Seite der Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
-
Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.
-
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 APIs aktivieren.
-
Aktivieren Sie Cloud Shell in der Google Cloud Console.
Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.
-
Gewähren Sie Ihrem Google-Konto Rollen. Führen Sie den folgenden Befehl für jede der folgenden IAM-Rollen einmal aus:
- 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
- Ersetzen Sie
PROJECT_IDdurch Ihre Projekt-ID. - Ersetzen Sie
EMAIL_ADDRESSdurch Ihre E-Mail-Adresse. - Ersetzen Sie
ROLEdurch jede einzelne Rolle.
- Wenn Sie noch kein Apigee X-Konto haben, richten Sie Apigee ein, um eine Apigee X-Instanz bereitzustellen. Dies kann bis zu einer Stunde dauern.
- Konfigurieren Sie Ihre Apigee X-Organisation so, dass externer Zugriff zugelassen wird.
Nach Abschluss der in diesem Dokument beschriebenen Aufgaben können Sie weitere Kosten vermeiden, indem Sie die erstellten Ressourcen löschen. Weitere Informationen finden Sie unter Bereinigen.
E-Commerce-Empfehlungs-Dataset mit BigQuery ML erstellen
In diesem Abschnitt verwenden Sie Standard-SQL-Abfragen in BigQuery ML, um ein ML-Modell zu erstellen, es mit Kundendaten in BigQuery zu trainieren und es dann bereitzustellen. Sie müssen weder Ihre Daten exportieren noch eine Modelltrainings- und Bereitstellungspipeline erstellen. BigQuery skaliert automatisch für alle benötigten Rechenressourcen.
Das ML-Modell, das Sie in dieser Anleitung erstellen, verwendet die Matrixfaktorisierung, eine häufige und effektive Methode zum Erstellen eines Empfehlungssystems, das auf den Daten von Nutzerpräferenzen beruht.
In dieser Anleitung verwenden Sie das Google Analytics-Beispiel-Dataset, das öffentlich in BigQuery gehostet wird. Dieses Dataset bietet verschleierte Analytics 360-Daten aus einem Zeitraum von zwölf Monaten (August 2016 bis August 2017). Diese Daten stammen aus dem Google Merchandise Store, einem echten E-Commerce-Shop, in dem Merchandise-Artikel von Google verkauft werden.
Beispieldaten verarbeiten
Bei der Matrixfaktorisierung bewerten Sie explizites oder implizites Nutzerfeedback, um Kundenpräferenzen zu ermitteln. Wenn Sie explizites Feedback verwenden möchten, muss das Dataset Daten zu Produktpräferenzen der Nutzer, z. B. eine Bewertung zwischen 1 und 5, enthalten. Wenn kein explizites Feedback verfügbar ist, müssen Sie zur Ableitung von Kundenpräferenzen andere Verhaltensmesswerte verwenden, z. B. die Zeit, die ein Nutzer insgesamt auf einer Produktdetailseite verbringt. In dieser Anleitung verwenden Sie Daten zur Sitzungsdauer, um Kundenpräferenzen abzuleiten.
Zum Trainieren des Matrixfaktorisierungsmodells benötigen Sie eine Tabelle mit Spalten, die den Kunden, das bewertete Element und die implizite Bewertung identifizieren. In diesem Abschnitt erstellen Sie eine solche Tabelle mit den Spalten userid, itemId und session_duration. Die Spalte session_duration enthält die Dauer der Nutzersitzung auf der Produktseite des angegebenen Artikels.
So erstellen Sie die Tabelle mit Daten aus dem Analytics-Beispiel-Dataset:
Rufen Sie im Google Cloud Marketplace die Seite Analytics-Beispiel auf.
Klicken Sie auf Dataset aufrufen. Die Seite "BigQuery SQL-Arbeitsbereich" wird mit dem ausgewählten Analytics-Beispiel-Dataset geöffnet.
Klicken Sie im Abschnitt Explorer neben Ihrem Projekt auf Aktionen anzeigen und dann auf Dataset erstellen.
Führen Sie im angezeigten Dialogfeld Dataset erstellen die folgenden Schritte aus:
- Geben Sie im Feld Dataset-ID den Wert
bqmlein. - Wählen Sie in der Liste Datenspeicherort die Option us (mehrere Regionen in den USA) aus.
- Klicken Sie auf Dataset erstellen.
- Geben Sie im Feld Dataset-ID den Wert
Klicken Sie auf Zum Dataset und dann auf Neue Abfrage erstellen.
Erstellen Sie im Abfrageeditor eine Tabelle mit den Trainingsdaten. Führen Sie dazu die folgende SQL-Anweisung aus:
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 );Die Tabelle
bqml.aggregate_web_statswird erstellt und mit Trainingsdaten gefüllt.Wenn Sie ein Beispiel der Daten sehen möchten, führen Sie im Abfrageeditor die folgende SQL-Anweisung aus:
SELECT * FROM bqml.aggregate_web_stats LIMIT 10;
Die Ausgabe zeigt eine Tabelle mit einer Zeile für jede Nutzer-ID, die die vom Nutzer angesehene Element-ID und die Dauer ihrer Sitzung enthält. Die Ausgabe sieht etwa so aus:
| 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 |
Flex-Slots erwerben
Wenn Sie On-Demand-Preise für BigQuery verwenden, müssen Sie zum Trainieren eines Matrixfaktorisierungsmodells Flex-Slots erwerben und dann Reservierungen und Zuweisungen für diese erstellen. Wenn Sie Pauschalpreise mit BigQuery verwenden, können Sie diesen Abschnitt überspringen und mit Modell erstellen, trainieren und bereitstellen fortfahren.
Sie benötigen eine IAM-Rolle mit der Berechtigung bigquery.reservations.create, um Flex-Slots zu erwerben. Diese Berechtigung wird dem Projektinhaber gewährt und in den IAM-Rollen "BigQuery-Administrator" (roles/bigquery.admin) und "BigQuery-Ressourcenadministrator" (roles/bigquery.resourceAdmin) enthalten.
Öffnen Sie in der Google Cloud Console die Seite BigQuery:
Klicken Sie auf Kapazitätsverwaltung und dann auf Reservierungen.
Wenn Sie zur Seite BigQuery Reservation API weitergeleitet werden, um die API zu aktivieren, klicken Sie auf Aktivieren. Andernfalls fahren Sie mit dem nächsten Schritt fort.
Klicken Sie auf dem Tab Reservierungen auf Slots erwerben.
Führen Sie auf der Seite Slots erwerben folgende Schritte aus:
- Wählen Sie in der Liste Zusicherungsdauer die Option Flex aus.
- Wählen Sie in der Liste Standort die Option us (mehrere Regionen in den USA) aus.
- Wählen Sie in der Liste Anzahl der Slots die Option 500 aus.
- Klicken Sie auf Next (Weiter).
Geben Sie im Feld Kaufbestätigung
CONFIRMein und klicken Sie dann auf Kaufen.
Klicken Sie auf Slot-Zusicherungen anzeigen.
Es kann bis zu 20 Minuten dauern, bis die Kapazität bereitgestellt wird. Nachdem die Kapazität bereitgestellt wurde, wird in der Spalte Status der Slot-Zusicherung angezeigt.
Klicken Sie auf Reservierung erstellen und legen Sie die folgenden Optionen fest:
- Geben Sie unter Name der Reservierung den Wert
modelein. - Wählen Sie in der Liste Standort die Option us (mehrere Regionen in den USA) aus.
- Geben Sie unter Anzahl der Slots den Wert
500ein. - Klicken Sie auf Speichern. Dadurch kehren Sie zur Seite Reservierungen zurück.
- Geben Sie unter Name der Reservierung den Wert
Wählen Sie neben der Reservierung
modelin der Spalte Aktionen die Option Zuweisung erstellen aus.Klicken Sie unter Organisation, Ordner oder Projekt auswählen auf Durchsuchen.
Geben Sie den Namen des Projekts ein, in dem Sie diese Anleitung durcharbeiten, oder wählen Sie es aus der Liste aus.
Klicken Sie auf Auswählen und anschließend auf Erstellen.
Modell erstellen, trainieren und bereitstellen
So erstellen, trainieren und stellen Sie das Matrixfaktorisierungsmodell bereit:
- Klicken Sie in der BigQuery-Seite der Google Cloud Console auf Neue Abfrage erstellen.
Führen Sie die SQL-Anweisung
CREATE MODELaus: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;
Nach Abschluss des Trainings wird das trainierte Modell als bqml.retail_recommender-Modell bereitgestellt.
Trainiertes Modell für Vorhersagen verwenden
In diesem Abschnitt verwenden Sie die SQL-Funktion ML.RECOMMEND, um Vorhersagen aus dem bereitgestellten bqml.retail_recommender-Modell abzurufen.
Erstellen Sie auf der BigQuery-Seite in der Google Cloud Console eine Abfrage und rufen Sie Vorhersagen ab, die die fünf besten Empfehlungen für eine angegebene Nutzer-ID darstellen:
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;Die Ausgabe zeigt eine Zeile für die Konfidenzsitzungsdauer (höher ist besser), die zugehörige Nutzer-ID und die Element-ID, die sich der Nutzer angesehen hat. Die Ausgabe sieht etwa so aus:
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 Führen Sie die folgende SQL-Anweisung aus, um die fünf besten Vorhersagen für alle Nutzer zu erhalten. Die Anweisung generiert viele Zeilen, sodass die Ausgabe in eine Tabelle geschrieben und die ersten zehn Datensätze abgerufen werden, damit Sie ein Beispiel der Daten sehen können.
-- 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;Die Ausgabe zeigt mehrere Nutzer-IDs, die vom Nutzer aufgerufene Element-ID und den Konfidenzwert der vorhergesagten Sitzung. Die Ausgabe sieht etwa so aus:
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
Cloud Spanner-Daten einrichten
In den folgenden Abschnitten dieser Anleitung verwenden Sie die gcloud-Befehlszeile und Maven. Bei beiden Tools führen Sie Befehle über Cloud Shell aus. Zur Verwendung der Tools ist keine Installation erforderlich.
Klonen Sie in Cloud Shell das GitHut-Repository für Produktempfehlungen, das die API-Proxy-Bundles und Skripte zum Einrichten der Daten in einer Cloud Spanner-Datenbank enthält:
git clone https://github.com/apigee/devrel/tree/main/references/product-recommendations cd product-recommendations-v1Erstellen Sie das Dienstkonto
datareaderund weisen Sie ihm IAM-Rollen zu. Das Dienstkonto wird verwendet, um über den API-Proxy auf die Daten in BigQuery und der Cloud Spanner-Datenbank zuzugreifen.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" --quietLegen Sie Umgebungsvariablen fest:
# 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-east1Dabei gilt:
APIGEEX_PROJECTist der Name Ihres Apigee X-Projekts.API_DOMAIN_NAME: der Hostname, der auf der Seite Admin> Umgebungen > Gruppen in der Apigee X-Benutzeroberfläche konfiguriert wurde.
Wählen Sie auf der BigQuery-Seite der Google Cloud Console die Tabelle
prod_recommendationsaus und klicken Sie dann auf den Tab Vorschau, um die Ergebnisse aufzurufen.- Kopieren Sie einen beliebigen
userId-Wert. Legen Sie in Cloud Shell eine Umgebungsvariable fest:
export CUSTOMER_USERID=USER_IDErsetzen Sie
USER_IDdurch den WertuserId, den Sie im vorherigen Schritt kopiert haben.
- Kopieren Sie einen beliebigen
Rufen Sie in Cloud Shell die Ergebnisse der sortierten Produktempfehlung für den angegebenen
CUSTOMER_USERID-Wert auf: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 DESCDie Ausgabe zeigt eine einzelne Nutzer-ID, die vom Nutzer aufgerufene Element-ID und den Konfidenzwert der vorhergesagten Sitzung. Die Ausgabe sieht etwa so aus:
+-----------------------+----------------+--------------------------------------------+ | 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 | +-----------------------+----------------+--------------------------------------------+
Cloud Spanner-Datenbank erstellen und Produktkatalogdaten importieren
Erstellen Sie in Cloud Shell eine Cloud Spanner-Instanz in der angegebenen Region, erstellen Sie die Produktkatalogdatenbank und importieren Sie die Daten:
./setup_spanner.shDas Skript verwendet die Umgebungsvariable
CUSTOMER_USERIDund zeigt die erstellten Einträge an.Der Cloud Spanner-Produktkatalog enthält nur die Elemente, die im BigQuery-Trainingsschritt für einen bestimmten Nutzer verwendet wurden. Wenn Sie daher die Umgebungsvariable
CUSTOMER_USERIDnach dem Erstellen der Produktkatalogdaten in der Cloud Spanner-Datenbank ändern, müssen Sie das Shell-Skriptsetup_spanner.shnoch einmal ausführen, um die Daten neu auszufüllen.Überprüfen Sie die Daten in der Cloud Spanner-Datenbank:
gcloud spanner databases execute-sql $SPANNER_DATABASE --sql='SELECT * FROM products'Die Ausgabe zeigt die Produkt-IDs und die beschreibenden Informationen aus dem Spanner-Produktkatalog, einschließlich Preis und Bildpfad. Die entsprechende Ausgabe sieht etwa so aus:
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
Apigee-Proxy bereitstellen
In diesem Abschnitt führen Sie einen Maven-Befehl aus, um die folgenden Ressourcen zu erstellen:
- Ein Proxy mit dem Namen
product-recommendations-v1 - Ein API-Produkt mit dem Namen
product-recommendations-v1-$ENV - Ein App-Entwicklernutzer mit dem Namen
demo@any.com - Eine Anwendung mit dem Namen
product-recommendations-v1-app-$ENV
Um die Ressourcen zu erstellen, verwendet Maven die Datei pom.xml aus dem GitHub-Repository. Die Datei enthält die Installationsanleitungen und Schritte.
Der Profilabschnitt der Datei pom.xml enthält Werte für apigee.org, apigee.env, api.northbound.domain, gcp.projectid, googletoken.email und api.userid. Diese Werte variieren je nach Projekt und werden über die Befehlszeile festgelegt. Das folgende Beispiel zeigt den Abschnitt der Datei pom.xml, die die Werte enthält:
<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>
Sie legen diese Werte zuvor beim Einrichten der Cloud Spanner-Daten fest.
So stellen Sie den Proxy bereit:
Installieren Sie in Cloud Shell den Proxy und die zugehörigen Artefakte und testen Sie dann die 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_USERIDDie Ausgabe zeigt die Ausführung der Installationsschritte und die Ergebnisse der Integrationstest-API-Aufrufe. Es gibt einen Aufruf an den Endpunkt
/openapiund einen weiteren an den Endpunkt/products. Die Testergebnisse prüfen, ob der API-Proxy installiert, bereitgestellt und betriebsbereit ist. Die Ausgabe zeigt auch die Anmeldedaten der Anwendung, die Sie für nachfolgende API-Testaufrufe verwenden können.
Recommendations API testen
Legen Sie in Cloud Shell eine Umgebungsvariable für den API-Schlüssel der Anwendung fest. Führen Sie dazu einen curl-Aufruf an die Apigee API aus:
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)Notieren Sie sich den Wert von
APIKEY. Sie benötigen diese Informationen, wenn Sie später eine AppSheet-Anwendung erstellen.Führen Sie einen Testaufruf aus, um die Ergebnisse für den Wert
CUSTOMER_USERIDabzurufen, den Sie bei der Installation des API-Proxys angegeben haben:curl -s https://$ENVGROUP_HOSTNAME/v1/recommendations/products \ -H "x-apikey:$APIKEY" | jq
In der API, die in der OpenAPI-Spezifikation (OAS) definiert ist, kann die Anfrage die folgenden Header angeben:
x-apikey: Der Consumer-Key der Anwendung aus dem Sicherheitsschema.x-userid: Die Nutzer-ID, die die Anfrage stellt. Wenn nicht angegeben, verwendet dieser Wert standardmäßig den im Proxy konfigurierten WertCUSTOMER_USERID.cache-control: Der Zeitraum, in dem die Antwort im Cache gespeichert wird. Mit diesem Header können Sie die Antwort 300 Sekunden lang im Cache speichern oder durch Angabe vonno-cacheüberschreiben.
Wenn Sie den CUSTOMER_USERID-Wert ändern oder das Caching steuern möchten, können Sie die Headerwerte festlegen, wie im folgenden Beispielaufruf gezeigt:
curl -s "https://$ENVGROUP_HOSTNAME/v1/recommendations/products" \
-H "x-apikey:$APIKEY" \
-H "x-userid:$CUSTOMER_USERID" \
-H "Cache-Control:no-cache" | jq
Die Antwort auf den Beispielaufruf sieht in etwa so aus:
{
"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"
}
]
}
Apigee-Richtlinien
Die in den folgenden Abschnitten aufgeführten Apigee-Richtlinien werden im API-Proxy-Bundle in dieser Anleitung verwendet.
PreFlow
- SpikeArrest
- Back-End-Dienst BiqQuery vor Trafficspitzen schützen.
- Kontingent
- Drosseln Sie die API-Anfragen anhand der Nutzeranwendung und des Entwicklers. Die Drosselunglimits werden im API-Produkt konfiguriert.
- ResponseCache – URI
- Reduzieren Sie die Anfragen an das Data Warehouse von BiqQuery, indem Sie die Antwort des Dienstes im Cache speichern.
Produktablauf
- AssignMessage – Abfrageanfrage erstellen
- Legen Sie die HTTP-Anfrage mit einer SQL-Abfrage fest, mit der die Liste der Produktempfehlungen aus dem BigQuery-Dataset abgerufen wird.
- JavaScript- und ExtractVariable-Richtlinien
- Formatieren Sie die Daten aus dem BigQuery-Dienst und erstellen Sie eine nutzerfreundlichere Antwortnachricht.
- LookupCache – Cloud Spanner-Sitzung
- Suchen Sie die Sitzungs-ID der Cloud Spanner-Datenbank aus dem Apigee-Cache.
- ServiceCallout – Cloud Spanner-Sitzung
- Senden Sie eine Anfrage an den Cloud Spanner-Dienst und erstellen Sie eine Datenbanksitzung, wenn der Apigee-Cache keine Sitzungs-ID hat oder die ID abgelaufen ist.
- PopulateCache – Cloud Spanner-Sitzung
- Füllen Sie die Cloud Spanner-Sitzungs-ID in den Apigee-Cache aus.
- ServiceCallout – Produktkatalogsuche
- Produktdetails aus der Cloud Spanner-Produktkatalogdatenbank abrufen
- JavaScript – Produktdaten formatieren
- Erstellen Sie eine API-Antwortnachricht, die dem OAS entspricht. Formatieren Sie dazu die Daten aus der Produktkatalogdatenbank.
OpenAPI-Flow
- AssignMessage - OAS JSON
- Legen Sie die OAS-JSON-Antwort für die API fest.
Optional: AppSheet-Anwendung mit Apigee als Datenquelle erstellen
Wenn Sie Produktempfehlungen für Endnutzer der E-Commerce-Website und für Geschäftsnutzer anzeigen möchten, können Sie eine AppSheet-Anwendung erstellen, wie in diesem Abschnitt gezeigt.
AppSheet-Konto erstellen
Erstellen Sie mit Ihrer E-Mail-Adresse ein AppSheet-Konto.
Datenquelle erstellen
AppSheet verwendet den API-Proxy als Datenquelle für die neue Anwendung. So erstellen Sie eine Datenquelle:
- Melden Sie sich in AppSheet an.
- Klicken Sie auf der Seite Mein Konto auf Quellen > Neue Datenquelle.
- Geben Sie im Dialogfeld Neue Datenquelle hinzufügen den Namen des Proxys
product-recommendations-v1ein und klicken Sie dann auf Apigee. Legen Sie im Dialogfeld Apigee-Verbindungsinformationen hinzufügen die folgenden Optionen fest:
- Wählen Sie Manuell aus.
- Geben Sie im Feld Apigee API-Schlüssel den API-Schlüssel für Ihre Anwendung ein, den Sie zum Testen des Proxys verwendet haben. Wenn Sie den API-Schlüssel nicht haben, rufen Sie ihn in Cloud Shell ab, indem Sie
echo $APIKEY.ausführen. Geben Sie im Feld Apigee API Basispfad Folgendes ein:
https://ENVGROUP_HOSTNAME/v1/recommendationsErsetzen Sie ENVGROUP_HOSTNAME durch den Hostnamen, der in der Apigee X-UI für Administrator > Umgebungen > Gruppen konfiguriert ist.
Geben Sie im Feld API-Ressourcenpfade das Pfadsuffix
productsein.Klicken Sie auf Test.
Nachdem die Tests erfolgreich abgeschlossen wurden, klicken Sie auf Zugriff autorisieren.
Nachdem Sie den Zugriff autorisiert haben, wird in der AppSheet-Konsole eine neue Kachel für product-recommendations-v1 angezeigt.
Anwendung erstellen
- Rufen Sie die Seite App-Vorlagen-Apps für AppSheet auf.
- Klicken Sie auf Kopieren und anpassen. Das Dialogfeld App klonen wird angezeigt.
- Geben Sie im Feld App-Name den Namen des Proxys
product-recommendations-v1ein und klicken Sie dann auf App kopieren. Warten Sie einen Moment, bis die Anwendung erstellt ist. - Klicken Sie auf der Seite Willkommen bei Ihrer App auf App anpassen. Standardmäßig verwendet die Anwendung eine Beispieldatenquelle in einer Google-Tabelle.
Ändern Sie die Datenquelle so, dass sie der zuvor erstellten Apigee-Datenquelle entspricht:
- Klicken Sie auf + Neue Tabelle und dann auf Produktempfehlungen Version 1.
- Wählen Sie im Dialogfeld Tabelle/Tabelle auswählen die Option Produkte aus.
- Klicken Sie im Dialogfeld Neue Tabelle erstellen auf Schreibgeschützt und dann auf Diese Tabelle hinzufügen.
Die Anwendung wird mit dem Tab Produkte 2 und einer anderen Datenansicht angezeigt. Die neue Datenansicht hat unterschiedliche Werte für die Beschreibung und den Preis jedes Artikels. Beachten Sie, dass die Reihenfolge der Elemente nicht mit der Reihenfolge der Vorhersagen übereinstimmt.
Ändern Sie die Reihenfolge, in der Elemente von der Datenquelle zurückgegeben werden. Entfernen Sie dazu die Standardsortierung von AppSheet:
- Wählen Sie im seitlichen Navigationsmenü UX aus.
- Wählen Sie im Abschnitt Primäre Ansichten die Option Produkte 2 aus.
- Löschen Sie im Abschnitt Ansichtsoptionen neben Sortieren nach den Eintrag für Name, Aufsteigend. Beachten Sie, dass die in AppSheet angezeigte Reihenfolge jetzt mit dem Ergebnis des API-Aufrufs identisch ist, wobei das letzte Element aus der Antwort unten angezeigt wird.
Speichern Sie die Anwendung.
Sie können optional die ursprüngliche Produkttabelle und UX löschen und die Tabelle „Produkte 2“ umbenennen und in „Produktempfehlungen“ ansehen.
Bereinigen
Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie entweder das Projekt, das die Ressourcen enthält, oder Sie behalten das Projekt und löschen die einzelnen Ressourcen.
Projekt löschen
- Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.
- Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie dann auf Löschen.
- Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Shut down (Beenden), um das Projekt zu löschen.
Einzelne Ressourcen löschen
Löschen Sie die Flex-Slot-Reservierungen, das BigQuery-Dataset und das AI Platform-Modell, um wiederkehrende Kosten zu vermeiden.
BigQuery Flex-Slot-Reservierungen löschen
- Wählen Sie auf der BigQuery-Seite in der Google Cloud Console Kapazitätsverwaltung aus und klicken Sie dann auf den Tab Reservierungen.
- Öffnen Sie den Eintrag Model.
- Klicken Sie neben der Reservierung auf Aktionen anzeigen und dann auf Löschen.
- Klicken Sie neben dem Eintrag Model auf Aktionen ansehen und dann auf Löschen.
Löschen Sie in Cloud Shell die Bereitstellung, den Proxy und die zugehörigen Artefakte:
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=cleanEntfernen Sie die Spanner-Ressourcen:
./cleanup_spanner.sh
BigQuery-Dataset löschen
- Maximieren Sie auf der BigQuery-Seite der Google Cloud Console im Abschnitt Ressourcen das Projekt, in dem Sie diese Anleitung abgeschlossen haben.
- Wählen Sie das Dataset bqml aus und klicken Sie dann auf Dataset löschen.
- Geben Sie im eingeblendeten Fenster
bqmlein und klicken Sie dann auf Löschen.
AI Platform-Modell löschen
Rufen Sie in der Google Cloud Console die Seite AI Platform-Modelle auf.
Klicken Sie in der Modellliste auf rpm_bqml_model.
Klicken Sie auf der Seite Modelldetails das Kästchen für die Version V_1 (default) an.
Klicken Sie auf Mehr und dann auf Löschen.
Klicken Sie nach dem Löschen der Version auf Zurück, um zur Modellliste zurückzukehren.
Klicken Sie auf das Kästchen für das Modell rpm_bqml_model.
Klicken Sie auf Mehr und anschließend auf Löschen.
Erstellen Sie in der Cloud Shell das Dienstkonto:
gcloud iam service-accounts delete $SA
Nächste Schritte
- Google Cloud-Dienste über Apigee API-Proxys aufrufen
- Weitere Referenzarchitekturen, Diagramme, Anleitungen und Best Practices finden Sie im Cloud-Architekturcenter.