Conectar ao Dataphin via JDBC - Dataphin: Central de Documentação do Alibaba Cloud

Pré-requisitos

O recurso OpenAPI do Dataphin está ativado.

Visão geral

Dois modos de autenticação: O driver JDBC do Dataphin oferece suporte a dois modos: Simple Mode e Proxy Mode. Para mais informações, consulte Modos de autenticação.
Resultados de execução consistentes: As instruções SQL executadas pelo driver JDBC produzem os mesmos resultados obtidos no console do Dataphin. Configurações como permissões, regras de mascaramento de dados, definições de segurança e especificações de código aplicam-se igualmente.

Limitações

Não é possível conectar-se ao Dataphin via JDBC quando o Compute Engine for Databricks, SelectDB, Doris ou Aliyun EMR Serverless Spark.
O driver JDBC encaminha o SQL pelo Dataphin para pré-processamento (tradução de SQL, mascaramento de dados) e posterior envio dos resultados. Esse processo adiciona latência em comparação à consulta direta ao Compute Engine.
O driver JDBC envia o SQL ao Dataphin via OpenAPI antes de encaminhá-lo ao Compute Engine. Avalie o volume esperado de chamadas e verifique se é necessário dimensionar o cluster do Dataphin e o Compute Engine.

Nota
Caso não consiga estimar a capacidade necessária, entre em contato com a equipe de O&M do Dataphin para uma avaliação de capacidade do seu cluster. Essa avaliação não abrange o Compute Engine.
O Dataphin não oferece suporte a controle de tráfego ou concorrência. Avalie o impacto potencial antes de usar esse recurso.

Versão do driver JDBC e link para baixar

Para obter o arquivo JAR do driver, entre em contato com a equipe de O&M do Dataphin.

Parâmetros de conexão

Nota

No Proxy Mode (AccessKey no nível da plataforma), use a instrução SET para especificar o usuário alvo.

set dp_delegation_uid = 'target_source_user_uid';
set dp_delegation_name = 'target_user_name';

Formato da URL JDBC: jdbc:dataphin://host:port/catalog?[tenant_id=TenantID][&ssl=true][&log_level=Log_Level][&user=UserName][&password=PassWord][&delegation_uid=DelegationUid][&account_type=AccountType][&connect_timeout=ConnectTimeout][&engine=engine_type][compute_project=ProjectName]

Importante

Os nomes dos parâmetros diferenciam maiúsculas de minúsculas.
Os colchetes [] indicam parâmetros opcionais. Não os inclua na URL.

Parâmetro	Obrigatório	Descrição	Exemplo
host	Sim	Nome de domínio da OpenAPI do Dataphin. Encontre esta informação em OpenAPI Invocation Address na página Personal Center > AccessKey Management.	dataphin-openapi.****.aliyun.com
port	Não	Porta `443` para HTTPS, `80` para HTTP. Padrão: 80.	80
catalog	Sim	Escopo padrão da consulta. Para consultar uma Tabela Física do Dataphin, insira o nome em inglês do projeto do Dataphin (project_name). Para consultar uma Tabela Lógica do Dataphin, insira o nome em inglês do domínio de dados do Dataphin (começa com `LD_`). Para consultar uma tabela de uma Fonte de Dados gerenciada pelo Dataphin, insira o código da Fonte de Dados configurada no Dataphin (começa com `ds_`). Nota Se o escopo padrão da consulta for um domínio de dados, compute_project é obrigatório. Se o escopo padrão da consulta for uma tabela de uma Fonte de Dados gerenciada pelo Dataphin, não é necessário especificar compute_project.	Exprojectname
tenant_id	Sim	ID do tenant.	111***111
ssl	Não	Define se o HTTPS será usado. True: Usa um Nome de Domínio HTTPS. False: Usa um Nome de Domínio HTTP. Este é o valor padrão.	False
currentschema	Não	Schema da Fonte de Dados. Este parâmetro não é necessário se o catalog apontar para uma Tabela Física ou Tabela Lógica do Dataphin. Este parâmetro não é necessário se o tipo de Fonte de Dados especificado no catalog não suportar schemas, como o MySQL. Este parâmetro é opcional se o tipo de Fonte de Dados especificado no catalog suportar schemas, como o Oracle. Ao especificar um schema, as consultas serão executadas nesse schema. Se nenhum schema for especificado, as consultas serão executadas no schema padrão do banco de dados.	information_schema
compute_project	Não	Projeto destinado à execução das consultas SQL. Este projeto e sua Fonte de Computação devem ter permissões de leitura sobre as tabelas consultadas. Se o escopo da consulta for um projeto do Dataphin, este parâmetro é opcional. O padrão é o projeto definido no catalog. Obrigatório quando o escopo da consulta for um domínio de dados. Não é necessário quando o escopo da consulta for uma Fonte de Dados.	Exprojectname
user	Sim	AccessKey ID. No Proxy Mode, use o AccessKey ID da plataforma. Para obter o AccessKey ID da plataforma, entre em contato com a equipe de O&M do Dataphin. Para obter seu AccessKey ID de usuário, acesse Personal Center > AccessKey Management.	kIBPT0
log_level	Não	Nível de log. Valores válidos: DEBUG INFO WARNING ERROR	DEBUG
password	Sim	AccessKey Secret. Para obter o AccessKey da plataforma, entre em contato com a equipe de O&M do Dataphin. Para obter seu AccessKey ID de usuário, acesse Personal Center > AccessKey Management.	Cy****r2T
delegation_uid	Não	Usuário do Dataphin a ser representado ao conectar-se com um AccessKey da plataforma. O ID do usuário deve corresponder ao account_type especificado. Definir este parâmetro ativa o Proxy Mode.	999***999
account_type	Não	Tipo de conta do usuário representado (apenas no Proxy Mode). ACCOUNT_NAME: Nome de usuário do Dataphin. Recomendado quando a aplicação e o Dataphin usam o mesmo nome de usuário. USER_ID: ID exclusivo do usuário dentro do Dataphin (geralmente não recomendado). SOURCE_USER_ID: ID do usuário no sistema de origem. Disponível quando o Dataphin está configurado com autenticação SSO (como RAM, SAML ou OAuth) e representa a conta do usuário no Provedor de Identidade (IdP). Nota Este parâmetro é obrigatório apenas quando delegation_uid estiver definido. Se não for especificado, o tipo padrão será USER_ID. A autenticação falhará caso existam usuários duplicados.	USER_ID
connect_timeout	Não	Tempo limite de conexão em segundos. Maior que 0: Define o período de tempo limite. O valor mínimo é 10s. Menor ou igual a 0: Aguarda indefinidamente.	10
engine	Não	Engine offline do projeto. Para Fontes de Computação Hadoop, o padrão é Hive; é possível definir como Impala ou Spark. A engine deve estar pré-configurada na Fonte de Computação. Valores não suportados são ignorados com um aviso. Valores válidos: MaxCompute Hologres Hive Impala Inceptor ArgoDB Spark Nota Este parâmetro é ignorado ao acessar uma Fonte de Dados.	MaxCompute
acceleration_source	Não	Código do Acceleration Source dentro do tenant.	starrocks_code
acceleration_resource_group	Não	Resource Group do Acceleration Source especificado.	starrocks_resource_group

Modos de autenticação

Simple mode

Defina username como o AccessKey ID do usuário e password como o AccessKey Secret. Gerenciar AccessKeys da OpenAPI do Dataphin.

O Dataphin autentica o AccessKey, autoriza o usuário para os recursos solicitados e executa as consultas como esse usuário.

Proxy mode

Importante

Entre em contato com a equipe de O&M do Dataphin para ativar o Proxy Mode antes de usá-lo.

O Proxy Mode destina-se a integrações no nível do sistema. Em vez de gerenciar AccessKeys individuais, um AccessKey no nível da plataforma representa usuários específicos por meio do parâmetro delegation_uid. Todas as verificações de permissão usam os privilégios do usuário representado.

Referência da API do driver Dataphin

com.aliyun.dataphin.jdbc.DataphinDriver

Interface	Descrição	Sintaxe
connect	Estabelece uma conexão com o banco de dados.	`Connection connect (String url, Properties info) throws SQLException;`
acceptsURL	Verifica se o driver pode processar uma determinada URL.	`boolean acceptsURL(String url) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinConnection

Interface

Descrição

Sintaxe

createStatement

Cria um objeto Statement.

Statement createStatement
(int resultSetType, 
int resultSetConcurrency)
throws SQLException;

prepareStatement

Cria um objeto PreparedStatement.

PreparedStatement prepareStatement(String sql, int resultSetType,int resultSetConcurrency)throws SQLExcept;
PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability);

com.aliyun.dataphin.jdbc.DataphinStatement

Interface	Descrição	Sintaxe
executeQuery	Executa uma instrução SQL e retorna um objeto `ResultSet`.	`ResultSet executeQuery (String sql) throws SQLException;`
setFetchSize	Busca dados de resultado em lotes com base no número de linhas especificado. Se não for definido ou se for definido como 0, o tamanho padrão de busca será 1.000.	`void setFetchSize(int rows) throws SQLException`
cancel	Cancela a execução do objeto `Statement`.	`void cancel() throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinPrepareStatement

Interface	Descrição	Sintaxe
executeQuery	Executa uma instrução SQL e retorna um objeto `ResultSet`.	`ResultSet executeQuery (String sql) throws SQLException;`

com.aliyun.dataphin.jdbc.DataphinResultSetMetaData

Interface	Descrição	Sintaxe
getColumnCount	Obtém o número de colunas no schema do resultado.	`int getColumnCount() throws SQLException;`
getColumnName	Obtém o nome de uma coluna no schema do resultado.	`String getColumnName(int column) throws SQLException;`

com.aliyun.dataphin.jdbc.ResultSet

Interface	Descrição	Sintaxe
next	Recupera os resultados da consulta SQL linha por linha.	`boolean next() throws SQLException;`

com.aliyun.dataphin.jdbc.DatabaseMetaData

Interface

Descrição

Sintaxe

getTables

Recupera metadados de tabelas.

Parâmetros:
- catalog: O padrão é default.
- schemaPattern: Nome do projeto ou nome do domínio de dados.
- tableNamePattern: Nome da tabela. Há suporte para correspondência com curingas, mas não para expressões regulares.
- types: Atualmente, não há suporte para este parâmetro.
Resultados:
- Retorna um objeto ResultSet.
- Use o método next() para recuperar resultados linha por linha. Cada linha contém os metadados de uma única tabela (apenas o nome da tabela é suportado).
Obter nome da tabela:
- resultSet.getString("table_name")

ResultSet getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) throws SQLException

getColumns

Recupera metadados de colunas de uma tabela.

Parâmetros:
- catalog: Nome do projeto ou nome do domínio de dados.
- schemaPattern: Atualmente, não há suporte para este parâmetro.
- tableNamePattern: Nome completo da tabela. Não há suporte para correspondência com curingas nem expressões regulares.
- columnNamePattern: Atualmente, não há suporte para este parâmetro.
Resultados:
- Retorna um objeto ResultSet.
- Use o método next() para recuperar resultados linha por linha. Cada linha contém os metadados de uma coluna da tabela (apenas nome da coluna e tipo de dados são suportados).
Obter nome da coluna: resultSet.getString("column_name").
Obter tipo de dados da coluna: resultSet.getString("data_type").

ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern)

Exemplos

Recupere informações do catálogo por meio do driver JDBC.

1. Obter uma lista de tabelas

Lista Tabelas Físicas e Visualizações Físicas em um projeto.

Sintaxe

SHOW TABLES
    [FROM db_name]
    [LIKE 'pattern']

Parâmetros

db_name:

Nome do projeto Dataphin: Lista as Tabelas Físicas neste projeto.
Para projetos de desenvolvimento e domínios de dados, adicione explicitamente o sufixo _Dev.
Se db_name não for especificado, as tabelas no project_name definido na URL serão listadas por padrão.

Resultados

Nome	Tipo	Comentário
dim_user	Tabela Lógica	Tabela de usuários.
ods_user	Tabela Física	Tabela de origem de usuários.
ods_user_logical_view	Visualização Lógica	Visualização lógica.
ods_user_physical_view2	Visualização Física	Visualização física.

2. Obter a estrutura de uma tabela

Obtém os detalhes dos campos de uma Tabela Física ou Visualização Física.

Sintaxe

{DESCRIBE | DESC} table_name;

Nota

Apenas Tabelas Físicas e Visualizações Físicas são suportadas.

Parâmetros

table_name: Nome da Tabela Física ou Visualização Física.

Resultados

Nome	Tipo	Comentário
ID	BigInt	ID do usuário.
Name	String	Nome do usuário.
DS	String	Tempo da partição.

Controle de conexão no lado do servidor

Máximo de conexões: 100 (padrão).
Tempo limite de conexão: 288.000s (80 horas). Conexões ociosas são encerradas após esse período.

Informações de tarefas JDBC no MaxCompute

Quando uma tarefa JDBC é enviada ao MaxCompute, o Dataphin transmite os seguintes metadados para a instância.

Parâmetro	Descrição
logical_project	Nome do projeto do Dataphin onde a tarefa JDBC é executada.
EXT_JDBC_TASKRUN_ID	ID da tarefa JDBC.
EXT_DPN_TENANT_ID	ID do tenant do Dataphin onde a tarefa JDBC é executada.
EXT_PLATFORM_ID	ID da plataforma superior que enviou a tarefa ao MaxCompute. O padrão é Dataphin.
biz_id	ID de membro do Dataphin do usuário que executou a tarefa JDBC.
odps.idata.userenv	Informações do ambiente do usuário, incluindo revisão do SDK Java, versão do Java, endereço IP e endereço MAC do dispositivo. Exemplo: `JavaSDK Revision:fcedc4d,Version:0.37.6,JavaVersion:1.8.0_152,IP:11...,MAC:00----*-25`.

Essas informações podem ser usadas para análise de faturamento e rastreamento de execução de jobs. Coletar estatísticas sobre contas de custo TOP N e jobs demorados.