Configuração de conexão

A configuração da conexão é uma etapa do assistente que vem logo após a configuração do conector. Esta etapa permite que o usuário especifique as propriedades necessárias para estabelecer uma conexão com o sistema de origem para começar a ingerir dados no Snowflake. O procedimento chamado PUBLIC.SET_CONNECTION_CONFIGURATION(connection_configuration VARIANT) é o ponto de entrada responsável por esta fase do assistente. Este procedimento pode ser chamado pela UI ou da planilha. Ao substituir com lógica personalizada, este procedimento precisa ser substituído para especificar o manipulador Java personalizado.

Chamar este procedimento requer que o usuário tenha a função do aplicativo ADMIN atribuída.

A etapa de configuração da conexão consiste internamente em várias fases. Alguns deles são totalmente personalizáveis e, por padrão, não fazem nada. As fases são as seguintes:

  1. Validação de status

  2. Validação de entrada

  3. Atualização de configuração

  4. Retorno de chamada interno

  5. Validação de conexão

  6. Atualização de status

Requisitos

A configuração da conexão requer pelo menos os seguintes arquivos SQL a serem executados durante a instalação do aplicativo nativo:

Além disso, há um requisito dependente do usuário SDK:

  • implementação personalizada do procedimento PUBLIC.TEST_CONNECTION()

Validação de status

Para executar a configuração da conexão, o status interno do conector precisa ser CONFIGURING, com status de configuração: CONFIGURED ou CONNECTED. O primeiro status de configuração será definido logo após a etapa de configuração do conector; o último estará presente se, por algum motivo, a configuração de conexão tiver que ser atualizada durante etapas posteriores.

Esta validação não pode ser substituída usando ConnectionConfigurationHandlerBuilder nem sobrescrevendo um procedimento armazenado. No entanto, é possível implementar um manipulador personalizado, que não terá esse tipo de validação.

Validação de entrada

A entrada precisa ser uma variant contendo um mapa de propriedades, porém isso pode não funcionar para todos os casos. Por essa razão, o SDK fornece um procedimento armazenado interno chamado: PUBLIC.SET_CONNECTION_CONFIG_VALIDATE(config VARIANT). Por padrão, este procedimento apenas retorna 'responseCode': 'OK', substituí-lo pode atualizar a configuração fornecida durante a validação. Esse recurso permite lógica personalizada. Por exemplo, cortar a entrada ou converter para maiúsculas/minúsculas. Para retornar a configuração transformada de qualquer forma, a resposta precisa conter uma propriedade adicional "config" na resposta Variant, esta propriedade deve conter a configuração atualizada como Variant. O procedimento pode ser personalizado por meio de sobreposição através do SQL ou usando ConnectionConfigurationHandlerBuilder e fornecer implementação personalizada da interface ConnectionConfigurationInputValidator.

A seguir está uma resposta válida da implementação personalizada com transformação:

{
    "response_code" : "OK",
    "config": {
        "key1": "value1",
        "key2": "value2"
    }
}
Copy

Atualização de configuração

Depois que as validações forem aprovadas com sucesso, a configuração será salva na tabela APP_CONFIG interna. O serviço responsável por isso salva a Variant fornecida sob a chave connection_configuration. Esta configuração não segue nenhum requisito adicional ao salvar, o conjunto de propriedades fornecida fica a critério do usuário.

Retorno de chamada interno

O retorno de chamada interno é outra etapa personalizável. Por padrão, ele invoca PUBLIC.SET_CONNECTION_CONFIGURATION_INTERNAL(connection_configuration VARIANT), que retorna 'response_code': 'OK'. Por exemplo, ele pode ser usado para alterar outros procedimentos, concedendo-lhes integração de acesso externo. Pode ser sobrescrito através do script SQL ou usando um ConnectionConfigurationHandlerBuilder para fornecer implementação personalizada da interface ConnectionConfigurationCallback.

Validação de conexão

Esta etapa aciona um procedimento PUBLIC.TEST_CONNECTION. Este procedimento tenta consultar o sistema de origem para obter os dados. Este procedimento não é implementado por padrão e precisa ser fornecido pelo usuário do SDK. Adicionalmente, a implementação da interface ConnectionValidator pode ser fornecida ao ConnectionConfigurationHandlerBuilder para personalizar esta fase, neste caso, não há necessidade de implementar um procedimento armazenado. A recomendação é executar apenas uma verificação mínima de conectividade neste procedimento para garantir que os recursos de acesso externo do Snowflake foram configurados corretamente e que o conector tem todos os privilégios necessários para usá-los.

Atualização de status

Quando todas as fases acima forem concluídas com sucesso, o status interno do conector será atualizado para:

{
    "status": "CONFIGURING",
    "configurationStatus": "CONNECTED"
}
Copy

Para o diagrama completo de transições de estado, veja Fluxo do conector.

Visualização da configuração

Há um procedimento PUBLIC.GET_CONNECTION_CONFIGURATION() disponível para os usuários ADMIN e VIEWER que retorna uma configuração de conexão atual da tabela interna.

Resposta

Resposta bem-sucedida

Se o procedimento for concluído com sucesso, ele retornará uma resposta do procedimento TEST_CONNECTION. Recomendamos usar o seguinte formato:

{
  "response_code": "OK"
}
Copy

Resposta de erro

Em caso de erro, a resposta seguirá o formato abaixo:

{
  "response_code": "<ERROR_CODE>",
  "message": "<error message>"
}
Copy

Possíveis códigos de erro incluem:

  • INVALID_CONNECTOR_STATUS - Status do conector inválido. Status esperado: [CONFIGURING]

  • INVALID_CONNECTOR_CONFIGURATION_STATUS - Status de configuração do conector inválido. Status esperado: CONFIGURED

  • INTERNAL_ERROR - Algo deu errado internamente, a mensagem deve ser descritiva

  • PROCEDURE_NOT_FOUND - O procedimento que foi chamado não existe. Nesse caso, trata-se principalmente de um procedimento TEST_CONNECTION.

  • UNKNOWN_SQL_ERROR - Este erro ocorre quando algo inesperado acontece ao chamar procedimentos internos

  • INVALID_RESPONSE - Este erro ocorre quando a resposta recebida do procedimento interno não contém response_code ou uma resposta de erro não contém message, mas contém response_code

  • UNKNOWN_ERROR - Significa que algo inesperado deu errado - a mensagem de exceção lançada é encaminhada

  • Códigos de erro personalizados recebidos do procedimento TEST_CONNECTION() - definido pelo desenvolvedor do conector

  • Códigos de erro personalizados recebidos do procedimento SET_CONNECTION_CONFIGURATION_INTERNAL() - definido pelo desenvolvedor do conector

Linguagem: Português