Configuração do aplicativo¶

Este tópico descreve como um Snowflake Native App pode usar objetos de configuração de aplicativo para solicitar entrada do consumidor.

Configuração do aplicativo: Visão geral¶

Uma configuração de aplicativo é um par chave-valor que fornece um mecanismo de coordenação entre um Snowflake Native App e o consumidor. Quando um Snowflake Native App requer entrada do consumidor, ele define uma chave de configuração juntamente com uma descrição explicando a finalidade da configuração. O consumidor então fornece o valor para essa chave.

A configuração do aplicativo é compatível com os seguintes tipos:

APPLICATION_NAME: O consumidor fornece o nome de um app instalado na conta do consumidor. Este tipo é utilizado para comunicação entre apps.
STRING: O consumidor fornece um valor de cadeia de caracteres arbitrário. É possível usar esse tipo em vários casos de uso, como fornecer URLs externos, identificadores de conta ou outras configurações específicas do app.

O fluxo de trabalho de configuração do aplicativo envolve as seguintes etapas:

O app cria uma definição de configuração usando ALTER APPLICATION SET CONFIGURATION DEFINITION, especificando o tipo de informação necessária e as funções do app que têm acesso à configuração.
O consumidor visualiza as solicitações de configuração recebidas usando SHOW CONFIGURATIONS ou Snowsight.
O consumidor fornece o valor solicitado usando ALTER APPLICATION SET CONFIGURATION VALUE ou Snowsight.
O app recupera o valor e o usa para realizar outras operações, como criar uma especificação de aplicativo para uma conexão.

O Snowflake Native App Framework fornece retornos de chamada para notificar o app quando um valor de configuração é definido ou alterado. Para obter mais informações, consulte Retornos de chamada de configuração.

Terminologia¶

A configuração do aplicativo usa os seguintes termos:

Definição de configuração: Um objeto que o app cria para solicitar uma informação específica do consumidor. A definição de configuração especifica o tipo de informação solicitada, um rótulo, uma descrição e as funções do app que têm acesso à configuração.
Valor da configuração: O valor que o consumidor fornece em resposta a uma solicitação de definição de configuração.

Usando configurações¶

Esta seção descreve como criar, exibir e gerenciar configurações.

Criar uma solicitação de configuração
Visualizar solicitações de configuração
Fornecer o valor da configuração
Atualizar o valor de uma configuração
Remover o valor de uma configuração
Recuperar o valor de uma configuração

Criar uma solicitação de configuração¶

Para solicitar um valor de configuração do consumidor, o app cria uma definição no script de configuração ou em tempo de execução. A definição de configuração especifica o tipo de valor esperado, um rótulo e uma descrição que são exibidos ao consumidor e as funções do app que podem visualizar a configuração e editar o valor.

O exemplo a seguir mostra como criar uma definição de configuração do tipo STRING que solicita do consumidor o URL de uma empresa:

ALTER APPLICATION SET CONFIGURATION DEFINITION company_url
  TYPE = STRING
  LABEL = 'Company URL'
  DESCRIPTION = 'Provide the company website URL'
  APPLICATION_ROLES = (app_user)
  SENSITIVE = FALSE;

Copy

As seguintes propriedades controlam como a configuração é exibida e gerenciada:

LABEL: o nome exibido ao consumidor no Snowsight.
DESCRIPTION: uma descrição que ajuda o consumidor a entender a finalidade da configuração.
APPLICATION_ROLES: as funções do app que podem visualizar e definir o valor para esta configuração. As funções do consumidor que recebem uma das funções de app especificadas podem visualizar a configuração e editar seu valor.
SENSITIVE: especifica se o valor da configuração deve ser tratado como confidencial. Quando definido como TRUE, o valor não é exibido na saída de SHOW CONFIGURATIONS. Para obter mais informações, consulte Configurações confidenciais.

Visualizar solicitações de configuração¶

Depois que um app cria uma solicitação de configuração, o consumidor pode visualizar as solicitações pendentes usando SQL ou o Snowsight.

Para visualizar as solicitações de configuração e os detalhes de uma definição de configuração usando SQL, use os comandos SHOW CONFIGURATIONS e DESCRIBE CONFIGURATION:

SHOW CONFIGURATIONS IN APPLICATION example_app;

DESCRIBE CONFIGURATION company_url IN APPLICATION example_app;

Copy

Fornecer o valor da configuração¶

Depois que o app cria uma solicitação de configuração, o consumidor fornece o valor solicitado usando SQL ou o Snowsight.

Para fornecer um valor para a configuração usando SQL, use o comando ALTER APPLICATION SET CONFIGURATION VALUE:

ALTER APPLICATION <app> SET CONFIGURATION <config> VALUE = '<value>';

Copy

Atualizar o valor de uma configuração¶

Você pode atualizar o valor de uma configuração usando SQL ou o Snowsight.

Para atualizar o valor de uma configuração, use a mesma sintaxe que para definir o valor inicial:

ALTER APPLICATION <app> SET CONFIGURATION <config> VALUE = '<value>';

Copy

Remover o valor de uma configuração¶

Você pode remover o valor de uma configuração usando SQL ou o Snowsight.

Para remover o valor de uma configuração usando SQL, use o comando ALTER APPLICATION UNSET CONFIGURATION:

ALTER APPLICATION <app> UNSET CONFIGURATION <config>;

Copy

Recuperar o valor de uma configuração¶

Além de SHOW CONFIGURATIONS ou DESCRIBE CONFIGURATION, um app pode recuperar o valor de uma configuração fornecida pelo consumidor usando a função get_configuration_value. O exemplo a seguir mostra como recuperar o valor de uma configuração:

SELECT SYS_CONTEXT('SNOWFLAKE$APPLICATION', 'GET_CONFIGURATION_VALUE' , '<config_name>')

Copy

Nota

Somente o app pode recuperar o valor da configuração do contexto do sistema. Para visualizar o valor da configuração como consumidor, você pode visualizar os detalhes da configuração usando SQL ou o Snowsight. Para obter mais informações, consulte Visualizar solicitações de configuração.

Configurações confidenciais¶

Quando um app cria uma configuração, ele pode marcá-la como confidencial com a definição SENSITIVE = TRUE. Isso é útil quando o app precisa solicitar informações confidenciais do consumidor, como um token de acesso pessoal ou uma chave API.

Nota

A propriedade SENSITIVE só é compatível com configurações do tipo STRING.

Quando uma configuração é confidencial, o valor fornecido pelo consumidor é protegido de outros usuários e funções do consumidor. O Snowflake Native App Framework aplica proteções semelhantes às utilizadas para objetos SECRET no Snowflake:

Depois que o consumidor define um valor, o histórico de consultas do comando ALTER APPLICATION SET CONFIGURATION VALUE oculta o valor para que ele não seja exposto a outras funções ou usuários do consumidor.
O valor não é exibido na saída das exibições SHOW CONFIGURATIONS, DESCRIBE CONFIGURATION, INFORMATION_SCHEMA ou ACCOUNT_USAGE.

O app que cria a configuração sempre pode recuperar o valor fornecido pelo consumidor, mesmo quando a configuração é confidencial. Isso é intencional, pois o objetivo de uma configuração de aplicativo é que o consumidor forneça um valor ao app.

Alterando a propriedade SENSITIVE¶

Um app não poderá alterar a propriedade SENSITIVE enquanto a configuração tiver um valor definido (ou seja, quando a configuração não estiver em um estado PENDING). Essa restrição impede que o valor do consumidor seja exposto acidentalmente. Se o app tentar alterar a propriedade SENSITIVE enquanto um valor estiver definido, o comando será concluído sem erros, mas não terá efeito.

Para alterar a propriedade SENSITIVE, o consumidor deve primeiro remover o valor da configuração usando ALTER APPLICATION UNSET CONFIGURATION.

Referência de SQL¶

Os seguintes comandos, funções e exibições SQL são utilizados para gerenciar configurações de aplicativos.

Comandos SQL¶

ALTER APPLICATION SET CONFIGURATION DEFINITION: cria ou atualiza uma definição de configuração de aplicativo que solicita um valor do consumidor.
ALTER APPLICATION DROP CONFIGURATION DEFINITION: exclui uma definição de configuração de aplicativo.
ALTER APPLICATION SET CONFIGURATION VALUE: define um valor em uma configuração do aplicativo.
ALTER APPLICATION UNSET CONFIGURATION: remove o valor de uma configuração de aplicativo.
SHOW CONFIGURATIONS: lista todas as configurações em um aplicativo.
DESCRIBE CONFIGURATION: descreve os detalhes de uma configuração de aplicativo.

Funções SQL¶

IS_CONFIGURATION_SET (função SYS_CONTEXT): retorna se a configuração tem ou não um valor definido.
GET_CONFIGURATION_VALUE (função SYS_CONTEXT): retorna o valor atual de uma configuração.

Exibições e funções do Information Schema¶

Exibição APPLICATION_CONFIGURATIONS: Esta exibição do Information Schema exibe uma linha para cada configuração de aplicativo atualmente definida no banco de dados especificado ou atual onde o INFORMATION_SCHEMA está localizado.
APPLICATION_CONFIGURATION_VALUE_HISTORY: Retorna o histórico de valores para uma configuração.

Exibições do esquema de uso da conta¶

Exibição APPLICATION_CONFIGURATIONS: Esta visualização do uso da conta exibe uma linha para cada configuração de aplicativo na conta.
Exibição APPLICATION_CONFIGURATION_VALUE_HISTORY: Esta visualização do uso da conta exibe o histórico de valores para uma configuração.

Retornos de chamada¶

Quando um valor de configuração é alterado, o Snowflake Native App Framework pode invocar retornos de chamada de ciclo de vida registrados no arquivo manifest do app. Esses retornos de chamada permitem que o aplicativo valide, prepare-se ou reaja a alterações de configuração. Por exemplo, ao configurar a comunicação entre aplicativos, um caso de uso comum é usar o retorno de chamada before_configuration_change para criar ou atualizar automaticamente uma especificação de conexão quando o consumidor define o nome do app do servidor. Isso evita que o consumidor precise executar etapas manuais adicionais após definir o valor da configuração. Para obter mais informações sobre comunicação entre apps, consulte Comunicação entre aplicativos.

Os seguintes retornos de chamada de configuração estão disponíveis:

validate_configuration_change: Um retorno de chamada síncrono chamado como parte do comando ALTER APPLICATION SET CONFIGURATION VALUE. Permite que o app execute validação personalizada no valor fornecido. Se o retorno de chamada retornar um erro, o comando falhará e o novo valor não será definido.
before_configuration_change: Um retorno de chamada síncrono chamado como parte dos comandos ALTER APPLICATION SET CONFIGURATION VALUE e ALTER APPLICATION UNSET CONFIGURATION. Permite que o app execute operações com base no valor da configuração antes que ele seja salvo.
after_configuration_change: Um retorno de chamada assíncrono chamado após a conclusão dos comandos ALTER APPLICATION SET CONFIGURATION VALUE ou ALTER APPLICATION UNSET CONFIGURATION. Permite que o app reaja à alteração, por exemplo, para fins de notificação ou rastreamento.

Para obter assinaturas de retorno de chamada e valores de retorno completos, consulte Retornos de chamada.