Esta é a documentação do Recommendations AI, da Pesquisa de varejo e do novo Console do Retail.

Antes de começar

Criar um projeto do Google Cloud

  1. Na página Gerenciar recursos no Console do Google Cloud, selecione ou crie um projeto do Google Cloud.

    Acessar a página "Gerenciar recursos"

  2. Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Configurar a API Retail

Para usar a API Retail, com a Recommendations AI, ative a API Retail e aceite os termos de uso de dados do Discovery Solutions. Se você também estiver usando a pesquisa de varejo, precisará ativá-la. O uso da pesquisa de varejo gera custos adicionais com base no número de consultas. Para mais informações, consulte Cobranças da pesquisa de varejo.

Para configurar a API Retail, siga estas etapas:

  1. Acesse a página Varejo no Console do Google Cloud.

    Acesse a página "Varejo"

  2. Na página Configurar API Retail, clique em Ativar API.

  3. Quando a API Retail e a Recommendations AI forem exibidas como Ativadas, clique em Continuar.

  4. Leia os Termos de Uso de dados do Discovery Solutions e clique em Aceitar se você concordar com eles.

    Ao aceitar os termos de uso de dados, o Console do Google Cloud indica que os termos de uso da API Retail são aceitos.

  5. Se você quiser usar o projeto somente com o Recommendations AI, clique em Primeiros passos.

  6. Se você quiser ativar a Pesquisa de varejo, além da Recommendations AI, faça o seguinte:

    1. Clique em Continuar e em Ativar na página Ativar a Pesquisa de varejo (opcional).
    2. Clique em Primeiros passos.

O Console do Google Cloud exibe os componentes da API Retail que você ativou. Agora, é possível definir as configurações iniciais do seu projeto.

Configurar a API Retail para um projeto atual

Se você configurou a API Retail em um projeto do Google Cloud antes que os termos de uso de dados entrem em vigor em 4 de abril de 2022, será preciso aceitar os termos do Discovery Solutions para continuar usando a API Retail com esse projeto. Você também precisa ativar a pesquisa de varejo para esse projeto, se necessário.

Para aceitar os termos de uso de dados das soluções do Discovery para um projeto atual, siga estas etapas:

  1. Acesse a página Varejo no Console do Google Cloud do seu projeto.

    Acesse a página "Varejo"

  2. Na página Termos de uso de dados, leia os termos de uso de dados do Discovery Solutions e clique em Aceitar se você concordar com eles.

  3. Se você quiser usar o projeto somente com o Recommendations AI, clique em Primeiros passos.

  4. Se você quiser ativar a Pesquisa de varejo, além da Recommendations AI, faça o seguinte:

    1. Clique em Continuar e em Ativar na página Ativar a Pesquisa de varejo (opcional).
    2. Clique em Primeiros passos.

Desativar a Pesquisa de varejo ou a API Retail

Desativar a Pesquisa de varejo

Caso não queira mais usar a Pesquisa de varejo, é possível desativá-la enviando um tíquete de suporte.

Para definir a passagem como o componente correto, selecione os seguintes campos:

  • Categoria: aprendizado de máquina
  • Componente: soluções de varejo: pesquisa de varejo
  • Subcomponente: administração de conta e faturamento

Para mais informações sobre como criar um tíquete de suporte, consulte Como receber suporte.

Desativar a API Retail

Você pode desativar a API Retail a qualquer momento desativando-a e o Recommendations AI. Essa ação também desativa a Pesquisa de varejo.

Para desativar a API Retail, siga estas etapas:

  1. Acesse a página Detalhes do serviço da API Retail no Console do Google Cloud.

    Acessar a página "Detalhes do serviço da API Retail"

  2. Clique em Desativar API.

  3. Na caixa Desativar API Retail?, clique em Desativar.

  4. Na caixa Desativar Recommendations AI?, clique em Desativar.

Primeiros passos com a API Retail

Quando você configura a API Retail para um novo projeto, o Console do Google Cloud exibe estes três painéis para ajudar você a configurar o projeto da API Retail:

  • Catálogo: exibe o catálogo de produtos e um link que importa o catálogo.

  • Evento: exibe os eventos do usuário e um link para importar eventos históricos do usuário.

  • Configurações de exibição: contém detalhes sobre sua configuração de exibição e um link para criar uma nova configuração de exibição.

Você pode usar esses painéis para importar seus dados e criar uma configuração inicial para o projeto da API Retail.

Importar seu catálogo de produtos

Para importar seu catálogo de produtos, conclua o conjunto de etapas da sua fonte de dados. Para mais informações sobre catálogos de produtos, consulte Como importar informações do catálogo.

Sincronização com o Merchant Center

  1. Clique em Importar catálogo de produtos para abrir o painel Importar dados.
  2. Escolha Catálogo de produtos.
  3. Selecione Merchant Center Sync como sua fonte de dados.
  4. Selecione sua conta do Merchant Center.
  5. Selecione a ramificação para fazer o upload do catálogo.
  6. Clique em Importar.

Cloud Storage

  1. Clique em Importar catálogo de produtos para abrir o painel Importar dados.
  2. Escolha Catálogo de produtos como sua fonte de dados.
  3. Selecione a ramificação para fazer o upload do catálogo.
  4. Escolha Esquema de catálogos de produtos de varejo como o esquema.
  5. Insira o local dos seus dados no Cloud Storage.
  6. Se a Pesquisa de varejo não estiver ativada, selecione os níveis dos produtos.

    Selecione os níveis se estiver importando seu catálogo pela primeira vez ou após limpar o catálogo. Saiba mais sobre níveis de produtos. Alterar níveis de produto depois de importar dados exige um esforço significativo.

    Importante: não é possível ativar a Pesquisa de varejo para projetos com um catálogo de produtos que foram ingeridos como variantes.
  7. Clique em Importar.

BigQuery

  1. Clique em Importar catálogo de produtos para abrir o painel Importar dados.
  2. Escolha Catálogo de produtos.
  3. Selecione BigQuery como fonte de dados.
  4. Selecione a ramificação para fazer o upload do catálogo.
  5. Escolha um dos seguintes esquemas:
  6. Insira a tabela do BigQuery em que seus dados estão localizados.
  7. (Opcional) Em Mostrar opções avançadas, insira o local de um bucket do Cloud Storage no projeto como um local temporário para seus dados.

    Se não for especificado, um local padrão será usado. Se especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.
  8. Se a Pesquisa de varejo não estiver ativada e você estiver usando o esquema do Merchant Center, selecione o nível do produto.

    Selecione o nível do produto se esta for a primeira vez que você importa o catálogo ou está importando o catálogo novamente depois de limpá-lo. Saiba mais sobre níveis de produtos. Alterar níveis de produto depois de importar dados exige um esforço significativo.

    Importante:não é possível ativar a Pesquisa de varejo para projetos com um catálogo de produtos que foram ingeridos como variantes.
  9. Clique em Importar.

Importar seus eventos históricos de usuário

Para importar seus eventos históricos de usuários, conclua o conjunto de etapas da sua fonte de dados. Para mais informações sobre eventos históricos do usuário, consulte Como importar eventos históricos do usuário.

Cloud Storage

  1. Clique em Importar eventos do usuário para abrir o painel Importar dados.
  2. Escolha Eventos do usuário.
  3. Selecione Google Cloud Storage como a fonte de dados.
  4. Escolha Esquema de eventos de usuários de varejo como o esquema.
  5. Insira o local dos seus dados no Cloud Storage.
  6. Clique em Importar.

BigQuery

  1. Clique em Importar eventos do usuário para abrir o painel Importar dados.
  2. Escolha Eventos do usuário.
  3. Selecione BigQuery como a fonte de dados.
  4. Escolha Esquema de eventos de usuários de varejo como o esquema.
  5. Insira a tabela do BigQuery em que seus dados estão localizados.
  6. (Opcional) Insira o local de um bucket do Cloud Storage no projeto como um local temporário para seus dados.
    Se não for especificado, um local padrão será usado. Se especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.
  7. (Opcional) Em Mostrar opções avançadas, insira o local de um bucket do Cloud Storage no projeto como um local temporário para seus dados.

    Se não for especificado, um local padrão será usado. Se especificado, os buckets do BigQuery e do Cloud Storage precisam estar na mesma região.
  8. Clique em Importar.

Criar uma configuração de exibição

Uma configuração de exibição é uma entidade de exibição que associa um modelo ou um conjunto de controles usados para gerar os resultados da pesquisa ou da recomendação.

Para criar uma configuração de exibição, siga estas etapas:

  1. No painel Configurações de exibição, clique em Criar configuração de exibição.
  2. Na página Criar configuração de exibição, escolha Pesquisa como o produto em que a configuração de exibição será usada.
  3. Forneça um nome para sua configuração de exibição.

    O nome precisa ter 1.024 caracteres ou menos e pode conter apenas caracteres alfanuméricos, sublinhados, hifens e espaços.
  4. Opcional: se necessário, atualize o ID.

    Ele é gerado com base no nome fornecido e precisa ser exclusivo no seu projeto. Ele pode ter até 50 caracteres e não pode conter espaços.
  5. Clique em Continuar.
  6. Escolha se você quer ativar o atributo dinâmico para esta configuração de exibição.
  7. Escolha ou crie controles de veiculação para otimizar as pesquisas.

    Para mais informações sobre controles, consulte Como criar e gerenciar controles.

Painel de varejo

Quando você concluir a configuração inicial do projeto, o Console do varejo exibirá o estado do sistema do projeto da API Retail. O Console do varejo permite gerenciar recursos do varejo e monitorar as atividades.

Acesse o Console do Google Cloud no varejo

Para mais informações sobre o console do varejo, consulte Console de administração do varejo.

Configurar a autenticação do seu aplicativo

Configure os dois métodos de autenticação a seguir para acessar a API Retail:

  • Conta de serviço: os aplicativos usam uma conta de serviço para autenticar chamadas para o Product.

  • Chave de API: os aplicativos usam uma chave de API para chamadas às APIs de registro de eventos do usuário.

Criar uma conta de serviço

  1. Acesse a página Credenciais do Console do Google Cloud.

  2. Selecione o projeto para o qual você está criando credenciais (o projeto pode já estar selecionado).

  3. Clique em Criar credenciais. Em seguida, selecione Chave da conta de serviço.

  4. Preencha os campos a seguir:

    Campo Valor
    Conta de serviço Nova conta de serviço
    Nome da conta de serviço enter a name for your service account
    Papel Contas de serviço > Criador de token da conta de serviço
    Varejo > Editor de varejo
    Tipo de chave JSON
  5. Clique em Criar para criar a conta de serviço.

    O arquivo JSON que contém a chave pública/privada para a nova conta de serviço é salvo automaticamente no seu computador. Esse arquivo JSON é a única cópia da chave da sua conta de serviço. Armazene-o em um local seguro. O arquivo de chave JSON precisa ser armazenado em um local acessível para o aplicativo. Consulte your-service-account-json-key-file em Autenticar usando uma conta de serviço (OAuth 2.0).

Adicionar a conta de serviço ao ambiente local

Se você quiser fazer chamadas para a API Retail usando a ferramenta de linha de comando cURL, precisará disponibilizar a conta de serviço no ambiente local. cURL usa o comando gcloud auth application-default print-access-token para receber um token de acesso para sua conta de serviço usando a CLI do Google Cloud. Para fazer o download e instalar a CLI gcloud, consulte CLI da gcloud. Se você estiver usando o Cloud Shell, a CLI gcloud já está instalada.

A variável de ambiente GOOGLE_APPLICATION_CREDENTIALS não será mantida se você fechar a janela de comando. Para verificar se a variável está definida como o caminho para o arquivo da conta de serviço ao abrir uma nova janela de comando, defina o valor em um script de shell de inicialização.

  export GOOGLE_APPLICATION_CREDENTIALS=path-to-service-account-json-key-file

Criar uma chave de API

  1. Acesse a página Credenciais do Console do Google Cloud.

  2. Na lista suspensa do projeto, na parte superior da página do Console do Google Cloud, selecione seu projeto. O projeto já pode estar selecionado.

  3. Clique em Criar credenciais e, em seguida, selecione Chave de API. Não adicione restrições de referenciador. Algumas configurações de privacidade do usuário costumam não passar o URL referenciador.

    • Anote a chave de API gerada, que será usada ao chamar a API de registro de eventos do usuário.
  4. Para reforçar a segurança, adicione uma restrição HTTP à sua chave de API para restringir o acesso ao serviço de varejo em https://retail.googleapis.com/*.

Examples

Autenticar usando uma conta de serviço (OAuth 2.0)

Veja um exemplo de Java da autenticação do OAuth 2.0 usando uma conta de serviço. Instruções mais detalhadas são encontradas na documentação de autenticação. O Google tem bibliotecas de cliente em sete idiomas que podem ser usadas para implementar a autenticação do OAuth2 no seu aplicativo. Se preferir implementar o HTTP/REST diretamente, siga as instruções de autenticação REST.

No exemplo, substitua your-service-account-json-key-file pelo caminho para o arquivo de chave JSON da sua conta de serviço.

// Simple Java example of using Google Cloud OAuth client library.
//
// Please see here for the list of libraries in different languages:
// https://developers.google.com/identity/protocols/OAuth2#libraries
//
// The following example depends on the google api client library.
//
// Maven:
//    <dependency>
//      <groupId>com.google.api-client</groupId>
//      <artifactId>google-api-client</artifactId>
//      <version>1.22.0</version>
//    </dependency>
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.GenericJson;
import com.google.api.client.json.jackson2.JacksonFactory;
import java.io.FileInputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class RetailApiSample {
  public static final String CREATE_PRODUCT_URL =
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products";

  public static GoogleCredential authorize() throws Exception {
    return GoogleCredential.fromStream(new FileInputStream("your-service-account-json-key-file"))
        .createScoped(Collections.singleton("https://www.googleapis.com/auth/cloud-platform"))
        .setExpirationTimeMilliseconds(new Long(3600 * 1000));;
  }

  // Build an example product.
  public static GenericJson getProduct() {
    GenericJson categories = new GenericJson()
        .set("categories", Arrays.asList("Electronics > Computers", "Laptops"));
    GenericJson priceInfo = new GenericJson()
        .set("currency_code", "USD")
        .set("price", 800.00)
        .set("original_price", 1000.00);

    return new GenericJson()
        .set("name", "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/[ProductName]")
        .set("title", "Sample Laptop")
        .set("description", "Indisputably the most fantastic laptop ever created.")
        .set("categories", categories)
        .set("price_info", priceInfo)
        .set("availability", "IN_STOCK")
        .set("available_quantity", 1219);
  }

  public static void main(String[] args) {
    try {
      GoogleCredential credential = RetailApiSample.authorize();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      HttpRequestFactory requestFactory = httpTransport.createRequestFactory();
      HttpRequest request = requestFactory.buildPostRequest(new GenericUrl(CREATE_PRODUCT_URL),
          new JsonHttpContent(new JacksonFactory(), RetailApiSample.getProduct()));
      credential.initialize(request);
      HttpResponse response = request.execute();
      System.out.println("Response content: " + response.parseAsString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

A seguir