Crea una API inteligente para predecir la propensión del cliente a comprar mediante Apigee, BigQuery ML y Cloud Spanner

Last reviewed 2022-06-29 UTC

En este instructivo, se muestra cómo crear una API que pueda predecir la probabilidad de que un cliente realice una compra. Para crear la API, usa Apigee, BigQuery ML y Cloud Spanner.

Este instructivo está dirigido a desarrolladores de API y especialistas en datos que deseen generar más ingresos a través de plataformas de comercio electrónico o de varios canales mediante una experiencia más personalizada para los usuarios. Se supone que estás familiarizado con BigQuery, Apigee, Google Cloud CLI y Apache Maven.

La API que creas usa predicciones en línea para realizar acciones en tiempo real en función del comportamiento de los usuarios en tu sitio web. Las predicciones en línea combinan las estadísticas del aprendizaje automático (AA) con un catálogo de productos y otra información, lo que te ayuda a crear una mejor experiencia para los clientes en varios canales. La arquitectura de la API que creas se muestra en el siguiente diagrama:

Arquitectura de una API para predecir la propensión del cliente a comprar.

En el diagrama se muestra la siguiente arquitectura:

  1. Una aplicación para dispositivos móviles envía una solicitud a la API que se implementa en la plataforma de Apigee. La solicitud recupera los datos de recomendaciones de productos para el usuario que accedió.
  2. Un proxy de API obtiene los datos de recomendaciones de productos para el ID de usuario desde un conjunto de datos de BigQuery.
  3. El proxy de API realiza un texto destacado para recuperar los datos de la base de datos principal del producto en una instancia de Cloud Spanner.
  4. El proxy de API agrega los datos de las recomendaciones de productos y los conjuntos de datos principales del producto.
  5. Se muestra una respuesta a la aplicación para dispositivos móviles.

Objetivos

  • Crear un conjunto de datos de propensión de compra del cliente en BigQuery.
  • Importar los datos del catálogo de productos a la base de datos de Cloud Spanner.
  • Importar e implementar el proxy de la API de Apigee.
  • Integrar los datos de propensión de compra de los clientes desde BigQuery con el catálogo de productos y la información de precios en la base de datos de Cloud Spanner.
  • Crea una vista agregada de las recomendaciones de productos.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

  • Ranuras flexibles de BigQuery ML y BigQuery
  • Cloud Spanner
  • Apigee

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Antes de comenzar

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

    Go to project selector

  2. Make sure that billing is enabled for your Google Cloud project.

  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. Si aún no tienes una cuenta de Apigee X, configura Apigee para aprovisionar una instancia de Apigee X. El aprovisionamiento puede tomar hasta una hora.
  7. Configura tu organización de Apigee X para permitir el acceso externo.

Cuando finalices las tareas que se describen en este documento, puedes borrar los recursos que creaste para evitar que continúe la facturación. Para obtener más información, consulta Cómo realizar una limpieza.

Crea un conjunto de datos de recomendaciones de comercio electrónico mediante BigQuery ML

En esta sección, usarás consultas de SQL estándar en BigQuery ML para crear un modelo de AA, entrenarlo con datos de clientes en BigQuery y, luego, implementarlo. No tienes que exportar tus datos ni compilar una canalización de implementación y entrenamiento de modelos. BigQuery escala de forma automática para controlar los recursos de procesamiento que necesites.

En el modelo de AA que creas en este instructivo, se usa la factorización de matrices, un método común y efectivo para la creación de un sistema de recomendación basado en los datos de preferencias del usuario.

En este instructivo, usarás el conjunto de datos Google Analytics Sample, que se aloja a nivel público en BigQuery. Este conjunto de datos proporciona 12 meses (de agosto de 2016 a agosto de 2017) de datos ofuscados de Analytics 360 de Google Merchandising Store, una tienda de comercio electrónico real que vende productos de la marca Google.

Procesa los datos de muestra

Cuando usas la factorización de matrices, evalúas los comentarios explícitos o implícitos de los usuarios para determinar las preferencias de los clientes. Para usar comentarios explícitos, el conjunto de datos debe contener datos sobre las preferencias de productos de los usuarios, como las calificaciones por estrellas del 1 al 5. Si no hay comentarios explícitos disponibles, debes usar otras métricas de comportamiento para inferir las preferencias del cliente, como el tiempo total que un usuario pasa en una página de detalles del producto. En este instructivo, usarás datos de duración de sesión para inferir las preferencias del cliente.

Para entrenar el modelo de factorización de matrices, necesitas una tabla con columnas que identifiquen al cliente, el artículo que se está calificando y la calificación implícita. En esta sección, crearás esta tabla con las columnas userid, itemId y session_duration. La columna session_duration contiene la duración de la sesión del usuario en la página del producto del elemento determinado.

Para crear la tabla con los datos del conjunto de datos Analytics Sample, haz lo siguiente:

  1. En Google Cloud Marketplace, ve a la página Analytics Sample.

    Ir a Analytics Saple

  2. Haz clic en Ver conjunto de datos. Se abrirá la página del lugar de trabajo de BigQuery SQL con el conjunto de datos Analytics Sample seleccionado.

  3. En la sección Explorador, junto a tu proyecto, haz clic en Ver acciones y, luego, en Crear conjunto de datos.

  4. En el cuadro de diálogo Crear conjunto de datos que aparece, haz lo siguiente:

    1. En el campo ID de conjunto de datos, ingresa bqml.
    2. En la lista Ubicación de los datos, selecciona us (varias regiones en Estados Unidos).
    3. Haga clic en Crear conjunto de datos.

  5. Haz clic en Ir al conjunto de datos y, luego, en Redactar consulta nueva.

  6. En el Editor de consultas, crea una tabla que contenga los datos de entrenamiento mediante la ejecución de la siguiente instrucción de SQL:

    CREATE OR REPLACE TABLE bqml.aggregate_web_stats AS (
  WITH
    durations AS (
      --calculate pageview durations
      SELECT
        CONCAT(fullVisitorId,'-',
             CAST(visitNumber AS STRING),'-',
             CAST(hitNumber AS STRING) ) AS visitorId_session_hit,
        LEAD(time, 1) OVER (
          PARTITION BY CONCAT(fullVisitorId,'-',CAST(visitNumber AS STRING))
          ORDER BY
          time ASC ) - time AS pageview_duration
      FROM
        `bigquery-public-data.google_analytics_sample.ga_sessions_2017*`,
        UNNEST(hits) AS hit
    ),
    prodview_durations AS (
      --filter for product detail pages only
     SELECT
        CONCAT(fullVisitorId,'-',CAST(visitNumber AS STRING)) AS userId,
        productSKU AS itemId,
        IFNULL(dur.pageview_duration,
         1) AS pageview_duration,
      FROM
        `bigquery-public-data.google_analytics_sample.ga_sessions_2017*` t,
        UNNEST(hits) AS hits,
        UNNEST(hits.product) AS hits_product
      JOIN
        durations dur
      ON
        CONCAT(fullVisitorId,'-',
               CAST(visitNumber AS STRING),'-',
               CAST(hitNumber AS STRING)) = dur.visitorId_session_hit
      WHERE
      eCommerceAction.action_type = "2"
    ),
    aggregate_web_stats AS(
      --sum pageview durations by userId, itemId
      SELECT
        userId,
        itemId,
        SUM(pageview_duration) AS session_duration
      FROM
        prodview_durations
      GROUP BY
        userId,
        itemId )
    SELECT
    *
   FROM
      aggregate_web_stats
);

    La tabla bqml.aggregate_web_stats se crea y se propaga con los datos de entrenamiento.

  7. Para ver una muestra de los datos, en el Editor de consultas, ejecuta la siguiente instrucción de SQL:

    SELECT
*
FROM
  bqml.aggregate_web_stats
LIMIT
  10;

En el resultado se muestra una tabla que tiene una fila para cada ID de usuario que incluye el ID del artículo que vio el usuario y la duración de su sesión. La salida es similar a lo siguiente:

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

Compra ranuras flexibles

Si usas precios bajo demanda para BigQuery, a fin de entrenar un modelo de factorización de matrices, debes comprar ranuras flexibles y, luego, crearles reservas y asignaciones. Si usas precios de tarifa plana con BigQuery, puedes omitir esta sección e ir a Crea, entrena e implementa el modelo.

Para comprar ranuras flexibles, debes tener un rol de IAM que incluya el permiso bigquery.reservations.create. Este permiso se otorga al propietario del proyecto y se incluye en los roles de IAM BigQuery Admin (roles/bigquery.admin) y BigQuery Resource Admin (roles/bigquery.resourceAdmin).

  1. En Google Cloud Console, ve a la página de BigQuery:

    Ir a BigQuery

  2. Haz clic en Administración de capacidad y, luego, en Reservas.

  3. Si se te redirecciona a la página API de reservas de BigQuery para habilitar la API, haz clic en Habilitar. De lo contrario, continúa con el paso siguiente.

  4. En la pestaña Reservas, haz clic en Comprar ranuras.

  5. En la página Comprar ranuras, sigue estos pasos:

    1. En la lista Duración del compromiso, selecciona Flex.
    2. En la lista Ubicación, selecciona us (varias regiones en Estados Unidos)
    3. En la lista Cantidad de ranuras, selecciona 500.
    4. Haga clic en Next.

    5. En el campo Confirmación de compra, escribe CONFIRM y, luego, haz clic en Comprar.

  6. Haz clic en Ver compromisos de ranuras.

    Espera 20 minutos para que se aprovisione la capacidad. Después de aprovisionar la capacidad, la columna Estado del compromiso de ranuras muestra .

  7. Haz clic en Crear reserva y, luego, configura las siguientes opciones:

    1. En Nombre de reserva, ingresa model.
    2. En la lista Ubicación, selecciona us (varias regiones en Estados Unidos)
    3. En Cantidad de ranuras, ingresa 500.
    4. Haz clic en Guardar. Esto te vuelve a llevar a la página Reservas.

  8. Junto a la reserva model, en la columna Acciones, selecciona Crear asignación.

  9. En Selecciona una organización, una carpeta o un proyecto, haz clic en Explorar.

  10. Ingresa el nombre del proyecto en el que completaste este instructivo o selecciónalo de la lista.

  11. Haz clic en Seleccionar y, luego, en Crear.

Crea, entrena e implementa el modelo

Para crear, entrenar e implementar el modelo de factorización de matrices, haz lo siguiente:

  1. En la página de BigQuery de la consola de Google Cloud, haz clic en Redactar consulta nueva.

  2. Ejecuta la instrucción de SQL CREATE MODEL:

    CREATE OR REPLACE MODEL bqml.retail_recommender`
  OPTIONS(model_type='matrix_factorization',
        user_col='userId',
        item_col='itemId',
        rating_col='session_duration',
        feedback_type='implicit'
        )
  AS
  SELECT * FROM bqml.aggregate_web_stats;

Una vez que finaliza el entrenamiento, el modelo entrenado se implementa como el modelo bqml.retail_recommender.

Usa el modelo entrenado para hacer predicciones

En esta sección, para obtener predicciones del modelo bqml.retail_recommender implementado, usa la función de SQL ML.RECOMMEND.

  1. En la página de BigQuery de la consola de Google Cloud, crea una consulta y obtén predicciones que representen las 5 recomendaciones principales para un userId especificado:

    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;

    En el resultado, se muestra una fila para la confianza de duración prevista de la sesión (mayor es mejor), el ID del usuario asociado y el ID del artículo que el usuario vio. El resultado es similar a este:

    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. Para obtener las 5 predicciones principales para todos los usuarios, ejecuta la siguiente instrucción de SQL. La instrucción genera muchas filas, por lo que el resultado se escribe en una tabla y, luego, se recuperan los primeros diez registros para que puedas ver un ejemplo de los datos.

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

    En el resultado, se muestran varios ID de usuario, el ID del artículo que el usuario vio y la confianza de la duración prevista de la sesión. El resultado es similar al siguiente:

    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

Configura datos de Cloud Spanner

En las secciones siguientes de este instructivo, usarás la CLI de gcloud y Maven. Ejecuta los comandos para ambas herramientas desde Cloud Shell. No se necesitan instalaciones para usar las herramientas.

  1. En Cloud Shell, clona el repositorio de GitHut de recomendaciones de productos que contiene el paquete de proxy de API de recomendaciones de productos y las secuencias de comandos para configurar los datos en una base de datos de Cloud Spanner:

    git clone https://github.com/apigee/devrel/tree/main/references/product-recommendations
cd product-recommendations-v1

  2. Crea la cuenta de servicio datareader y asígnale roles de IAM. La cuenta de servicio se usa para acceder a los datos en BigQuery y la base de datos de Cloud Spanner desde el proxy de API.

    gcloud iam service-accounts create datareader --display-name="Data reader for BigQuery and Spanner Demo"
gcloud iam service-accounts list | grep datareader
gcloud iam service-accounts create datareader --display-name="Data reader for Apigee, BigQuery, and Spanner Demo"
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/spanner.databaseUser" --quiet
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/spanner.databaseReader" --quiet
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/bigquery.dataViewer" --quiet
gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SA" --role="roles/bigquery.user" --quiet

  3. Establece las variables de entorno:

    # 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

    Reemplaza lo siguiente:

    • APIGEEX_PROJECT: el nombre de tu proyecto de Apigee X.
    • API_DOMAIN_NAME: el nombre de host configurado en la página Administrador > Entornos > Grupos en la IU de Apigee X.

  4. En la página de BigQuery de la consola de Google Cloud, selecciona la tabla prod_recommendations y haz clic en la pestaña Vista previa para ver los resultados.

    1. Copia cualquier valor de userId.

    2. En Cloud Shell, configura una variable de entorno:

      export CUSTOMER_USERID=USER_ID

      Reemplaza USER_ID por el valor de userId que copiaste en el paso anterior.

  5. En Cloud Shell, muestra los resultados de recomendación de productos ordenados para el valor de CUSTOMER_USERID especificado:

    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

    El resultado muestra un ID de usuario individual, el ID del artículo que vio el usuario y la confianza de la duración prevista de la sesión. El resultado es similar al siguiente:

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

Crea una base de datos de Cloud Spanner e importa datos del catálogo de productos

  1. En Cloud Shell, crea una instancia de Cloud Spanner en la región especificada, crea la base de datos del catálogo de productos e importa los datos:

    ./setup_spanner.sh

    La secuencia de comandos usa la variable de entorno CUSTOMER_USERID y muestra las entradas que se crearon.

    El catálogo de productos de Cloud Spanner solo contiene los elementos que se usaron en el paso de entrenamiento de BigQuery para un usuario específico. Por lo tanto, si cambias la variable de entorno CUSTOMER_USERID después de crear los datos del catálogo de productos en la base de datos de Cloud Spanner, debes volver a ejecutar la secuencia de comandos de shell setup_spanner.sh para volver a propagar los datos.

  2. Verifica los datos en la base de datos de Cloud Spanner:

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

    En el resultado, se muestran los ID de los productos y la información descriptiva del catálogo de productos de Spanner, incluido el precio y la ruta de la imagen. El resultado es similar al siguiente:

    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

Implementa el proxy de Apigee

En esta sección, debes ejecutar un comando de Maven para crear los siguientes recursos:

  • Un proxy llamado product-recommendations-v1
  • Un producto de API llamado product-recommendations-v1-$ENV
  • Un usuario desarrollador de aplicaciones llamado demo@any.com
  • Una app llamada product-recommendations-v1-app-$ENV

Para crear los recursos, Maven usa el archivo pom.xml del repositorio de GitHub. El archivo contiene instrucciones y pasos de instalación.

La sección de perfil del archivo pom.xml contiene valores para apigee.org, apigee.env, api.northbound.domain, gcp.projectid, googletoken.email y api.userid. Estos valores varían según el proyecto y se establecen con la línea de comandos. En el siguiente ejemplo, se muestra la sección del archivo pom.xml que contiene los valores:

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

Estableces estos valores antes cuando configuras los datos de Cloud Spanner.

Para implementar el proxy, haz lo siguiente:

  • En Cloud Shell, instala el proxy y sus artefactos asociados y, luego, prueba la 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

    El resultado muestra la ejecución de los pasos de instalación y los resultados de las llamadas a la API de prueba de integración. Hay una llamada al extremo /openapi y otra al extremo /products. Los resultados de la prueba verifican que el proxy de API se haya instalado e implementado y que esté en funcionamiento. En el resultado, también se muestran las credenciales de la app que puedes usar para las llamadas de prueba posteriores a la API.

Prueba la API de recomendaciones

  1. En Cloud Shell, establece una variable de entorno para la clave de API de la app mediante una llamada curl a la API de 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)

    Anota el valor APIKEY; necesitas esta información si creas una app de AppSheet más adelante de forma opcional.

  2. Para obtener los resultados del valor CUSTOMER_USERID que especificaste cuando instalaste el proxy de API, haz una llamada de prueba:

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

La API que define la especificación de OpenAPI (OAS) permite que la solicitud especifique los siguientes encabezados:

  • x-apikey: La clave de consumidor de la app del esquema de seguridad.
  • x-userid: El identificador del usuario que realiza la solicitud. Si no se proporciona, este valor se establece de forma predeterminada en el valor CUSTOMER_USERID que se configura en el proxy.
  • cache-control: La cantidad de tiempo que se almacena en caché la respuesta. Este encabezado te permite almacenar en caché la respuesta durante 300 segundos o anular mediante la especificación de no-cache.

Para cambiar el valor CUSTOMER_USERID o controlar el almacenamiento en caché, puedes configurar los valores de encabezado como se muestra en la siguiente llamada de ejemplo:

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

La respuesta a la llamada de ejemplo es similar a la siguiente:

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

Políticas de Apigee

Las políticas de Apigee que se enumeran en las siguientes secciones se usan en el paquete del proxy de API en este instructivo.

Pre-flow

SpikeArrest
Protege el servicio de backend de BigQuery de los aumentos de tráfico.
Cuota
Limita las solicitudes a la API según el desarrollador y la aplicación del consumidor. Los límites de regulación se configuran en el producto de API.
ResponseCache - uri
Reduce las solicitudes al almacén de datos de BigQuery mediante el almacenamiento en caché de la respuesta del servicio.

Products-flow

AssignMessage: crear solicitud de consulta
Configura la solicitud HTTP con una consulta de SQL para recuperar la lista de recomendaciones de productos del conjunto de datos de BigQuery.
Políticas JavaScript y ExtractVariable
Da formato a los datos del servicio de BigQuery y crea un mensaje de respuesta más fácil de usar.
LookupCache: sesión de Cloud Spanner
Busca el ID de sesión de la base de datos de Cloud Spanner desde la caché de Apigee.
ServiceCallout: sesión de Cloud Spanner
Realiza una solicitud al servicio de Cloud Spanner y crea una sesión de base de datos si la caché de Apigee no tiene un ID de sesión o el ID venció.
PopulateCache: sesión de Cloud Spanner
Propaga el ID de sesión de Cloud Spanner a la caché de Apigee.
ServiceCallout: búsqueda del catálogo de productos
Recupera los detalles del producto desde la base de datos del catálogo de productos de Cloud Spanner.
JavaScript: formatear datos de productos
Crea un mensaje de respuesta de API que cumple con el OAS mediante el formato de los datos de la base de datos del catálogo de productos.

OpenAPI-flow

AssignMessage: JSON de OAS
Configura la respuesta JSON de OAS para la API.

Opcional: Crea una app de AppSheet con Apigee como fuente de datos

A fin de mostrar las recomendaciones de productos a los usuarios finales del sitio web de comercio electrónico y a los usuarios empresariales, puedes crear una app de AppSheet como se muestra en esta sección.

Crea una cuenta de AppSheet

Crea una cuenta de AppSheet con tu dirección de correo electrónico.

Crea una fuente de datos

AppSheet usa el proxy de API como fuente de datos para tu app nueva. A fin de crear una fuente de datos, haz lo siguiente:

  1. Accede a AppSheet.
  2. En la página Mi cuenta, haz clic en Fuentes > Fuente de datos nueva.
  3. En el cuadro de diálogo Agregar una fuente de datos nueva, ingresa el nombre del proxy product-recommendations-v1 y, luego, haz clic en Apigee.

  4. En el cuadro de diálogo Agregar información de conexión a la API de Apigee, configura las siguientes opciones:

    1. Selecciona Manual.
    2. En el campo Clave de API de Apigee, ingresa la clave de API para tu app, que usaste a fin de probar el proxy. Si no tienes la clave de API, ejecuta echo $APIKEY. en Cloud Shell para obtenerla.

    3. En el campo Ruta de acceso base de la API de Apigee, ingresa lo siguiente:

      https://ENVGROUP_HOSTNAME/v1/recommendations

      Reemplaza ENVGROUP_HOSTNAME por el nombre de host configurado en la IU de Apigee X para Admin > Entornos > Grupos.

    4. En el campo Rutas de recursos de la API, ingresa el sufijo de ruta products.

    5. Haga clic en Test.

    6. Una vez que las pruebas se hayan completado correctamente, haz clic en Autorizar acceso.

Después de autorizar el acceso, la consola de AppSheet muestra un mosaico nuevo para product-recommendations-v1.

Cree la app

  1. Ve a la página products-template app de AppSheet.
  2. Haz clic en Copiar y personalizar. Se muestra el cuadro de diálogo Clonar tu app.
  3. En el campo Nombre de la app, ingresa el nombre del proxy, product-recommendations-v1, y haz clic en Copiar app. Espera unos minutos para que se cree tu app.
  4. En la página Bienvenido a tu app, haz clic en Personalizar app. De forma predeterminada, la app usa una fuente de datos de muestra en una Hoja de cálculo de Google.

  5. Cambia la fuente de datos para que coincida con la fuente de datos de Apigee que creaste antes:

    1. Haz clic en + Nueva tabla y, luego, en product recommendations v1.
    2. En el cuadro de diálogo Elegir una hoja/tabla, selecciona productos.
    3. En el cuadro de diálogo Crear una tabla nueva, haz clic en Solo lectura y, luego, en Agregar esta tabla.

    La app se muestra con una pestaña products 2 y una vista de datos diferente. La vista de datos nueva tiene valores diferentes para la descripción y el precio de cada artículo. Ten en cuenta que el orden de los elementos no es el mismo que el de las predicciones.

  6. Para cambiar el orden en que se muestran los elementos de la fuente de datos, quita el orden predeterminado de AppSheet:

    1. En el menú de navegación lateral, selecciona UX.
    2. En la sección Vistas principales, selecciona products 2.
    3. En la sección Opciones de vista, junto a Ordenar por, borra la entrada de nombre, Ascendente. Observa que el orden que se muestra en AppSheet ahora es el mismo que el resultado de la llamada a la API, con el último elemento de la respuesta en la parte inferior.

  7. Guarda la app.

De manera opcional, puedes borrar la UX y la tabla originales de Product, y cambiar el nombre de la tabla y la vista “products 2” por “Product Recommendations”.

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra el proyecto

  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.

Borra los recursos individuales

Para evitar costos recurrentes, borra las reservas de ranuras flexibles de BigQuery, el conjunto de datos de BigQuery y el modelo de AI Platform.

Borra las reservas de ranuras flexibles de BigQuery

  1. En la página de BigQuery de la consola de Google Cloud, selecciona Administración de capacidad y, luego, haz clic en la pestaña Reservas.
  2. Abre la entrada del modelo.
  3. Junto a la reserva, haz clic en Ver acciones y, luego, en Borrar.
  4. Junto a la entrada modelo, haz clic en Ver acciones y, luego, en Borrar.

  5. En Cloud Shell, borra la implementación, el proxy y sus artefactos asociados:

    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. Quita los recursos de Spanner:

    ./cleanup_spanner.sh

Borra el conjunto de datos de BigQuery

  1. En la página de BigQuery de la consola de Google Cloud, en la sección Recursos, expande el proyecto en el que completaste este instructivo.
  2. Selecciona el conjunto de datos bqml y, a continuación, haz clic en Borrar conjunto de datos.
  3. En la ventana de superposición que aparece, ingresa bqml y, luego, haz clic en Borrar.

Borra el modelo de AI Platform

  1. En la consola de Google Cloud, ve a la página Modelos de AI Platform.

    Ir a Modelos de AI Platform

  2. En la lista de modelos, haz clic en rpm_bqml_model.

  3. En la página Detalles del modelo, selecciona la casilla de verificación para la versión V_1 (predeterminada).

  4. Haz clic en Más y, luego, en Borrar.

  5. Cuando se termine de borrar la versión, haz clic en Atrás para volver a la lista de modelos.

  6. Selecciona la casilla de verificación para el modelo rpm_bqml_model.

  7. Haz clic en Más y, luego, en Borrar.

  8. En Cloud Shell, borra la cuenta de servicio:

    gcloud iam service-accounts delete $SA

¿Qué sigue?