Configurar uma conexão

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

Configurar a URL de Conexão

Para se conectar ao workspace do Azure Databricks usando o driver JDBC, você precisa especificar uma URL de conexão JDBC que inclua várias configurações de conexão, como o nome do 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.

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

1. Faça logon 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 logon no workspace do Azure Databricks.
2. Na barra lateral, clique em SQL Warehousese, em seguida, clique no nome do armazém de destino.
3. Clique na guia Detalhes da conexão.
4. Copie o URL JDBC para usar como a URL de conexão JDBC ou construa a URL a partir de valores nos campos Nome do host do servidor , Porta , e de 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 OAuth de usuário para máquina (U2M) (Recomendado)
• Autenticação OAuth máquina a máquina (M2M)
• Token de acesso pessoal do Azure Databricks

Autenticação de usuário para máquina (U2M) 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:

Autenticação OAuth máquina a máquina (M2M)

O driver JDBC dá suporte à autenticação OAuth M2M (máquina a máquina) usando uma entidade de serviço do Azure Databricks. Isso também é conhecido como autenticação de credenciais de cliente do OAuth 2.0 . Consulte Autorizar o acesso não assistido aos recursos do Azure Databricks com uma entidade de serviço usando o OAuth.

Para configurar a autenticação de credenciais do cliente OAuth M2M ou OAuth 2.0:

1. Crie uma entidade de serviço gerenciada do Microsoft Entra ID e, em seguida, atribua-a a contas e workspaces do Azure Databricks. Para obter detalhes, confira Gerenciar entidades de serviço.

   Importante

   O Driver JDBC do Databricks (OSS) dá suporte aos segredos OAuth do Azure Databricks para autenticação de credenciais de cliente OAuth M2M ou OAuth 2.0. Não há suporte para segredos do Microsoft Entra ID.

2. Crie um segredo OAuth do Azure Databricks para a entidade de serviço. Para fazer isso, confira Gerar e usar manualmente tokens de acesso para autenticação da entidade de serviço do OAuth.

3. Conceda à entidade de serviço acesso ao cluster ou ao warehouse. Consulte Permissões de computação ou Gerenciar um SQL warehouse.

Adicione as seguintes propriedades à URL de conexão JDBC existente ou objeto java.util.Properties:

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