Agora que estamos utilizando os dados que são consultados através do cliente de analytics, precisamos salvar esses dados e atualizá-los. Dessa forma, toda vez que os dados são consultados, queremos atualizá-los utilizando o Master Data (uma base de dados como serviço da VTEX).

Master Data é o serviço da VTEX que torna possível criar arquiteturas de base de dados para uma loja. Em geral, é utilizada para armazenar e organizar dados de clientes, mas também é amplamente utilizada por lojas VTEX para customizações de regras de negócio e para criar aplicações para sua loja virtual. Você pode configurar aplicações que utilizam este módulo como um repositório de dados para criar um sistema em cima do Master Data, sendo necessário apenas a modelagem dos novos dados.

Na versão atual do Master Data, utilizamos o conceito de data entities e, para isso, usa-se o JSON Schema para validar e indexar documentos. Uma entidade de dados pode ter diversos schemas, dependendo de como você utiliza os dados armazenados. Você precisará do nome do JSON Schema para implementar a query, como você verá neste passo.

Nota: o JSON Schema não é necessário para todos os endpoints. Se você não precisa validar seus dados, você pode salvar seus documentos sem nenhum tipo de configuração, apenas indicando a entidade dos dados e provendo credenciais de acesso. No caso deste passo, como precisaremos de validação, é necessário criar um JSON Schema.

Documentos do Master Data tem identificadores únicos e podem ter vários campos customizados. No JSON Schema, você pode declarar os campos e indicar aqueles que você deseja utilizar para indexação. Campos indexados podem ser utilizados como filtros para queries.

Um cliente do Master Data já está disponível para ser utilizado, através do VTEX IO Node Runtime. É possível acessá-lo através do Context, um parâmetro que contém todos os clientes do IO, na propriedade clients.

Neste passo, este cliente será utilizado para pegar informações dos N produtos mais vistos, onde N é um parâmetro que será utilizado para consultar a quantidade desejada de produtos.

Nota: É importante ressaltar que o cliente do Master Data estará disponível para ser utilizado desde que a versão correta do @vtex/api esteja instalada na pasta node. Ele poderá ser acessado através de ctx.clients.masterdata.

Vamos começar?

Esse passo é opcional se você já estiver usando a conta appliancetheme.

Antes de começar a atividade desse passo, você precisa configurar o seu Master Data para poder usar do jeito que a atividade propõe.

Então, você precisa criar uma entidade para salvar a sua lista de produtos. Para fazer isso, usando a nossa API do Master Data, você vai salvar um novo schema.

1. Usando o Postman ou qualquer outro cliente para APIs que preferir, faça um request PUT para esta rota https://{{nome-da-sua-conta}}.vtexcommercestable.com.br/api/dataentities/course_backend_product_list/schemas/{{nome-do-seu-schema}} com os seguintes headers e body:

Note que você precisa preencher algumas informações na rota, como o nome-da-sua-conta e nome-do-seu-schema. Esse último pode ser qualquer nome, mas recomendamos algo como v0.

Headers:

Body:

Para pegar um VTEX local token para o header, basta rodar no seu terminal vtex local token.

Seu request deve ser algo parecido com as imagens abaixo se você estiver usando o Postman:

Fazendo isso, você não só está criando a entidade mas também criando um novo schema que será usado nessa atividade.

Agora você está pronto para começar!

1. Em primeiro lugar, precisamos definir as policies da aplicação, para autorizar o uso do Master Data. Para fazer isso, altere o arquivo manifest.json, como feito abaixo:

   
   

   _20

   //manifest.json

   _20

   {

   _20

   ...

   _20

   },

   _20

   "credentialType": "absolute",

   _20

   "policies": [

   _20

   + {

   _20

   + "name": "ADMIN_DS"

   _20

   + },

   _20

   + {

   _20

   + "name": "outbound-access",

   _20

   + "attrs": {

   _20

   + "host": "api.vtex.com",

   _20

   + "path": "/dataentities/*"

   _20

   + }

   _20

   + }

   _20

   ],

   _20

   "dependencies": {

   _20

   ...

   _20

   }

   
   

   Fazendo isso, estamos garantindo que esta app tem autorização para acessar o Master Data.

2. Agora, para salvar os dados no Master Data, precisamos, em primeiro lugar, checar cada productSlug e ver se já está salvo. Para fazer isso, será utilizado um método do cliente do Master Data chamado searchDocuments. Para utilizá-lo, vá ao arquivo node/event/updateLiveUsers.ts, e faça alterações como as mostradas abaixo:

   
   

   _28

   //node/event/updateLiveUsers.ts

   _28

   ...

   _28

   + import { COURSE_ENTITY } from '../utils/constants'

   _28

   _28

   export async function updateLiveUsers(ctx: EventContext<Clients>) {

   _28

   const liveUsersProducts = await ctx.clients.analytics.getLiveUsers()

   _28

   console.log('LIVE USERS ', liveUsersProducts)

   _28

   + await Promise.all(

   _28

   + liveUsersProducts.map(async ({ slug, liveUsers }) => {

   _28

   + const [savedProduct] = await ctx.clients.masterdata.searchDocuments<{

   _28

   + id: string

   _28

   + count: number

   _28

   + slug: string

   _28

   + }>({

   _28

   + dataEntity: COURSE_ENTITY,

   _28

   + fields: ['count', 'id', 'slug'],

   _28

   + pagination: {

   _28

   + page: 1,

   _28

   + pageSize: 1,

   _28

   + },

   _28

   + schema: 'v1',

   _28

   + where: `slug=${slug}`,

   _28

   + })

   _28

   + console.log('SAVED PRODUCT', savedProduct)

   _28

   + })

   _28

   + )

   _28

   return true

   _28

   }

   
   

   Note que estamos utilizando COURSE_ENTITY, das constantes declaradas globalmente, para acessar os dados da entidade desejada.

3. Agora, para nos certificarmos de que estamos lidando corretamente com erros, implemente uma estrutura de try-catch. Veja o exemplo abaixo:

   
   

   _15

   export async function updateLiveUsers(ctx: EventContext<Clients>) {

   _15

   const liveUsersProducts = await ctx.clients.analytics.getLiveUsers()

   _15

   console.log('MOCKED LIVE USERS ', liveUsersProducts)

   _15

   await Promise.all(

   _15

   liveUsersProducts.map(async ({ slug, liveUsers }) => {

   _15

   + try {

   _15

   ...

   _15

   + } catch (e) {

   _15

   + console.log(`failed to update product ${slug}`)

   _15

   + console.log(e)

   _15

   + }

   _15

   })

   _15

   )

   _15

   return true

   _15

   }

   
   

4. Se o produto já está salvo, precisamos atualizá-lo, de forma a incrementar seu contador de visualizações. O cliente de Master Data tem um método que permite que atualizemos um documento que já existe ou que criemos um novo, no caso do documento não existir - createOrUpdateEntireDocument.

   Para utilizar este método e implementar o incremento na entidade do Master Data, no mesmo arquivo que foi alterado anteriormente, logo após a linha de log, adicione o seguinte bloco de código:

   
   

   _24

   //node/event/updateLiveUsers.ts

   _24

   export async function updateLiveUsers(ctx: EventContext<Clients>) {

   _24

   await Promise.all(

   _24

   liveUsersProducts.map(async ({ slug, liveUsers }) => {

   _24

   try {

   _24

   ...

   _24

   console.log({savedProduct})

   _24

   + await ctx.clients.masterdata.createOrUpdateEntireDocument({

   _24

   + dataEntity: COURSE_ENTITY,

   _24

   + fields: {

   _24

   + count: liveUsers,

   _24

   + slug,

   _24

   + },

   _24

   + id: savedProduct?.id,

   _24

   + schema: 'v1'

   _24

   + })

   _24

   } catch {

   _24

   console.log(`failed to update product ${slug}`)

   _24

   console.log(e)

   _24

   }

   _24

   })

   _24

   )

   _24

   return true

   _24

   }

   
   

   Nota: se um erro é gerado dentro do handler de eventos, o VTEX IO tentará novamente fazer o envio do evento.

5. Finalmente, rode vtex link e espere que um evento seja disparado. Uma vez que isso acontece, cheque o terminal por logs no código. Quebre o vtex link através de ctrl + C e utilize o seguinte cURL no terminal para checar as atualizações no Master Data:

   
   

   _10

   curl --location --request GET 'https://api.vtex.com/api/dataentities/course_backend_product_list/search?_fields=slug,count&_schema=v1&an=appliancetheme' \

   _10

   --header 'Content-Type: application/json'

   
   

   Atenção: Se você tem uma versão do Windows anterior ao Windows 10, versão 1803, é necessário baixar e instalar cURL. Caso contrário, ele já é instalado por default.

   Para rodar o comando cURL no Windows, é necessário substituir as aspas simples (') por aspas duplas (").

   O resultado deve ser algo similar a imagem abaixo: