Exemplo – Configuração de acesso externo para serviços em um aplicativo com contêineres¶

Como adicionar uma referência de integração de acesso externo ao arquivo de manifesto¶

O exemplo a seguir mostra como um provedor define uma integração de acesso externo no arquivo de manifesto:

references:
  ...
  - my_external_access:
      label: "Default External Access Integration"
      description: "This EAI is required to access xyz.com"
      privileges:
        - USAGE
      object_type: EXTERNAL ACCESS INTEGRATION
      required_at_setup: true
      register_callback: config.REGISTER_EAI_CALLBACK
      configuration_callback: config.get_config_for_ref

Este exemplo especifica as seguintes propriedades, entre outras, em references:

• my_external_access: Especifica o nome da referência externa.

  • privileges: Lista os privilégios exigidos pela integração de acesso externo. Neste exemplo, o privilégio USAGE é necessário.

  • object_type: EXTERNAL ACCESS INTEGRATION: Indica uma referência a uma integração de acesso externo.

  • required_at_setup: Indica que o consumidor deve autorizar o acesso ao objeto antes que o aplicativo possa criar o objeto ao definir como true.

  • register_callback: Especifica o procedimento armazenado de retorno de chamada usado para registrar a referência no aplicativo.

  • configuration_callback: Especifica a função de retorno de chamada de configuração para o segredo. Consulte Adição da função configuration_callback ao script de configuração para obter mais informações.

Adicione uma referência de segredo ao arquivo de manifesto.¶

O exemplo a seguir mostra como um provedor define um segredo no arquivo de manifesto:

references:
 ...
 - consumer_secret:
     label: "Consumer secret"
     description: "Needed to authenticate with an external endpoint"
     privileges:
       - READ
     object_type: SECRET
     register_callback: config.register_my_secret
     configuration_callback: config.get_config_for_ref

Este exemplo especifica as seguintes propriedades, entre outras, em references:

• consumer_secret: Especifica o nome da referência.

  • privileges: Lista os privilégios exigidos pelo segredo. Neste exemplo, o privilégio READ é especificado.

  • object_type: SECRET: Indica que a referência é um segredo.

  • register_callback: Especifica o procedimento armazenado de retorno de chamada usado para registrar a referência no aplicativo.

  • configuration_callback: Especifica a função de retorno de chamada de configuração para o segredo. Consulte Adição da função configuration_callback ao script de configuração para obter mais informações.

Adição da função configuration_callback ao script de configuração¶

Após adicionar referências para a integração de acesso secreto e externo, você deve adicionar a função configuration_callback ao script de configuração. Para criar uma integração de acesso externo ou segredo, o aplicativo deve ser capaz de determinar valores para a porta do host, o tipo de segredo, a autorização e o ponto de extremidade do token para OAuth, e assim por diante. A função configuration_callback fornece essas informações da conta do consumidor para o aplicativo.

CREATE OR REPLACE PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(ref_name STRING)
RETURNS STRING
LANGUAGE SQL
AS
$$
BEGIN
 CASE (UPPER(ref_name))
   WHEN 'my_external_access' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "host_ports":["google.com"],
         "allowed_secrets" : "LIST",
         "secret_references":["CONSUMER_SECRET"]}}';
   WHEN 'consumer_secret' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "type" : "OAUTH2",
         "security_integration": {
           "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
           "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
           "oauth_authorization_endpoint":
               "https://accounts.google.com/o/oauth2/auth"}}}';
  END CASE;
  RETURN '';
END;
$$;

Snowsight executa este procedimento de retorno de chamada para preencher a caixa de diálogo de configuração que solicita ao usuário que configure os objetos necessários.

O procedimento precisa ser concedido a uma função de aplicativo para execução, conforme mostrado no exemplo a seguir:

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

Melhores práticas ao usar integrações de acesso externo em um aplicativo com contêineres¶

A Snowflake aconselha as seguintes práticas recomendadas ao usar integrações de acesso externo em um aplicativo com contêineres:

• Qualquer referência a integrações de acesso externo especificadas em um comando CREATE SERVICE ou ALTER SERVICE deve ser vinculada antes que os comandos sejam executados no script de configuração. Esses comandos falham quando a referência não está vinculada.

• Quaisquer referências a segredos especificados na especificação do serviço também devem ser vinculadas antes que os comandos CREATE SERVICE ou ALTER SERVICE sejam executados no script de configuração. Esses comandos falham quando a referência não está vinculada.

• Ao retornar uma carga do tipo ERROR em uma função configuration_callback, os provedores devem retornar uma mensagem de erro informativa que ajude o consumidor a entender a causa do erro e como resolvê-lo. Por exemplo:

  • Se houver um erro no aplicativo

  • Se a referência ainda não for necessária

  • Se a referência não estiver pronta para ser permitida.

• Se a função configuration_callback contiver referências com a propriedade required_at_setup definida como TRUE, a função configuration_callback deverá ser bem-sucedida no momento da configuração. Neste contexto, a função configuration_callback não pode depender de informações do consumidor.

• Ao usar uma referência para uma integração de acesso externo com um serviço, considere criar o serviço usando ALLOWED_AUTHENTICATION_SECRETS = ALL, se o aplicativo exigir segredos fornecidos pelo consumidor. Isso simplifica o manuseio de um segredo dentro de uma integração de acesso externo.

• Se um aplicativo só precisa atingir pontos de extremidade específicos e não requer nenhum segredo, use ALLOWED_AUTHENTICATION_SECRETS = NONE. NONE é o valor padrão. Consulte CREATE EXTERNAL ACCESS INTEGRATION para obter mais informações.

• Se o aplicativo precisar atualizar uma referência, primeiro desvincule a referência e, em seguida, solicite ao consumidor que crie e vincule um novo objeto à referência. Um consumidor pode escolher editar e vincular um objeto existente. Consulte CREATE EXTERNAL ACCESS INTEGRATION.