Armazenamento doméstico

Em uma chamada do webhook, é possível armazenar valores de parâmetro em várias sessões na mesma família (com base no Home Graph) no armazenamento inicial. Sua ação poderá usar esses valores armazenados posteriormente em solicitações e condições, e o código do webhook poderá acessar valores no armazenamento doméstico para uma família específica quando necessário.

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

Limitações

O armazenamento residencial não pode ser usado com dispositivos móveis, porque não faz parte de um gráfico de casa. 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 residencial:

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.

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 do webhook. O exemplo abaixo define "exampleColor" como "red" no armazenamento inicial:

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

{
  "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 o valor de "exampleColor" no armazenamento inicial:

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

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

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

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

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

Fazer referência a valores armazenados em prompts

É possível referenciar valores armazenados no armazenamento da casa 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 inicial como o parâmetro exampleColor. Para acessar esse valor em uma solicitação, use $home.params.exampleColor:

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

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

Também é possível referenciar valores armazenados no armazenamento inicial em condições. 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 inicial como o parâmetro exampleColor e quer fazer a correspondência com o valor "red" em uma condição. Na sua condição, faça referência ao valor armazenado usando home.params.exampleColor. A expressão de condição tem esta aparência:

home.params.exampleColor == "red"
    

Vencimento dos dados de armazenamento doméstico

Os dados de armazenamento doméstico são excluídos permanentemente após 90 dias consecutivos da ação não serem invocados. A invocação da 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 o armazenamento inicial, os gerenciadores da estrutura do Home Graph podem limpar o armazenamento para as estruturas que gerenciam na página "Ação" no diretório do Google Assistente:

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

Quando o administrador de um dispositivo o desassociar da estrutura, o armazenamento residencial também será dissociado. Os dados de armazenamento em casa continuarão associados a um dispositivo, mesmo que o gerenciador da estrutura mude, a menos que um gerenciador de estrutura os apague.

Dados do armazenamento da casa no simulador

Ao testar a ação usando o simulador no Console do Actions, os dados armazenados no armazenamento inicial se comportam de maneira um pouco diferente de 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 local não serão mantidos nas sessões quando a configuração Simular usuário não verificado estiver ativada.

Exemplo de interação

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

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

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 da página inicial).