Armazenamento doméstico

Em uma chamada do webhook, você pode armazenar valores de parâmetros em várias sessões da mesma família (com base no Home Graph) no armazenamento doméstico. Sua ação poderá usar esses valores armazenados mais tarde em solicitações e condições, e o código do webhook poderá acessar valores no armazenamento doméstico de uma família específica quando necessário.

O estado do armazenamento doméstico é transmitido em uma solicitação app.handle() e armazenado no objeto home.

Importante: não use o armazenamento doméstico para armazenar dados pessoais. Os dados de armazenamento doméstico se aplicam a vários indivíduos na mesma casa que usam a mesma ação. Para dados específicos do usuário, use o armazenamento do usuário e solicite o consentimento dele antes de salvar dados pessoais.

Limitações

O armazenamento doméstico não pode ser usado com dispositivos móveis, porque não faz parte de um gráfico doméstico. No código do webhook, use o recurso de dispositivo HOME_STORAGE para ramificar a lógica de negócios com base no que o dispositivo do usuário é capaz.

Você precisa ativar o uso do armazenamento doméstico:

1. No Console do Actions, acesse Implantar > Informações do diretório.
2. Na seção Informações adicionais, marque a caixa Armazenamento em casa.

Observação: ao usar o armazenamento doméstico, o Google também apresenta uma exoneração de responsabilidade uma vez para os usuários verificados e a cada invocação para os usuários convidados (até uma vez a cada 10 minutos).

Ler e gravar dados em uma família

Para atualizar ou definir um novo valor no armazenamento inicial, atribua o valor ao campo params do objeto home em uma chamada de webhook. O exemplo a seguir define "exampleColor" como "red" no armazenamento doméstico:

Node.js (link em inglês)

// Assign color to home storage
app.handle('storeColor', conv => {
  let color = 'red';
  conv.home.params.exampleColor = color;
});
    

JSON

{
  "responseJson": {
    "session": {
      "id": "1234567890123456789",
      "params": {}
    },
    "prompt": {
      "override": false
    },
    "home": {
      "params": {
        "exampleColor": "red"
      }
    }
  }
}
    

Para acessar os dados armazenados no armazenamento inicial, atribua-os a uma variável em uma chamada de webhook. O exemplo a seguir recupera um valor de "exampleColor" no armazenamento inicial:

Node.js (link em inglês)

// Retrieve color from home storage
app.handle('getStoredColor', conv => {
  let color = conv.home.params.exampleColor;
});
    

JSON

{
  "responseJson": {
    "session": {
      "id": "1234567890123456789",
      "params": {}
    },
    "prompt": {
      "override": false
    },
    "home": {
      "params": {
        "homeColor": "red"
      }
    }
  }
}
    

Para limpar um valor salvo anteriormente, defina-o como null em uma chamada de webhook. O exemplo a seguir limpa o valor de "exampleColor" no armazenamento doméstico:

Node.js (link em inglês)

// Clear color from home storage
app.handle('clearStoredColor', conv => {
  conv.home.params.exampleColor = null;
});
    

JSON

{
  "responseJson": {
    "session": {
      "id": "1234567890123456789",
      "params": {}
    },
    "prompt": {
      "override": false
    },
    "home": {
      "params": {}
    }
  }
}
    

Referência a valores armazenados em prompts

É possível referenciar valores armazenados no armazenamento doméstico em uma solicitação. Para fazer referência ao valor, use a sintaxe $home.params.PARAMETER_NAME, em que PARAMETER_NAME é o nome fornecido no webhook quando o parâmetro foi definido.

Por exemplo, você já armazenou um valor de cor no armazenamento doméstico como o parâmetro exampleColor. Para acessar esse valor em um prompt, faça referência a ele usando $home.params.exampleColor:

JSON

{
  "candidates": [{
    "first_simple": {
      "variants": [{
        "speech": "Your favorite color is $home.params.exampleColor."
      }]
    }
  }]
}
    

Faça referência a valores armazenados em condições

Também é possível referenciar valores armazenados no armazenamento doméstico em condições. Para fazer referência ao valor, use a sintaxe home.params.PARAMETER_NAME, em que PARAMETER_NAME é o nome dado no webhook quando o parâmetro foi definido.

Por exemplo, você já armazenou um valor de cor no armazenamento doméstico como o parâmetro exampleColor e quer combiná-lo com o valor "red" em uma condição. Na condição, faça referência ao valor armazenado usando home.params.exampleColor. A expressão de condição tem a seguinte aparência:

Sintaxe da condição

home.params.exampleColor == "red"
    

Expiração dos dados do armazenamento doméstico

Os dados de armazenamento doméstico são excluídos permanentemente após 90 dias consecutivos em que a ação não é invocada. Invocar a ação em qualquer dispositivo associado à estrutura do gráfico inicial redefine o timer de 90 dias. Se uma estrutura do Home Graph for excluída, os dados de armazenamento correspondente serão apagados.

Para ações que usam armazenamento doméstico, os gerenciadores de estrutura do Home Graph podem limpar o armazenamento inicial para estruturas que gerenciam na página da ação no diretório do Assistente:

1. Encontre e selecione a ação que você quer ver ou limpar o armazenamento do usuário.
2. Role até a parte inferior da página:
   • Para remover os dados armazenados no armazenamento inicial, clique em Impedir que action_name se lembre de mim.

Observação: limpar o armazenamento inicial remove os valores armazenados para convidados e outros gerenciadores de estrutura do Home Graph.

Quando o administrador de um dispositivo o dissocia da estrutura, o armazenamento doméstico também é dissociado. Os dados do armazenamento doméstico continuam sendo associados a um dispositivo, mesmo que ele seja alterado, a menos que um gerenciador de estrutura o apague.

Dados de armazenamento doméstico no simulador

Ao testar sua ação usando o simulador no Console do Actions, os dados armazenados no armazenamento inicial se comportam de maneira um pouco diferente dos dados em um dispositivo físico. O simulador é considerado parte do próprio Home Graph, então os dados não persistem em outros dispositivos que você possa ter na sua rede. Além disso, os dados de armazenamento inicial não permanecem nas sessões quando a configuração do simulador Simular usuário não verificado está ativada.

Exemplo de interação

Veja um exemplo de interação de um usuário conectado na primeira invocação da ação:

Consulta do usuário	Ok Google, fale com a ExampleAction.
Resposta do Assistente	Como acessar ExampleAction.
Resposta do Assistente	Saiba que o ExampleAction é salvo sempre que é tocado para que os outros membros da família possam continuar de onde você parou.
Resposta de ActionAction	Olá, usuário verificado. Você está no nível 0. Diga "Avançar", "Redefinir" ou "Cancelar".
Consulta do usuário	Próxima.
Resposta de ActionAction	Você está no nível 1.
Consulta do usuário	Sair.

Depois, quando o mesmo usuário verificado retornar à ação após algum tempo:

Consulta do usuário	Ok Google, fale com a ExampleAction.
Resposta do Assistente	Como acessar ExampleAction.
Resposta de ActionAction	Olá, usuário verificado. Você está no nível 1. Diga "Avançar", "Redefinir" ou "Cancelar".
Consulta do usuário	Próxima.
Resposta de ActionAction	Você está no nível 2.
Consulta do usuário	Sair.

No dia seguinte, um usuário não verificado interage com a ação em outro dispositivo da mesma família (conforme especificado no gráfico inicial).

Observação: o Google apresentará a exoneração de responsabilidade somente se tiverem passado pelo menos 10 minutos desde a última invocação da ação nessa família.

Consulta do usuário	Ok Google, fale com a ExampleAction.
Resposta do Assistente	Como acessar ExampleAction.
Resposta do Assistente	Saiba que o ExampleAction é salvo sempre que é tocado para que os outros membros da família possam continuar de onde você parou.
Resposta de ActionAction	Olá, usuário convidado. Você está no nível 2. Diga "Avançar", "Redefinir" ou "Cancelar".
Consulta do usuário	Próxima.
Resposta de ActionAction	Você está no nível 3.
Consulta do usuário	Sair.