Antes de começar

Criar um projeto do Google Cloud

  1. Na página Gerenciar recursos do 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 Vertex AI para Pesquisa para varejo

Se você quiser usar a Vertex AI para Pesquisa para varejo, além de recomendações, ative a Vertex AI para Pesquisa para varejo e aceite os termos da Vertex AI para Pesquisa para o setor para uso de dados. Se você também estiver usando a pesquisa, será necessário ativá-la. O uso da pesquisa gera custos adicionais com base no número de consultas. Para mais informações, consulte Cobranças de pesquisa.

Para configurar a Vertex AI para Pesquisa para varejo, siga estas etapas:

  1. Acesse a página da Vertex AI para Pesquisa para varejo no console do Google Cloud.

    Acessar a página "Pesquisa para varejo"

  2. Na página Configurar a Vertex AI para Pesquisa para varejo, clique em Ativar API.

  3. Quando as opções Vertex AI para Pesquisa para varejo e Recommendations AI aparecem como Ativadas, clique em Continuar.

  4. Leia os Termos de uso de dados da Vertex AI para Pesquisa para o setor 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 Vertex AI para Pesquisa para varejo são aceitos.

  5. Se você quiser usar o projeto apenas com recomendações, clique em Primeiros passos.

  6. Se você quiser ativar a pesquisa além das recomendações, faça o seguinte:

    1. Clique em Continuar e em Ativar na página Ativar pesquisa (opcional).
    2. Clique em Começar.

O console do Google Cloud mostra os componentes da Vertex AI para Pesquisa para varejo que você ativou. Agora é possível definir as configurações iniciais do seu projeto.

Configurar para um projeto atual

Se você configurou a Vertex AI para Pesquisa para varejo em um projeto do Google Cloud antes de os termos de uso de dados entrarem em vigor em 4 de abril de 2022, será necessário aceitar os termos da Vertex AI para Pesquisa para o setor se quiser continuar usando a Vertex AI para Pesquisa para varejo com esse projeto. Você também precisa ativar a pesquisa para esse projeto, se necessário.

Para aceitar os termos da Vertex AI para Pesquisa para o setor em um projeto atual, siga estas etapas:

  1. Acesse a página Pesquisa de varejo do seu projeto no console do Google Cloud.

    Acessar a página "Pesquisa para varejo"

  2. Na página Termos de uso de dados, leia os termos de uso de dados das soluções de descoberta e clique em Aceitar caso concorde com eles.

  3. Se você quiser usar o projeto apenas com recomendações, clique em Primeiros passos.

  4. Se você quiser ativar a pesquisa além das recomendações, faça o seguinte:

    1. Clique em Continuar e em Ativar na página Ativar pesquisa (opcional).
    2. Clique em Começar.

Desativar a pesquisa ou a Vertex AI para Pesquisa para varejo

Desativar a pesquisa

Se você não quiser mais usar a pesquisa, envie um tíquete de suporte para desativá-la.

Para definir o tíquete no componente correto, selecione os seguintes campos:

  • Categoria: machine learning
  • Componente: Vertex AI para Pesquisa para varejo: pesquisa e navegação
  • Subcomponente: administração e faturamento da conta

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

Desativar a Vertex AI para Pesquisa para varejo

É possível desativar a Vertex AI para Pesquisa para o varejo a qualquer momento. Essa ação desativa as recomendações e a pesquisa.

Para desativar a Vertex AI para Pesquisa para varejo, siga estas etapas:

  1. Acesse a página API Vertex AI Search for Retail/Detalhes do serviço no console do Google Cloud.

    Acessar a página de detalhes do serviço da API Vertex AI Search for Retail

  2. Clique em Desativar API.

  3. Na caixa Desativar a API Vertex AI para Pesquisa para varejo?, clique em Desativar.

Introdução à Vertex AI para Pesquisa no varejo

Quando você configura a Vertex AI para Pesquisa no varejo para um novo projeto, o console do Google Cloud exibe os três painéis a seguir para ajudar você a configurar seu projeto da Vertex AI para Pesquisa para varejo:

  • Dados > Catálogo: exibe seu catálogo de produtos e um link para importá-lo.

  • Dados > Eventos: exibe seus eventos de usuário e um link para importar os eventos históricos do usuário.

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

É possível usar esses painéis para importar dados e criar uma configuração inicial para seu projeto da Vertex AI para Pesquisa para varejo.

Importar seu catálogo de produtos

Para importar o 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 de 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. Marque a opção Acesso do usuário se você não encontrar sua conta.
  5. Opcional: selecione Filtro de feeds do Merchant Center para importar somente ofertas dos feeds selecionados.

    Se não for especificado, as ofertas de todos os feeds serão importadas (incluindo os futuros).
  6. Opcional: para importar somente ofertas segmentadas a determinados países ou idiomas, abra Mostrar opções avançadas e selecione os países de venda e os idiomas do Merchant Center que serão filtrados.
  7. Selecione a ramificação para fazer o upload do catálogo.
  8. Clique em Importar.

Cloud Storage

  1. Clique em Importar catálogo de produtos para abrir o painel Importar dados.
  2. Escolha o 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 esquema.
  5. Insira o local dos seus dados no Cloud Storage.
  6. Se a pesquisa não estiver ativada, selecione os níveis dos produtos.

    É necessário selecionar os níveis do produto se esta for a primeira vez que você estiver importando seu catálogo ou se estiver importando o catálogo novamente depois de limpá-lo. Saiba mais sobre os níveis de produtos. Mudar os níveis de produtos após a importação de dados requer um esforço significativo.

    Importante:não é possível ativar a pesquisa de projetos com um catálogo de produtos que foi ingerido 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 seu projeto como um local temporário para seus dados.

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

    É necessário selecionar o nível do produto se esta for a primeira vez que você importa seu catálogo ou se estiver importando o catálogo novamente depois de limpá-lo. Saiba mais sobre os níveis de produtos. Mudar os níveis de produtos após a importação de dados requer um esforço significativo.

    Importante:não é possível ativar a pesquisa de projetos com um catálogo de produtos que foi ingerido como variantes.
  9. Clique em Importar.

Importar os eventos históricos do usuário

Para importar o histórico de eventos do usuário, conclua o conjunto de etapas da sua fonte de dados. Para mais informações sobre os 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 o Google Cloud Storage como a origem de dados.
  4. Escolha Esquema de eventos de usuários de varejo como 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. Selecione o esquema de dados.

  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 seu projeto como um local temporário para seus dados.
    Se não for especificado, será usado um local padrão. Se especificado, o bucket do BigQuery e do Cloud Storage precisa estar na mesma região.
  7. Opcional: em Mostrar opções avançadas, insira o local de um bucket do Cloud Storage no seu projeto como um local temporário para seus dados.

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

Criar uma configuração de veiculação

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

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

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

    Ele precisa ter no máximo 1.024 caracteres 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 em todo o projeto. Ele precisa ter até 50 caracteres e não pode conter espaços.
  5. Clique em Continuar.
  6. Escolha se você quer ativar os atributos dinâmicos para essa configuração de exibição.
  7. Escolha ou crie controles de veiculação para otimizar suas pesquisas.

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

O painel

Quando você concluir a configuração inicial do projeto, o console do Search for Retail vai mostrar o estado do sistema do projeto da Vertex AI para Pesquisa para varejo. O console permite gerenciar recursos e monitorar atividades.

Acessar o console da Pesquisa para varejo

Configurar a autenticação para o app

Você precisa configurar a autenticação para que apps, como seu site de e-commerce, possam acessar a Vertex AI para Pesquisa para varejo:

  • Conta de serviço. Os apps usam uma conta de serviço para autenticar chamadas para Product. Para configurar uma conta de serviço, consulte Criar uma conta de serviço abaixo.

  • Chave de API. Os apps usam uma chave de API em chamadas para o método userEvents.Collect. Você só vai precisar configurar esse método de autenticação se quiser capturar eventos de usuários dos navegadores deles usando um pixel JavaScript ou o Gerenciador de tags do Google. Para configurar uma chave de API, consulte Criar uma chave de API abaixo.

Crie uma conta de serviço

  1. Acesse a página Credenciais no console do Google Cloud.

  2. Selecione o projeto em que você está criando uma conta de serviço (o projeto pode já estar selecionado).

  3. Clique em Criar credenciais e selecione Conta de serviço.

    A página Criar conta de serviço é aberta.

  4. Em Detalhes da conta de serviço, preencha os seguintes campos:

    • Nome da conta de serviço: um nome de exibição para a conta de serviço.
    • ID da conta de serviço: um nome exclusivo para a conta de serviço. É possível usar o ID padrão fornecido ou substituí-lo por um ID personalizado.
    • Descrição da conta de serviço: opcional. Uma descrição da conta.

  5. Clique em Criar e continuar para criar a conta de serviço e conceda a ela acesso ao seu projeto.

  6. Em Conceda a essa conta de serviço acesso ao projeto, adicione os seguintes papéis:

    • Contas de serviço > Criador de token de conta de serviço
    • Outro > Editor de varejo

  7. Opcional: para conceder acesso à conta de serviço a usuários ou grupos que precisam executar ações como essa conta de serviço, clique em Continuar e insira as informações da conta do usuário ou grupo.

  8. Clique em Concluído para salvar as alterações.

Adicionar a conta de serviço ao ambiente local

Se você quiser fazer chamadas para a Vertex AI para Pesquisa no varejo usando a ferramenta de linha de comando cURL, será necessário disponibilizar sua conta de serviço no ambiente local.

Para receber um arquivo JSON da chave da conta de serviço, siga as instruções em Criar e gerenciar contas de serviço.

O arquivo JSON contém a chave pública/privada da sua conta de serviço. Esse arquivo JSON é a única cópia da chave da conta de serviço. Guarde-o em um local seguro.

O arquivo de chave JSON precisa ser armazenado em um local acessível pelo app.

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 Google Cloud CLI. Para fazer o download e instalar a CLI gcloud, consulte CLI gcloud. Se você estiver usando o Cloud Shell, a CLI gcloud já estará 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

crie uma chave de API

Uma chave de API é necessária se você usa um pixel JavaScript ou uma tag do Gerenciador de tags para capturar eventos de usuários nos navegadores deles. Para saber mais sobre como capturar eventos do usuário, consulte Gravar eventos do usuário em tempo real.

Se quiser criar uma chave de API para chamadas do método userEvents.Collect, siga estas etapas:

  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 pode já estar selecionado).

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

    • Anote a chave de API gerada, que é usada ao chamar o registro de eventos do usuário.

  4. Para reforçar a segurança, adicione uma restrição de API à sua chave de API para restringir o acesso ao serviço da Vertex AI para Pesquisa para 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 linguagens que podem ser usadas para implementar a autenticação 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