Configurar uma conexão com o Databricks usando o Databricks JDBC Driver

Este artigo mostra como configurar uma conexão com o Databricks usando o Databricks JDBC Driver, versão 3 e superior.

Configurar a conexão

Para se conectar ao seu espaço de trabalho do Azure Databricks usando o driver JDBC, você precisa especificar várias configurações de conexão, como o nome de host do servidor do espaço de trabalho do Azure Databricks, as configurações de recursos de computação e as credenciais de autenticação para se conectar ao espaço de trabalho.

Você pode definir o valor dessas propriedades na URL de conexão JDBC, defini-las e passá-las para o método DriverManager.getConnectionou uma combinação de ambos. Consulte a documentação do provedor para saber a melhor forma de se conectar usando seu aplicativo, cliente, SDK, API ou ferramenta SQL específica.

A URL de conexão JDBC deve estar no seguinte formato. As propriedades são insensíveis a maiúsculas e minúsculas.

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

Como alternativa, especifique as configurações usando a java.util.Properties classe ou uma combinação:

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

Os elementos de URL de conexão são descritos na tabela a seguir.

Para obter informações sobre propriedades adicionais, incluindo propriedades de autenticação, propriedades de configuração SQL e propriedades de log, consulte Propriedades de conexão com suporte.

Para obter a URL de conexão JDBC para um cluster do Azure Databricks :

1. Faça logon no seu espaço de trabalho do Azure Databricks.
2. Na barra lateral, clique em Computação e, em seguida, clique no nome do cluster de destino.
3. Na guia Configuração, expanda Opções avançadas.
4. Clique na guia JDBC/ODBC.
5. Copie o URL JDBC para usar como URL de conexão JDBC, ou construa o URL a partir dos valores nos campos nome de host do servidor , porta , e caminho HTTP .

Para obter a URL de conexão JDBC para um armazém Databricks SQL :

1. Faça logon no seu espaço de trabalho do Azure Databricks.
2. Na barra lateral, clique em SQL Warehouses e, em seguida, clique no nome do armazém de destino.
3. Clique no separador Detalhes da conexão.
4. Copie o URL JDBC para usar como URL de conexão JDBC, ou construa o URL a partir dos valores nos campos nome de host do servidor , porta , e caminho HTTP .

Configurar tags de consulta

Você pode anexar tags de chave-valor às suas consultas SQL para fins de rastreamento e análise. As tags de consulta aparecem na tabela system.query.history para identificação e análise.

Para adicionar tags de consulta à conexão, inclua a propriedade query_tags no URL JDBC.

jdbc:databricks://<server-hostname>:<port>/<schema>;query_tags=key1:value1,key2:value2

As tags de consulta usam um formato de par chave:valor separado por vírgula:

• query_tags=key:value (tag única)
• query_tags=key1:value1,key2:value2,key3:value3 (várias tags)

Configurar conexões proxy

Você pode configurar o conector para se conectar através de um servidor proxy em vez de se conectar diretamente ao Databricks. Ao conectar-se através de um servidor proxy, o conector suporta autenticação básica e SPNEGO.

Para configurar uma conexão proxy:

1. Defina a UseProxy propriedade como 1.
2. Para definir as configurações de proxy no nível do sistema, defina UseSystemProxy a propriedade como 1, caso contrário, defina-a para o driver da seguinte maneira:
   1. Defina a ProxyHost propriedade para o endereço IP ou nome de host do seu servidor proxy.
   2. Defina a ProxyPort propriedade para a porta que o servidor proxy usa para escutar conexões de cliente.
   3. Defina a ProxyIgnoreList propriedade como um nome de host separado por vírgula.
   4. Autentique-se com o servidor proxy:
      • Para usar a autenticação básica
        1. Defina a ProxyAuth propriedade como 1.
        2. Defina a ProxyUID propriedade como seu nome de usuário para acessar o servidor.
        3. Defina a ProxyPWD propriedade como sua senha para acessar o servidor.
      • Para usar a autenticação SPNEGO:
        1. Autentique a sua principal Kerberos ao nível do sistema.
        2. Defina a ProxyAuth propriedade como 2.

Para usar um proxy diferente especificamente para o CloudFetch, siga as etapas acima com as seguintes propriedades: UseCFProxy, CFProxyHost, CFProxyPort, CFProxyAuth, CFProxyUID, , CFProxyPwd

Configuração do SSL

Se você estiver se conectando ao Databricks com SSL (Secure Sockets Layer) habilitado, poderá configurar o conector para se conectar a um soquete habilitado para SSL. Ao se conectar a um servidor por SSL, o conector usa autenticação unidirecional para verificar a identidade do servidor.

A autenticação unidirecional requer um certificado SSL assinado e confiável para verificar a identidade do servidor. Você pode configurar o conector para acessar um TrustStore específico que contém o certificado apropriado. Se você não especificar um TrustStore, o conector usará o Java TrustStore padrão chamado jssecacerts. Se jssecacerts não estiver disponível, o conector usará cacerts.

Para configurar o SSL:

1. Defina a propriedade SSL como 1.
2. Se você não estiver usando um dos Java Trust Stores padrão, crie um Trust Store e configure o conector para usá-lo:
   1. Crie um Repositório de Confiança contendo seu certificado de servidor assinado e confiável.
   2. Configure a propriedade SSLTrustStore para o caminho completo do TrustStore.
   3. Defina a propriedade SSLTrustStorePwd como a senha para acessar a TrustStore.
   4. Se o TrustStore não for um JKS TrustStore, defina a propriedade SSLTrustStoreType como o tipo correto. Os tipos suportados são:
      • SSLTrustStoreType=BCFKS (BouncyCastle FIPS Keystore)
      • SSLTrustStoreType=PKCS12 (Padrões de criptografia de chave pública #12)

Em certos casos, onde você deseja alterar a estratégia de revogação de certificado, o conector fornece os seguintes parâmetros:

• A propriedade CheckCertRevocation quando definida como 0 aceitará certificados que são revogados (o valor padrão da propriedade é 1)
  • A propriedade AcceptUndeterminedRevocation quando definida como 1 aceitará certificados onde não conseguirmos identificar o status de revogação dos certificados (CRLDP está inacessível/expira etc), o valor padrão dessa propriedade é 0

Autenticar o controlador

Você pode autenticar a conexão do driver JDBC usando um dos seguintes mecanismos de autenticação:

• Autenticação OAuth de utilizador para máquina (U2M) (Recomendado)
• M2M usando identidades gerenciadas do Azure
• Token de acesso pessoal do Azure Databricks

Autenticação OAuth de utilizador para máquina (U2M)

O driver JDBC suporta autenticação OAuth user-to-machine (U2M) para login humano em tempo real e consentimento para autenticar a conta de usuário Databricks de destino. Isso também é conhecido como autenticação OAuth baseada em navegador.

O Azure Databricks criou a ID databricks-sql-jdbc do cliente OAuth para clientes. Este também é o ID de cliente OAuth padrão usado no driver JDBC. Para configurar a autenticação OAuth U2M, basta adicionar as seguintes propriedades ao URL ou java.util.Properties objeto de conexão JDBC existente:

Autenticação OAuth entre máquinas (M2M)

O driver JDBC suporta autenticação OAuth máquina-a-máquina (M2M), também conhecida como autenticação de credenciais de cliente OAuth 2.0, usando uma das seguintes entidades ou identidade. Consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.

• Uma entidade de serviço Databricks
• Uma entidade de serviço gerenciada do Azure
• Uma identidade gerenciada do Azure (atribuída pelo sistema ou atribuída pelo usuário)

M2M usando o principal de serviço gerido Databricks

Para configurar a autenticação usando um principal de serviço gerido pelo Databricks:

1. Crie um principal de serviço gerido do Databricks e atribua-o a contas e áreas de trabalho do Databricks.
2. Crie um segredo OAuth do Databricks para a entidade principal de serviço. Consulte o guia de configuração do OAuth M2M.
3. Conceda permissões de acesso a clusters e armazéns SQL.
4. Adicione as seguintes propriedades ao URL da conexão JDBC existente ou ao objeto java.util.Properties:

M2M usando o serviço gerido do Azure

Para configurar a autenticação usando um principal de serviço gerido do Azure:

1. Crie um segredo OAuth do Databricks para a entidade principal de serviço. Consulte o guia de configuração do OAuth M2M.
2. Conceda permissões de acesso a clusters e armazéns SQL.
3. Adicione as seguintes propriedades ao URL da conexão JDBC existente ou ao objeto java.util.Properties:

M2M usando identidades gerenciadas do Azure

Para configurar a autenticação usando identidades gerenciadas do Azure:

1. Configure identidades gerenciadas para seus recursos do Azure.
2. Conceda permissões de acesso a clusters e armazéns SQL.
3. Adicione as seguintes propriedades ao URL da conexão JDBC existente ou ao objeto java.util.Properties:

Token de acesso pessoal do Azure Databricks

Para autenticar a sua conexão de driver JDBC usando um token de acesso pessoal do Azure Databricks, adicione as seguintes propriedades ao URL de conexão JDBC ou ao objeto java.util.Properties: