Crie uma API inteligente para prever a propensão do cliente comprar usando a Apigee, o BigQuery ML e o Cloud Spanner

Last reviewed 2022-06-29 UTC

Neste tutorial, mostramos como criar uma API para prever a probabilidade de um cliente fazer uma compra. Para criar a API, use a Apigee, o BigQuery ML e o Cloud Spanner.

Este tutorial é destinado a desenvolvedores de API e especialistas em dados que querem gerar mais receita com as plataformas Omni-Channel e e-commerce, fornecendo uma experiência mais personalizada para os usuários. Ele pressupõe que você esteja familiarizado com o BigQuery, a Apigee, a CLI do Google Cloud e o Apache Maven.

A API que você cria usa previsões on-line para realizar ações em tempo real com base no comportamento do usuário no seu site. As previsões on-line combinam insights de machine learning (ML) com um catálogo de produtos e outras informações, o que ajuda a criar uma experiência melhor para os clientes em vários canais. A arquitetura da API criada é mostrada no diagrama a seguir:

Arquitetura de uma API para prever a propensão do cliente à compra.

O diagrama mostra a seguinte arquitetura:

  1. Um aplicativo para dispositivos móveis envia uma solicitação para a API implantada na plataforma da Apigee. A solicitação busca os dados de recomendações de produtos para o usuário que fez login.
  2. Um proxy de API recebe os dados de recomendações do produto para o ID do usuário de um conjunto de dados do BigQuery.
  3. O proxy de API faz uma chamada para buscar os dados do banco de dados principal do produto em uma instância do Cloud Spanner.
  4. O proxy de API agrega os dados das recomendações de produtos e dos conjuntos de dados principais do produto.
  5. Uma resposta é retornada ao aplicativo para dispositivos móveis.

Objetivos

  • Crie um conjunto de dados de propensão de compra do cliente no BigQuery.
  • Importar dados do catálogo de produtos para o banco de dados do Cloud Spanner.
  • Importe e implante o proxy de API da Apigee.
  • Integre dados de propensão de compra do cliente do BigQuery às informações de preço e do catálogo de produtos no banco de dados do Cloud Spanner.
  • Crie uma visualização agregada de recomendações de produtos.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

  • Slots flexíveis do BigQuery e do BigQuery M.
  • Cloud Spanner
  • Apigee

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Antes de começar

  1. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  2. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

  3. Ative as APIs 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.

    Ative as APIs

  4. No Console do Google Cloud, ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do Console do Google Cloud, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  5. Atribua os papéis à sua Conta do Google. Execute uma vez o seguinte comando para cada um dos seguintes papéis do IAM:

    • 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
    • Substitua PROJECT_ID pela ID do seu projeto.
    • Substitua EMAIL_ADDRESS pelo seu endereço de e-mail.
    • Substitua ROLE por cada papel individual.
  6. Se você ainda não tiver uma conta do Apigee X, configure-a para provisionar uma instância do Apigee X. O provisionamento pode levar até uma hora.
  7. Configure sua organização do Apigee X para permitir acesso externo.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Criar um conjunto de dados de recomendação de comércio eletrônico usando o BigQuery ML

Nesta seção, você usará consultas SQL padrão no BigQuery ML para criar um modelo de ML, treiná-lo nos dados do cliente no BigQuery e implantá-lo. Você não precisa exportar seus dados ou criar um pipeline de treinamento e implantação de modelo. O BigQuery faz o escalonamento automático para processar todos os recursos de computação necessários.

O modelo de ML que você criar neste tutorial usa a fatoração de matriz, um método comum e eficaz para criar um sistema de recomendação com base em dados de preferência do usuário.

Neste tutorial, você usará o conjunto de dados de amostra do Google Analytics, que está hospedado publicamente no BigQuery. Esse conjunto de dados fornece 12 meses (agosto de 2016 a agosto de 2017) de dados ofuscados do Google Analytics 360 da Google Merchandise Store, uma loja de comércio eletrônico real que vende mercadorias com a marca do Google.

Processar os dados de amostra

Ao usar a fatoração de matriz, você avalia o feedback explícito ou implícito do usuário para determinar as preferências do cliente. Para usar o feedback explícito, é necessário que o conjunto de dados contenha dados sobre as preferências de produto dos usuários, como avaliações com estrelas entre 1 e 5. Nos casos em que não houver feedback explícito disponível, use outras métricas comportamentais para inferir as preferências dos clientes, como analisar o tempo total que um usuário gasta em uma página de detalhes de um produto. Neste tutorial, você usará os dados de duração da sessão para deduzir as preferências do cliente.

Para treinar o modelo de fatoração de matrizes, você precisa de uma tabela com colunas que identifiquem o cliente, o item que está sendo avaliado e a classificação implícita. Nesta seção, você cria uma tabela com as colunas userid, itemId e session_duration. A coluna session_duration contém a duração da sessão do usuário na página do produto de um determinado item.

Para criar a tabela usando dados do conjunto de dados de amostra do Google Analytics, faça o seguinte:

  1. No Google Cloud Marketplace, acesse a página Amostra do Analytics.

    Acessar o exemplo do Google Analytics

  2. Clique em Ver conjunto de dados. A página do espaço de trabalho SQL do BigQuery é aberta com o conjunto de dados de amostra do Google Analytics selecionado.

  3. Na seção Explorer, ao lado do seu projeto, clique em Ver ações e, em seguida, clique em Criar conjunto de dados.

  4. Na caixa de diálogo Criar conjunto de dados exibida, faça o seguinte:

    1. No campo ID do conjunto de dados, digite bqml.
    2. Na lista Local de dados, selecione us (várias regiões nos Estados Unidos).
    3. Clique em Criar conjunto de dados.

  5. Clique em Ir para o conjunto de dados e em Escrever nova consulta.

  6. No Editor de consultas, crie uma tabela que contenha os dados de treinamento executando a seguinte instrução 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
);

    A tabela bqml.aggregate_web_stats é criada e preenchida com dados de treinamento.

  7. Para ver uma amostra dos dados, execute a seguinte instrução SQL no Editor de consultas:

    SELECT
*
FROM
  bqml.aggregate_web_stats
LIMIT
  10;

O resultado mostra uma tabela com uma linha para cada ID do usuário, incluindo o ID do item visualizado pelo usuário e a duração da sessão. A resposta será parecida com esta:

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

Comprar slots flexíveis

Se for usar o preço sob demanda para o BigQuery, para treinar um modelo de fatoração de matrizes, você precisa comprar slots flexíveis e, em seguida, criar reservas e atribuições para eles. Se você usa preços fixos com o BigQuery, pule esta seção e acesse Criar, treinar e implantar o modelo.

Para comprar slots flexíveis, você precisa ter um papel do IAM que inclua a permissão bigquery.reservations.create. Essa permissão é concedida ao proprietário do projeto e está incluída nos papéis do IAM de administrador do BigQuery (roles/bigquery.admin) e administrador de recursos do BigQuery (roles/bigquery.resourceAdmin).

  1. No console do Google Cloud, acesse a página do BigQuery:

    Ir para o BigQuery

  2. Clique em Gerenciamento de capacidade e Reservas.

  3. Se você for redirecionado para a página API BigQuery Reservation para ativar a API, clique em Ativar. Do contrário, avance para a próxima etapa.

  4. Na guia Reservas, clique em Comprar slots.

  5. Na página Comprar slots, siga estas etapas:

    1. Na lista Duração do compromisso, selecione Flexível.
    2. Na lista Local, selecione us (várias regiões nos Estados Unidos).
    3. Na lista Número de slots, selecione 500.
    4. Clique em Próxima.

    5. No campo Confirmação de compra, digite CONFIRM e clique em Comprar.

  6. Clique em Ver compromissos de slot.

    Aguarde até 20 minutos para que a capacidade seja provisionada. Depois que a capacidade for provisionada, a coluna Status do compromisso de slot mostrará .

  7. Clique em Criar reserva e defina as seguintes opções:

    1. Em Nome da reserva, insira model.
    2. Na lista Local, selecione us (várias regiões nos Estados Unidos).
    3. Em Número de slots, insira 500.
    4. Clique em Save. Isso leva você de volta à página Reservas.

  8. Ao lado da reserva model, na coluna Ações, selecione Criar atribuição.

  9. Em Selecionar organização, pasta ou projeto, clique em Procurar.

  10. Digite o nome do projeto em que você está concluindo este tutorial ou selecione-o na lista.

  11. Clique em Select, e depois em Create.

Criar, treinar e implantar o modelo

Para criar, treinar e implantar o modelo de fatoração de matrizes, faça o seguinte:

  1. Na página do BigQuery do Console do Google Cloud, clique em Escrever nova consulta.

  2. Execute a instrução 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;

Após a conclusão do treinamento, o modelo treinado é implantado como o modelo bqml.retail_recommender.

Usar o modelo treinado para fazer predições

Nesta seção, para receber previsões do modelo bqml.retail_recommender implantado, use a função SQL ML.RECOMMEND.

  1. Na página do BigQuery do Console do Google Cloud, escreva uma consulta e receba previsões que representem as cinco principais recomendações para um 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;

    A saída exibe uma linha para a confiança da duração da sessão prevista (mais alta é melhor), o ID do usuário associado e o ID do item que o usuário visualizou. O resultado será assim:

    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 receber as cinco principais previsões para todos os usuários, execute a seguinte instrução SQL. A instrução gera muitas linhas, então a saída é gravada em uma tabela, e os primeiros 10 registros são recuperados para que você possa ver um exemplo dos dados.

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

    A saída mostra vários IDs de usuário, o ID do item que o usuário visualizou e a confiança na duração da sessão prevista. O resultado será assim:

    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

Configurar dados do Cloud Spanner

Nas seções a seguir, você usará a CLI da gcloud e o Maven. Você executa comandos para as duas ferramentas no Cloud Shell. Nenhuma ferramenta é necessária para usar as ferramentas.

  1. No Cloud Shell, clone o repositório GitHut de recomendações de produtos que contém o pacote de proxy e os scripts da API de recomendações de produtos para configurar os dados em um banco de dados do Cloud Spanner:

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

  2. Crie a conta de serviço datareader e atribua papéis do IAM a ela. A conta de serviço é usada para acessar os dados no BigQuery e no banco de dados do Cloud Spanner pelo proxy da 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. Defina as variáveis de ambiente:

    # 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

    Substitua:

    • APIGEEX_PROJECT: o nome do projeto da Apigee X.
    • API_DOMAIN_NAME: o nome do host configurado na página "Administradores" > > Grupos na IU da Apigee X.

  4. Na página do BigQuery do Console do Google Cloud, selecione a tabela prod_recommendations e clique na guia Visualizar para ver os resultados.

    1. Copie qualquer valor userId.

    2. No Cloud Shell, defina uma variável de ambiente:

      export CUSTOMER_USERID=USER_ID

      Substitua USER_ID pelo valor userId que você copiou na etapa anterior.

  5. No Cloud Shell, exiba os resultados da recomendação de produto ordenados para o valor 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

    A saída mostra um ID do usuário individual, o ID do item que o usuário visualizou e a confiança na duração da sessão prevista. O resultado será assim:

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

Criar um banco de dados do Cloud Spanner e importar dados do catálogo de produtos

  1. No Cloud Shell, crie uma instância do Cloud Spanner na região especificada, crie o banco de dados do catálogo de produtos e importe os dados:

    ./setup_spanner.sh

    O script usa a variável de ambiente CUSTOMER_USERID e exibe as entradas que foram criadas.

    O catálogo de produtos do Cloud Spanner contém apenas os itens que foram usados na etapa de treinamento do BigQuery para um usuário específico. Portanto, se você alterar a variável de ambiente CUSTOMER_USERID depois de criar os dados do catálogo de produtos no banco de dados do Cloud Spanner, execute novamente o script de shell setup_spanner.sh para preencher novamente os dados.

  2. Verifique os dados no banco de dados do Cloud Spanner:

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

    A saída mostra os IDs dos produtos e as informações descritivas do catálogo de produtos do Spanner, incluindo o preço e o caminho da imagem. A resposta será semelhante a:

    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

Implantar proxy da Apigee

Nesta seção, você executará um comando do Maven para criar os seguintes recursos:

  • Um proxy chamado product-recommendations-v1
  • Um produto de API chamado product-recommendations-v1-$ENV
  • Um usuário desenvolvedor de apps chamado demo@any.com
  • Um app chamado product-recommendations-v1-app-$ENV

Para criar os recursos, o Maven usa o arquivo pom.xml do repositório do GitHub. O arquivo contém as instruções e etapas de instalação.

A seção de perfil do arquivo pom.xml contém valores para apigee.org, apigee.env, api.northbound.domain, gcp.projectid, googletoken.email e api.userid. Esses valores variam de acordo com o projeto e são definidos com a linha de comando. O exemplo a seguir mostra a seção do arquivo pom.xml que contém os 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>

Você define esses valores mais cedo ao configurar os dados do Cloud Spanner.

Para implantar o proxy, faça o seguinte:

  • No Cloud Shell, instale o proxy e os respectivos artefatos associados. Em seguida, teste a 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

    A saída mostra a execução das etapas de instalação e os resultados das chamadas de API de teste de integração. Há uma chamada para o endpoint /openapi e outra para o endpoint /products. Os resultados do teste verificam se o proxy de API foi instalado, implantado e está em operação. A saída também exibe as credenciais do app, que podem ser usadas para chamadas de teste de API subsequentes.

Testar as recomendações de API

  1. No Cloud Shell, defina uma variável de ambiente para a chave de API do aplicativo fazendo uma chamada curl para a API Apigee:

    APIKEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://apigee.googleapis.com/v1/organizations/$ORG/developers/demo@any.com/apps/product-recommendations-v1-app-$ENV \
    | jq -r .credentials[0].consumerKey)

    Anote o valor APIKEY. Você precisará dessas informações se criar um app do AppSheet opcionalmente.

  2. Para ver os resultados do valor CUSTOMER_USERID especificado ao instalar o proxy de API, faça uma chamada de teste:

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

A API definida pela OpenAPI Specification (OAS) permite que a solicitação especifique os seguintes cabeçalhos:

  • x-apikey: a chave do cliente do app que está no esquema de segurança.
  • x-userid: o identificador do usuário que faz a solicitação. Se não for fornecido, o valor padrão será o CUSTOMER_USERID configurado no proxy.
  • cache-control: o tempo total de armazenamento em cache da resposta. Esse cabeçalho permite armazenar em cache a resposta por 300 segundos ou substituir especificando no-cache.

Para alterar o valor de CUSTOMER_USERID ou controlar o armazenamento em cache, defina os valores de cabeçalho conforme mostrado no exemplo de chamada a seguir:

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

A resposta à chamada de exemplo é semelhante a esta:

{
  "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 da Apigee

As políticas da Apigee listadas nas seções a seguir são usadas no pacote de proxy de API neste tutorial.

Pré-fluxo

SpikeArrest
Proteja o serviço BigQuery de back-end contra picos de tráfego.
Cota
Limitar as solicitações de API com base no aplicativo e no desenvolvedor do consumidor. Os limites de limitação são configurados no produto da API.
ResponseCache - uri
Reduza as solicitações para o data warehouse do BiqQuery armazenando em cache a resposta do serviço.

Products-flow

AssignMessage: criar solicitação de consulta
Defina a solicitação HTTP com uma consulta SQL para buscar a lista de recomendações de produtos no conjunto de dados do BigQuery.
Políticas JavaScript e ExtractVariable
Formatar os dados do serviço do BigQuery e criar uma mensagem de resposta fácil de usar.
LookupCache - sessão do Cloud Spanner
Pesquisar o ID da sessão do banco de dados do Cloud Spanner no cache da Apigee.
ServiceCallout: sessão do Cloud Spanner
Faça uma solicitação para o serviço do Cloud Spanner e crie uma sessão de banco de dados se o cache da Apigee não tiver um ID de sessão ou o ID tiver expirado.
PopulateCache - sessão do Cloud Spanner
Preencha o ID da sessão do Cloud Spanner para o cache da Apigee.
ServiceCallout: pesquisa do catálogo de produtos
Buscar os detalhes do produto no banco de dados do catálogo de produtos do Cloud Spanner.
JavaScript: formatar dados do produto
Crie uma mensagem de resposta da API em conformidade com o OAS formatando os dados do banco de dados do catálogo de produtos.

OpenAPI-flow

AssignMessage: JSON OAS
Defina a resposta JSON do OAS para a API.

Opcional: criar um app do AppSheet usando a Apigee como fonte de dados

Para mostrar recomendações de produtos aos usuários finais do site de comércio eletrônico e aos usuários comerciais, crie um app AppSheet, conforme mostrado nesta seção.

Criar uma conta do AppSheet

Crie uma conta do AppSheet usando o endereço de e-mail.

Criar uma fonte de dados

O AppSheet usa o proxy de API como a fonte de dados do seu novo app. Para criar uma fonte de dados, faça o seguinte:

  1. Faça login no AppSheet.
  2. Na página Minha conta, clique em Fontes > Nova fonte de dados.
  3. Na caixa de diálogo Add a new data source, insira o nome do proxy product-recommendations-v1 e clique em Apigee.

  4. Na caixa de diálogo Adicionar informações de conexão da API Apigee, defina as seguintes opções:

    1. Selecione Manual.
    2. No campo Chave de API da Apigee, insira a chave de API do app que você usou para testar o proxy. Se você não tiver a chave de API, consiga-a no Cloud Shell executando echo $APIKEY.

    3. No campo Caminho base da API Apigee, digite o seguinte:

      https://ENVGROUP_HOSTNAME/v1/recommendations

      Substitua ENVGROUP_HOSTNAME pelo nome do host configurado na IU da Apigee X para administradores > Ambientes > Grupos.

    4. No campo Caminhos de recursos da API, insira o sufixo products.

    5. Clique em Test.

    6. Após a conclusão dos testes, clique em Autorizar acesso.

Depois que você autoriza o acesso, o Console do AppSheet mostra um novo bloco para product-recommendations-v1.

Criar o app

  1. Acesse a página app-template-template do AppSheet.
  2. Clique em Copy and Customize. A caixa de diálogo Clone your app será exibida.
  3. No campo Nome do aplicativo, digite o nome do proxy, product-recommendations-v1, e clique em Copiar aplicativo. Aguarde alguns momentos para a criação do app.
  4. Na página Este é seu app, clique em Personalizar app. Por padrão, o app usa uma fonte de dados de amostra em um arquivo do Planilhas Google.

  5. Altere a fonte de dados para que corresponda à fonte de dados da Apigee que você criou anteriormente:

    1. Clique em + Nova tabela e em recomendações de produtos v1.
    2. Na caixa de diálogo Escolher uma Planilha/Tabela, selecione produtos.
    3. Na caixa de diálogo Create a new table, clique em Read-Only e em Add This Table.

    O app é exibido com uma guia products 2 e uma visualização de dados diferentes. A nova visualização de dados tem valores diferentes para a descrição e o preço de cada item. Observe que a ordem dos itens não é igual à ordem das previsões.

  6. Altere a ordem em que os itens são retornados da fonte de dados removendo a classificação padrão do AppSheet:

    1. No menu de navegação lateral, selecione UX.
    2. Na seção Visualizações principais, selecione products 2.
    3. Na seção Opções de visualização, ao lado de Classificar por, exclua a entrada nome, Ascendente. Observe que a ordem exibida no AppSheet agora é igual ao resultado da chamada de API, com o último item da resposta na parte inferior.

  7. Salve o app.

Como alternativa, exclua a tabela original do produto e a UX, renomeie a tabela "products 2" e exiba-a como "Product Recommendations".

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Exclua o projeto

  1. No Console do Google Cloud, acesse a página Gerenciar recursos.

    Acessar "Gerenciar recursos"

  2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
  3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Excluir recursos individuais

Para evitar custos recorrentes, exclua as reservas de slot flexível do BigQuery, o conjunto de dados do BigQuery e o modelo do AI Platform.

Excluir as reservas do slot flexível do BigQuery

  1. Na página do BigQuery do Console do Google Cloud, selecione Gerenciamento de capacidade e clique na guia Reservas.
  2. Abra a entrada do modelo.
  3. Ao lado de reserva, clique em Visualizar ações e, em seguida, clique em Excluir.
  4. Ao lado da entrada model, clique em View actions e, em seguida, clique em Delete.

  5. No Cloud Shell, exclua a implantação, o proxy e os artefatos associados:

    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. Remova os recursos do Spanner:

    ./cleanup_spanner.sh

Excluir o conjunto de dados do BigQuery

  1. Na seção Recursos do BigQuery do Console do Google Cloud, expanda o projeto em que você concluiu este tutorial.
  2. Selecione o conjunto de dados bqml e clique em Excluir conjunto de dados.
  3. Na janela de sobreposição que aparece, digite bqml e clique em Excluir.

Excluir o modelo do AI Platform

  1. No Console do Google Cloud, acesse a página Modelos do AI Platform.

    Acesse os modelos da AI Platform

  2. Na lista de modelos, clique em rpm_bqml_model.

  3. Na página Detalhes do modelo, marque a caixa de seleção da versão V_1 (padrão).

  4. Clique em Mais e em Excluir.

  5. Quando a exclusão da versão for concluída, clique em Voltar para retornar à lista de modelos.

  6. Marque a caixa de seleção do modelo rpm_bqml_model.

  7. Clique em Mais e em Excluir.

  8. No Cloud Shell, exclua a conta de serviço :

    gcloud iam service-accounts delete $SA

A seguir