Usar especificações de aplicativo para solicitar pontos de extremidade externos dos consumidores¶

Acessar serviços externos de um Snowflake Native App¶

Alguns Snowflake Native Apps precisam se conectar a recursos que existem fora do Snowflake. O Snowflake fornece diferentes objetos dependendo do tipo de conexão externa necessária.

Ao usar a concessão automatizada de privilégios, um aplicativo tem os privilégios necessários para criar esses objetos ao executar o script de configuração. No entanto, como esses objetos permitem conexões fora do Snowflake, os consumidores devem aprovar essas conexões ao configurar o aplicativo.

As especificações de aplicativo permitem que um provedor especifique quais informações de conexão o aplicativo solicita. Quando o consumidor instala o aplicativo, ele analisa a especificação de aplicativo e aprova ou recusa conforme necessário.

Fluxo de trabalho de especificação de aplicativos¶

O fluxo de trabalho geral para configurar e usar uma especificação de aplicativo é o seguinte:

1. Os provedores configuram a concessão automatizada de privilégios para o aplicativo. Isso permite que os consumidores deem permissão a um aplicativo para criar a integração de acesso externo.

   Nota

   As especificações de aplicativo exigem que manifest_version = 2 seja definido no arquivo de manifesto.

2. Os provedores adicionam o privilégio CREATE EXTERNAL ACCESS INTEGRATION ao arquivo de manifesto.

3. Os provedores adicionam instruções SQL ao script de configuração para criar os seguintes objetos, conforme necessário:

   • Regra de rede

   • Integração de acesso externo

   • Integração de segurança

   • Especificação de aplicativo

   O script de configuração cria a especificação de aplicativo e outros objetos quando o aplicativo é instalado ou atualizado, ou está no tempo de execução.

4. Ao configurar o aplicativo, os consumidores aprovam as portas do host e outros serviços externos. Para obter mais informações, consulte Aprovar conexões com recursos externos usando especificações de aplicativo.

Adicionar o privilégio CREATE EXTERNAL ACCESS INTEGRATION ao arquivo de manifesto¶

Para configurar um aplicativo para solicitar o privilégio CREATE EXTERNAL ACCESS INTEGRATION, adicione o seguinte código à seção privileges do arquivo de manifesto:

manifest_version: 2
...
privileges:
  - CREATE EXTERNAL ACCESS INTEGRATION:
      description: "Allows the app to create an external access integration to connect to an external service."
...

Esta entrada na seção privileges do arquivo de manifesto especifica que o aplicativo usa uma integração de acesso externo. Para que o aplicativo use a concessão automatizada de privilégios, o arquivo de manifesto também requer a definição de manifest_version: 2.

Adicionar uma regra de rede e integração de acesso externo ao script de configuração¶

Integrações de acesso externo são os objetos Snowflake que permitem o acesso a locais de rede externos específicos. As integrações de acesso externo contêm uma lista de regras de rede que especificam os locais externos que um aplicativo pode acessar.

Para criar uma regra de rede para um aplicativo, adicione o comando CREATE NETWORK RULE ao script de configuração, como mostrado no exemplo a seguir:

CREATE OR REPLACE NETWORK RULE setup.my_network_rule
 TYPE = HOST_PORT
 VALUE_LIST = ( 'example.com' )
 MODE = EGRESS;

As propriedades HOST_PORT e VALUE_LIST indicam que a regra de rede deve apontar para um domínio, porta ou intervalo de portas válido. Quando um aplicativo é instalado ou atualizado, um consumidor concederá permissão para o aplicativo usar esses domínios ou portas.

Para criar uma integração de acesso externo para um aplicativo, adicione o comando CREATE EXTERNAL ACCESS INTEGRATION ao script de configuração, como mostrado no exemplo a seguir:

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_app_prefix_eai_rule
  ALLOWED_NETWORK_RULES = (setup.my_network_rule)
  ENABLED = TRUE;

Esse comando cria uma integração de acesso externo chamada my_app_prefix_eai_rule que permite que o aplicativo acesse recursos externos ou pontos de extremidade. Ele usa a regra de rede setup.my_network_rule.

Adicionar uma integração de segurança ao script de configuração¶

As integrações de segurança permitem que um aplicativo se conecte a um serviço de autenticação de terceiros, como o OAuth. Use o comando CREATE SECURITY INTEGRATION (Autenticação de API externa) para criar uma integração de segurança para um aplicativo, como mostrado no exemplo a seguir:

CREATE SECURITY INTEGRATION external_oauth_provider
  TYPE = API_AUTHENTICATION
  AUTH_TYPE = OAUTH2
  OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
  OAUTH_CLIENT_ID = 'YOUR_CLIENT_ID'
  OAUTH_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'
  OAUTH_GRANT = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default')
  ENABLED = TRUE;

Este exemplo mostra como criar uma integração de segurança para se conectar ao Microsoft Sharepoint usando o OAuth com credenciais do cliente. Consulte outros métodos aceitos para conexão com um provedor do OAuth em CREATE SECURITY INTEGRATION (Autenticação de API externa).

Criação de uma especificação de aplicativo no script de configuração¶

Para criar a especificação de aplicativo, os provedores adicionam o comando ALTER APPLICATION SET SPECIFICATIONS ao script de configuração.

ALTER APPLICATION SET SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'

ALTER APPLICATION SET SPECIFICATION oauth_app_spec
  TYPE = SECURITY_INTEGRATION
  LABEL = 'Connection to an external OAuth provider'
  DESCRIPTION = 'Integrates an external identity provider in the app'
  OAUTH_TYPE = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default');

Práticas recomendadas para usar especificações de aplicativo¶

A concessão automatizada de privilégios garante que o aplicativo tenha os privilégios necessários para criar integrações de acesso externo. No entanto, os consumidores podem optar por recusar a especificação de aplicativo que permite a conexão com os pontos de extremidade externos. Ao desenvolver um aplicativo, os provedores devem levar em conta situações em que as especificações de aplicativo podem não ser aprovadas

Por exemplo, um aplicativo pode solicitar o uso de várias portas de rede para uma integração de acesso externo, mas o consumidor pode permitir apenas uma. O aplicativo deve incluir lógica para lidar com erros que ocorrem se uma porta de rede não estiver disponível. Além disso, é uma prática recomendada capturar quaisquer exceções HTTP que possam ocorrer.

Uso de funções de retorno de chamada com especificações de aplicativo¶

Em alguns contextos, um aplicativo pode precisar saber quando o consumidor aprovou ou recusou uma especificação de aplicativo. Por exemplo, o aplicativo pode precisar aguardar até que uma especificação de aplicativo seja aprovada antes de criar um objeto.

Para lidar com essa situação, o Snowflake Native App Framework fornece um mecanismo que permite ao provedor definir um procedimento armazenado de retorno de chamada que é executado quando o consumidor aprova ou recusa uma especificação de aplicativo.

Os provedores podem adicionar um procedimento armazenado ao arquivo de manifesto, conforme mostrado no exemplo a seguir:

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update

Esse exemplo mostra como adicionar um procedimento armazenado chamado callbacks.on_spec_update ao arquivo de manifesto. Os provedores podem adicionar um procedimento armazenado ao script, como mostrado no exemplo a seguir:

CREATE OR REPLACE PROCEDURE callbacks.on_spec_update (
  name STRING,
  status STRING,
  payload STRING)
  ...

Este exemplo mostra a assinatura de um procedimento armazenado chamado callbacks.on_spec_update. No corpo desse procedimento, os provedores incluem o código necessário para verificar o status da especificação de aplicativo, criar objetos e executar ações conforme necessário.