Compartilhar via

Configurar uma conexão com o Databricks usando o Driver JDBC (OSS) do Databricks

Este artigo mostra como configurar uma conexão com o Databricks usando o Driver JDBC do Databricks (OSS).

Configurar a conexão

Para se conectar ao workspace 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 workspace do Azure Databricks, as configurações de recurso de computação e as credenciais de autenticação para se conectar ao workspace.

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 ambas. Consulte a documentação do provedor para obter a melhor maneira de se conectar usando seu aplicativo, cliente, SDK, API ou ferramenta SQL específico.

A URL de conexão JDBC deve estar no formato a seguir. As propriedades não diferenciam maiúsculas de minúsculas.

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

Como alternativa, especifique as configurações usando a classe java.util.Properties 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 do SQL e propriedades de log, consulte propriedades de conexão suportadas.

Observação

Elementos e propriedades de URL são insensíveis a maiúsculas e minúsculas.

Elemento ou propriedade de URL Descrição
<server-hostname> O valor do nome do host do servidor do recurso de computação do Azure Databricks.
<port> O valor da porta do recurso de computação do Azure Databricks. O valor padrão é 443.
<schema> O nome do esquema. Como alternativa, você pode definir a propriedade ConnSchema. Consulte Propriedades de conexão com suporte.
httpPath O valor do caminho HTTP do recurso de computação do Azure Databricks. O conector forma o endereço HTTP ao qual se conectar acrescentando o valor httpPath ao host e à porta especificados na URL de conexão. Por exemplo, para se conectar ao endereço HTTP http://localhost:10002/cliservice, você usaria a seguinte URL de conexão: jdbc:databricks://localhost:10002;httpPath=cliservice

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

  1. Faça login no workspace 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 a URL JDBC para usar como a URL de conexão JDBC ou construa a URL a partir dos valores nos campos Nome do host do servidor, Portae Caminho HTTP.

Para obter a URL de conexão JDBC para um warehouse do Databricks SQL:

  1. Faça login no workspace do Azure Databricks.
  2. Na barra lateral, clique em SQL Warehouses e, em seguida, clique no nome do warehouse de destino.
  3. Clique na guia Detalhes da conexão.
  4. Copie a URL JDBC para usar como a URL de conexão JDBC ou construa a URL a partir dos valores nos campos Nome do host do servidor, Portae Caminho HTTP.

Configurar conexões de proxy

Você pode configurar o conector para se conectar por meio de um servidor proxy em vez de se conectar diretamente ao Databricks. Ao se conectar por meio de um servidor proxy, o conector dá suporte à autenticação básica e SPNEGO.

Para configurar uma conexão proxy:

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

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

Configurando o SSL

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

A autenticação unidirecional requer um certificado SSL confiável e assinado 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 os jssecacerts não estiverem disponíveis, o conector usará cacerts.

Para configurar o SSL:

  1. Defina a propriedade SSL como 1.
  2. Se você não estiver usando um dos Repositórios de Confiança Java padrão, crie um Repositório de Confiança e configure o conector para usá-lo:
    1. Crie um Repositório de Confiança que contenha seu certificado de servidor confiável e assinado.
    2. Defina a propriedade SSLTrustStore como o caminho completo do TrustStore.
    3. Defina a propriedade SSLTrustStorePwd como a senha para acessar o TrustStore.
    4. Se o TrustStore não for um TrustStore do JKS, defina a propriedade SSLTrustStoreType como o tipo correto. Os tipos com suporte são:
      • SSLTrustStoreType=BCFKS (BouncyCastle FIPS Keystore)
      • SSLTrustStoreType=PKCS12 (Public Key Cryptography Standards #12)

Em determinados casos, em que 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 revogados (o valor padrão da propriedade é 1)
    • A propriedade AcceptUndeterminedRevocation, quando definida como 1, aceitará certificados cujo status de revogação não pode ser identificado (quando o CRLDP está inacessível, expira, etc.). O valor padrão dessa propriedade é 0.

Autenticar o driver

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

Autenticação U2M (usuário para computador) do OAuth

O driver JDBC oferece suporte à autenticação de usuário para máquina (U2M) do OAuth para o login humano em tempo real e consentimento para autenticar a conta de usuário alvo do Databricks. Isso também é conhecido como autenticação OAuthbaseada em navegador.

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

Propriedade Valor
AuthMech 11
Auth_Flow 2
TokenCachePassPhrase A frase secreta usada para criptografar suas credenciais OAuth U2M armazenadas em cache. Isso impede autenticações repetidas baseadas em navegador. Para recusar o cache de token, defina EnableTokenCache como 0.

Autenticação M2M (de computador para computador) do OAuth

O driver JDBC dá suporte à autenticação M2M (máquina a máquina) OAuth, também conhecida como autenticação de credenciais de cliente OAuth 2.0, usando um dos seguintes princípios ou identidades. Veja Autorizar acesso não supervisionado aos recursos do Azure Databricks com uma entidade de serviço usando OAuth.

M2M usando entidade de serviço gerenciada pelo Databricks

Para configurar a autenticação usando uma entidade de serviço gerenciada pelo Databricks:

  1. Crie uma entidade de serviço gerenciada pelo Databricks e atribua-a a contas e workspaces do Databricks.
  2. Crie um segredo OAuth do Databricks para a entidade de serviço. Consulte o guia de instalação do OAuth M2M.
  3. Conceda permissões de acesso a clusters e sql warehouses.
  4. Adicione as seguintes propriedades à URL de conexão JDBC existente ou objeto java.util.Properties:
Propriedade Valor
AuthMech 11
Auth_Flow 1
OAuth2ClientID O valor do ID do Aplicativo (cliente) principal do serviço.
OAuth2Secret O segredo do OAuth do Azure Databricks da entidade de serviço.

M2M usando a entidade de serviço gerenciada do Azure

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

  1. Crie um segredo OAuth do Databricks para a entidade de serviço. Consulte o guia de instalação do OAuth M2M.
  2. Conceda permissões de acesso a clusters e sql warehouses.
  3. Adicione as seguintes propriedades à URL de conexão JDBC existente ou objeto java.util.Properties:
Propriedade Valor
AuthMech 11
Auth_Flow 1
OAuth2ClientID O valor do ID do Aplicativo (cliente) principal do serviço.
AzureTenantID O ID do locatário do Azure encontrado no Azure Active Directory.
OAuth2Secret O segredo do OAuth do Azure Databricks da entidade de serviço.

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 sql warehouses.
  3. Adicione as seguintes propriedades à URL de conexão JDBC existente ou objeto java.util.Properties:
Propriedade Valor
AuthMech 11
Auth_Flow 3
OAuth2ClientID A ID do cliente da identidade gerenciada. Esse é um parâmetro necessário somente se você estiver usando uma identidade gerenciada atribuída pelo usuário.
Azure_workspace_resource_id ID do recurso do Azure do seu espaço de trabalho do Databricks

Token de acesso pessoal do Azure Databricks

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

Propriedade Valor
AuthMech 3
user O valor token, como uma cadeia de caracteres.
PWD ou password O valor do token de acesso pessoal do Azure Databricks, como uma cadeia de caracteres.