Migrar da versão Beta para a API Retail

A API Retail agora é usada nas recomendações. Nesta página, explicamos as mudanças introduzidas e as práticas recomendadas de migração ao migrar da versão v1beta1 da API Recommendations Engine (endpoint do serviço https://recommendationengine.googleapis.com) para a API Retail, de endpoint geral, disponível para todos os usuários. https://retail.googleapis.com).

A API Recommendations Engine e o conjunto de documentação dela permanecem disponíveis, mas não são mais atualizados.

Este documento se aplica somente se você começou a usar as Recomendações na versão Beta.

Práticas recomendadas

• Envie o tráfego somente para validação antes da migração completa.
• A migração incremental de tráfego é melhor do que fazer tudo de uma só vez. Se possível, migre gradualmente o tráfego da v1beta1 para v2.
• Se você estiver executando serviços em diferentes regiões, é melhor migrar regiões uma a uma para evitar interrupções globais.

Mudanças na documentação

Depois de mudar para o console do Retail, recomendamos que você use exclusivamente esta documentação do Retail em https://cloud.google.com/retail/docs.

A documentação Beta definida para a API Recommendations Engine continua disponível, mas não é mais atualizada.

Mudanças no console

O console do Retail substitui o console de recomendações.

O console do Google Cloud para varejo está disponível publicamente desde 20 de janeiro de 2022. Se você usa o console de recomendações, recomendamos acessar seus projetos de recomendações no console do Varejo.

Para uma explicação sobre as mudanças na funcionalidade e terminologia dos consoles de varejo em comparação com o console de recomendações, consulte Mudar para o console do Retail.

Esquemas de eventos do catálogo e do usuário

Os esquemas de eventos do usuário e catálogo foram alterados na API Retail.

• Ao importar dados de catálogo do BigQuery, use o esquema para varejo: esquema de catálogo de varejo.

• Ao gravar dados do evento do usuário, use o esquema apropriado para cada evento do usuário: Esquemas de eventos do usuário de varejo (em inglês).

Configurações de veiculação e posições

A API Retail introduz configurações de veiculação, que substituem o conceito de posições usadas pela API Recommendations Engine.

As configurações de exibição estão disponíveis a partir das Recomendações v2 e Retail Search v2alpha, usando a API Retail.

O recurso servingConfig está disponível nas versões v2beta e v2alpha da API Retail. É possível usar este recurso para criar, visualizar, editar e remover configurações de exibição.

Se você tiver posições atuais ou criar novas, a API Retail criará automaticamente uma configuração de exibição associada a cada posição. A criação de uma configuração de exibição não cria uma posição correspondente.

A exclusão de uma configuração de exibição exclui a posição correspondente, e a exclusão de uma posição também remove a configuração de exibição correspondente.

As configurações de exibição permitem editar opções de reclassificação de preços e diversidade e fazer com que elas entrem em vigor quase em tempo real. Com as posições, as configurações de diversidade e preço só podem ser alteradas no modelo de recomendação indicado pela posição.

As posições ainda são compatíveis, mas é recomendável usar as configurações de veiculação.

Para mais informações sobre como usar configurações de exibição, consulte Configurações de exibição e Como criar configurações de exibição.

Caminhos REST e RPC

Muitas alterações foram feitas nos caminhos REST e RPC. Revise a documentação da API para a API Retail para garantir que você a chame corretamente.

Agora, todos os caminhos usam retail.googleapis.com em vez de recommendationengine.googleapis.com.

Exemplo:

API v1beta1 Recommendations Engine:

GET https://recommendationengine.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

API v2 Retail:

GET https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/OPERATION_ID

Alguns recursos e métodos foram renomeados, removidos ou adicionados recentemente. A tabela abaixo compara os recursos v1beta1 e v2 e os métodos associados lado a lado.

Por exemplo, o recurso v1beta1 catalogs.catalogItems equivale ao recurso v2 catalogs.branches.products. O método list, que estava disponível em catalogs.catalogItems para a v1beta1, não está disponível para catalogs.branches.products na v2, portanto, é indicado como Removido.

Observe que os links para recursos de v1beta1 vão para a documentação da API de v1beta1.

Recurso v1beta1	Método	Recurso v2	Método
catalogs	list	catalogs	list
	patch		patch
N/A		catalogs.branches.operations	get
catalogs.catalogItems	create	catalogs.branches.products	create
	delete		delete
	get		get
	import		import
	list		Removida
	patch		patch
catalogs.operations	get	catalogs.operations	get
	list		list
catalogs.eventStores.operations	get	Removido
	list
catalogs.eventStores.placements	predict	catalogs.placements	predict
catalogs.eventStores.predictionApiKeyRegistrations	create	Removido
	delete
	list
catalogs.eventStores.userEvents	collect	catalogs.userEvents	collect
	import		import
	list		Removida
	purge		purge
	rejoin		rejoin
	write		write
N/A		operations	get
			list

Alterações do IAM

As seguintes alterações foram introduzidas nos papéis e nas permissões do gerenciamento de identidade e acesso (IAM) de varejo:

• O Retail usa papéis e permissões do IAM no namespace retail em vez do namespace automlrecommendations que foi usado pelo Recommendations Engine v1beta1.
• O papel Admin Viewer foi removido.
• As permissões de apiKeys foram removidas porque o método predict não requer mais a própria chave de API.