Intelligente API erstellen, um mit Apigee, BigQuery ML und Cloud Spanner die Kundeneignung zum Kauf vorherzusagen

Last reviewed 2022-06-29 UTC

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:

Architektur einer API zur Vorhersage der Kaufneigung des Kunden.

Das Diagramm zeigt die folgende Architektur:

  1. 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.
  2. Ein API-Proxy ruft die Produktempfehlungsdaten für die Nutzer-ID aus einem BigQuery-Dataset ab.
  3. Der API-Proxy erstellt ein Callout zum Abrufen der Daten aus der primären Produktdatenbank in einer Cloud Spanner-Instanz.
  4. Der API-Proxy aggregiert die Daten aus den Produktempfehlungen und den primären Datasets des Produkts.
  5. 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. Neuen Google Cloud-Nutzern steht möglicherweise eine kostenlose Testversion zur Verfügung.

Vorbereitung

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  2. Die Abrechnung für das Google Cloud-Projekt muss aktiviert sein.

  3. Enable the 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.

    Enable the APIs

  4. In the Google Cloud console, activate Cloud Shell.

    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.

  5. 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.
  6. 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.
  7. 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:

  1. Rufen Sie im Google Cloud Marketplace die Seite Analytics-Beispiel auf.

    Zum Analytics-Beispiel

  2. Klicken Sie auf Dataset aufrufen. Die Seite "BigQuery SQL-Arbeitsbereich" wird mit dem ausgewählten Analytics-Beispiel-Dataset geöffnet.

  3. Klicken Sie im Abschnitt Explorer neben Ihrem Projekt auf Aktionen anzeigen und dann auf Dataset erstellen.

  4. Führen Sie im angezeigten Dialogfeld Dataset erstellen die folgenden Schritte aus:

    1. Geben Sie im Feld Dataset-ID den Wert bqml ein.
    2. Wählen Sie in der Liste Datenspeicherort die Option us (mehrere Regionen in den USA) aus.
    3. Klicken Sie auf Dataset erstellen.
  5. Klicken Sie auf Zum Dataset und dann auf Neue Abfrage erstellen.

  6. 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_stats wird erstellt und mit Trainingsdaten gefüllt.

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

  1. Öffnen Sie in der Google Cloud Console die Seite BigQuery:

    BigQuery aufrufen

  2. Klicken Sie auf Kapazitätsverwaltung und dann auf Reservierungen.

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

  4. Klicken Sie auf dem Tab Reservierungen auf Slots erwerben.

  5. Führen Sie auf der Seite Slots erwerben folgende Schritte aus:

    1. Wählen Sie in der Liste Zusicherungsdauer die Option Flex aus.
    2. Wählen Sie in der Liste Standort die Option us (mehrere Regionen in den USA) aus.
    3. Wählen Sie in der Liste Anzahl der Slots die Option 500 aus.
    4. Klicken Sie auf Next (Weiter).
    5. Geben Sie im Feld Kaufbestätigung CONFIRM ein und klicken Sie dann auf Kaufen.

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

  7. Klicken Sie auf Reservierung erstellen und legen Sie die folgenden Optionen fest:

    1. Geben Sie unter Name der Reservierung den Wert model ein.
    2. Wählen Sie in der Liste Standort die Option us (mehrere Regionen in den USA) aus.
    3. Geben Sie unter Anzahl der Slots den Wert 500 ein.
    4. Klicken Sie auf Speichern. Dadurch kehren Sie zur Seite Reservierungen zurück.
  8. Wählen Sie neben der Reservierung model in der Spalte Aktionen die Option Zuweisung erstellen aus.

  9. Klicken Sie unter Organisation, Ordner oder Projekt auswählen auf Durchsuchen.

  10. Geben Sie den Namen des Projekts ein, in dem Sie diese Anleitung durcharbeiten, oder wählen Sie es aus der Liste aus.

  11. Klicken Sie auf Auswählen und anschließend auf Erstellen.

Modell erstellen, trainieren und bereitstellen

So erstellen, trainieren und stellen Sie das Matrixfaktorisierungsmodell bereit:

  1. Klicken Sie in der BigQuery-Seite der Google Cloud Console auf Neue Abfrage erstellen.
  2. Führen Sie die SQL-Anweisung CREATE MODEL aus:

    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.

  1. 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
  2. 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.

  1. 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-v1
    
  2. Erstellen Sie das Dienstkonto datareader und 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" --quiet
    
  3. Legen 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-east1
    

    Dabei gilt:

    • APIGEEX_PROJECT ist 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.
  4. Wählen Sie auf der BigQuery-Seite der Google Cloud Console die Tabelle prod_recommendations aus und klicken Sie dann auf den Tab Vorschau, um die Ergebnisse aufzurufen.

    1. Kopieren Sie einen beliebigen userId-Wert.
    2. Legen Sie in Cloud Shell eine Umgebungsvariable fest:

      export CUSTOMER_USERID=USER_ID
      

      Ersetzen Sie USER_ID durch den Wert userId, den Sie im vorherigen Schritt kopiert haben.

  5. 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 DESC
    

    Die 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

  1. Erstellen Sie in Cloud Shell eine Cloud Spanner-Instanz in der angegebenen Region, erstellen Sie die Produktkatalogdatenbank und importieren Sie die Daten:

    ./setup_spanner.sh
    

    Das Skript verwendet die Umgebungsvariable CUSTOMER_USERID und 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_USERID nach dem Erstellen der Produktkatalogdaten in der Cloud Spanner-Datenbank ändern, müssen Sie das Shell-Skript setup_spanner.sh noch einmal ausführen, um die Daten neu auszufüllen.

  2. Ü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_USERID
    

    Die Ausgabe zeigt die Ausführung der Installationsschritte und die Ergebnisse der Integrationstest-API-Aufrufe. Es gibt einen Aufruf an den Endpunkt /openapi und 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

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

  2. Führen Sie einen Testaufruf aus, um die Ergebnisse für den Wert CUSTOMER_USERID abzurufen, 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 Wert CUSTOMER_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 von no-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:

  1. Melden Sie sich in AppSheet an.
  2. Klicken Sie auf der Seite Mein Konto auf Quellen > Neue Datenquelle.
  3. Geben Sie im Dialogfeld Neue Datenquelle hinzufügen den Namen des Proxys product-recommendations-v1 ein und klicken Sie dann auf Apigee.
  4. Legen Sie im Dialogfeld Apigee-Verbindungsinformationen hinzufügen die folgenden Optionen fest:

    1. Wählen Sie Manuell aus.
    2. 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.
    3. Geben Sie im Feld Apigee API Basispfad Folgendes ein:

      https://ENVGROUP_HOSTNAME/v1/recommendations
      

      Ersetzen Sie ENVGROUP_HOSTNAME durch den Hostnamen, der in der Apigee X-UI für Administrator > Umgebungen > Gruppen konfiguriert ist.

    4. Geben Sie im Feld API-Ressourcenpfade das Pfadsuffix products ein.

    5. Klicken Sie auf Test.

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

  1. Rufen Sie die Seite App-Vorlagen-Apps für AppSheet auf.
  2. Klicken Sie auf Kopieren und anpassen. Das Dialogfeld App klonen wird angezeigt.
  3. Geben Sie im Feld App-Name den Namen des Proxys product-recommendations-v1 ein und klicken Sie dann auf App kopieren. Warten Sie einen Moment, bis die Anwendung erstellt ist.
  4. Klicken Sie auf der Seite Willkommen bei Ihrer App auf App anpassen. Standardmäßig verwendet die Anwendung eine Beispieldatenquelle in einer Google-Tabelle.
  5. Ändern Sie die Datenquelle so, dass sie der zuvor erstellten Apigee-Datenquelle entspricht:

    1. Klicken Sie auf + Neue Tabelle und dann auf Produktempfehlungen Version 1.
    2. Wählen Sie im Dialogfeld Tabelle/Tabelle auswählen die Option Produkte aus.
    3. 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.

  6. Ändern Sie die Reihenfolge, in der Elemente von der Datenquelle zurückgegeben werden. Entfernen Sie dazu die Standardsortierung von AppSheet:

    1. Wählen Sie im seitlichen Navigationsmenü UX aus.
    2. Wählen Sie im Abschnitt Primäre Ansichten die Option Produkte 2 aus.
    3. 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.
  7. 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

  1. In the Google Cloud console, go to the Manage resources page.

    Go to Manage resources

  2. In the project list, select the project that you want to delete, and then click Delete.
  3. In the dialog, type the project ID, and then click Shut down to delete the project.

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

  1. Wählen Sie auf der BigQuery-Seite in der Google Cloud Console Kapazitätsverwaltung aus und klicken Sie dann auf den Tab Reservierungen.
  2. Öffnen Sie den Eintrag Model.
  3. Klicken Sie neben der Reservierung auf Aktionen anzeigen und dann auf Löschen.
  4. Klicken Sie neben dem Eintrag Model auf Aktionen ansehen und dann auf Löschen.
  5. 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=clean
    
  6. Entfernen Sie die Spanner-Ressourcen:

    ./cleanup_spanner.sh
    

BigQuery-Dataset löschen

  1. Maximieren Sie auf der BigQuery-Seite der Google Cloud Console im Abschnitt Ressourcen das Projekt, in dem Sie diese Anleitung abgeschlossen haben.
  2. Wählen Sie das Dataset bqml aus und klicken Sie dann auf Dataset löschen.
  3. Geben Sie im eingeblendeten Fenster bqml ein und klicken Sie dann auf Löschen.

AI Platform-Modell löschen

  1. Rufen Sie in der Google Cloud Console die Seite AI Platform-Modelle auf.

    Zur Seite „AI Platform-Modelle“

  2. Klicken Sie in der Modellliste auf rpm_bqml_model.

  3. Klicken Sie auf der Seite Modelldetails das Kästchen für die Version V_1 (default) an.

  4. Klicken Sie auf Mehr und dann auf Löschen.

  5. Klicken Sie nach dem Löschen der Version auf Zurück, um zur Modellliste zurückzukehren.

  6. Klicken Sie auf das Kästchen für das Modell rpm_bqml_model.

  7. Klicken Sie auf Mehr und anschließend auf Löschen.

  8. Erstellen Sie in der Cloud Shell das Dienstkonto:

    gcloud iam service-accounts delete $SA
    

Nächste Schritte