MaxCompute:Conecte-se ao MaxCompute com o odpscmd

Pré-requisitos

• O cliente MaxCompute requer Java 8 ou superior.

• Compatibilidade de versões

  • O cliente MaxCompute v0.28.0 e posterior oferece suporte ao JDK 1.9 e versões mais recentes. As versões anteriores à v0.28.0 suportam apenas o JDK 1.8. Após iniciar o cliente MaxCompute, visualize a versão do cliente na interface de linha de comando.

  • O formato de saída do cliente MaxCompute não possui compatibilidade retroativa. Os formatos de comando e o comportamento podem variar entre as versões do cliente. Não utilize o formato de saída do cliente para análise sintática (parsing).

  • Para outras versões do cliente, consulte aliyun-odps-console.

• Codificação de caracteres

  O cliente utiliza UTF-8 por padrão. Caso a codificação de caracteres do seu ambiente local não seja UTF-8, poderão surgir caracteres ilegíveis ao consultar dados com caracteres chineses em uma tabela do MaxCompute ou ao usar um comando Tunnel para fazer upload de arquivos locais que os contenham.

Faturamento

A utilização do cliente MaxCompute para conectar-se a um projeto é gratuita, mas as operações realizadas por meio do cliente estão sujeitas ao faturamento do MaxCompute. Por exemplo, enviar uma consulta SQL consome recursos de computação, e a gravação de dados utiliza espaço de armazenamento, resultando em custos de computação e armazenamento. Para obter mais informações sobre o faturamento do MaxCompute, consulte Itens faturáveis e métodos de faturamento.

Instale e configure o odpscmd

O odpscmd v0.27.0 e versões posteriores oferecem suporte aos tipos de dados do MaxCompute 2.0. Recomendamos o uso desses tipos de dados. Para obter uma lista dos tipos de dados suportados, consulte Tipos de dados (V2.0).

Procedimento

1. Baixe o pacote de instalação do odpscmd (GitHub).

   Nota

   • Acesse a página de lançamento e baixe a versão mais recente do pacote de instalação do odpscmd (odpscmd_public.zip).

   • Caso não consiga baixar o pacote pelo link do GitHub, tente baixar o pacote de instalação do odpscmd (OSS). Se tiver problemas para acessar o GitHub, recomendamos buscar soluções online.

2. Descompacte o pacote baixado. O diretório extraído contém as pastas bin, conf, lib e plugins.

3. Acesse a pasta conf e configure o arquivo odps_config.ini.

   No arquivo odps_config.ini, o sinal de cerquilha (#) indica um comentário. A tabela a seguir descreve os parâmetros.

   Parâmetro	Obrigatório	Descrição	Exemplo
   project_name	Sim	Nome do projeto MaxCompute de destino. Se você criou um workspace no modo padrão, diferencie os nomes dos projetos para o ambiente de produção e o ambiente de desenvolvimento (_dev) ao configurar o parâmetro project_name. Para mais informações, consulte Diferenças entre modos de workspace. Faça login no MaxCompute console e selecione uma região no canto superior esquerdo. No painel de navegação à esquerda, escolha Manage Configurations > Projects. Na página Projects, visualize o nome do seu projeto MaxCompute.	doc_test_dev
   access_id	Sim	AccessKey ID da sua conta Alibaba Cloud ou usuário RAM. Obtenha o AccessKey ID na página AccessKey Management.	N/A
   access_key	Sim	AccessKey Secret correspondente ao AccessKey ID.	N/A
   end_point	Sim	Endpoint do serviço MaxCompute. Configure o endpoint com base na região onde seu projeto MaxCompute está localizado e no tipo de conexão de rede. Para obter uma lista de endpoints para diferentes regiões e tipos de rede, consulte Endpoints. Importante Um endpoint conecta-se ao serviço MaxCompute, enquanto um tunnel endpoint conecta-se ao serviço MaxCompute Tunnel. Especifique aqui o endpoint para o serviço MaxCompute. Uma configuração incorreta de endpoint causa erro de acesso.	http://service.cn-hangzhou.maxcompute.aliyun.com/api
   log_view_host	Não	URL do LogView. Recomendamos configurar este parâmetro. Sem essa configuração, não será possível identificar rapidamente a causa de uma falha de job. Use esta URL para visualizar informações detalhadas sobre a execução do job e solucionar erros. O valor fixo é http://logview.odps.aliyun.com.	http://logview.odps.aliyun.com
   https_check	Não	Define se o HTTPS deve ser ativado para criptografar requisições de acesso ao projeto MaxCompute. Valores válidos: True: Ativa o HTTPS. False: Utiliza HTTP. O valor padrão é False.	True
   data_size_confirm	Não	Tamanho máximo dos dados de entrada em GB. Este valor não possui limite superior. Valor recomendado: 100.	100
   update_url	Não	Parâmetro reservado para uso futuro.	N/A
   use_instance_tunnel	Não	Define se o InstanceTunnel deve ser usado para baixar resultados de execução SQL. Valores válidos: True: Usa o InstanceTunnel para baixar resultados de execução SQL. False: Não usa o InstanceTunnel para baixar resultados de execução SQL. O valor padrão é False.	True
   instance_tunnel_max_record	Não	Número máximo de registros em um resultado de execução SQL. Se use_instance_tunnel estiver definido como True, configure este parâmetro. O valor máximo é 10.000.	10.000
   tunnel_endpoint	Não	Endpoint público para o serviço Tunnel. Se você não configurar este parâmetro, o Tunnel roteará automaticamente as requisições para o tunnel endpoint correspondente à rede do serviço MaxCompute. Se configurar um tunnel endpoint, o Tunnel usará esse valor e não realizará o roteamento automático. Para obter uma lista de tunnel endpoints para diferentes regiões e tipos de rede, consulte Endpoints.	http://dt.cn-hangzhou.maxcompute.aliyun.com
   set.<key>	Não	Define uma propriedade para o projeto MaxCompute. Para mais informações sobre propriedades, consulte a lista de propriedades.	set.odps.sql.decimal.odps2=true

   Certifique-se de que as informações acima estejam configuradas corretamente. Configurações incorretas podem causar falhas na conexão com o projeto.

Inicie o cliente MaxCompute

1. Crie um projeto MaxCompute.

2. Se utilizar o cliente MaxCompute como um usuário RAM, use sua conta Alibaba Cloud para adicionar o usuário RAM ao projeto MaxCompute de destino. Para mais informações sobre como adicionar usuários, consulte Conceder permissões a outros usuários.

3. Utilize um dos métodos a seguir para iniciar o cliente MaxCompute:

   Script file

   No diretório bin da instalação do seu cliente MaxCompute, clique duas vezes em odpscmd.bat (no Windows) ou odpscmd (no macOS) para iniciar o cliente MaxCompute. A saída a seguir indica uma conexão bem-sucedida com o projeto MaxCompute.

   odpscmd
   Aliyun ODPS Command Line Tool
   Version 0.4xxx
   @Copyright 2020 Alibaba Cloud Computing Co., Ltd. All rights reserved.
   Connecting to http://service.xxx.maxcompute.aliyun.com/api, project: xxx
   Executing predefined SET command: SET odps.sql.hive.compatible=true
   OK
   Endpoint: http://service.xxx.maxcompute.aliyun.com/api
   Project: xxx
   Schema: default
   Quota: default in region N/A
   Timezone: Asia/Shanghai
   Connected!

   Command-line window

   Em uma janela de linha de comando, acesse o diretório bin da instalação do seu cliente MaxCompute. Execute odpscmd no Windows ou sh odpscmd no Linux ou macOS para iniciar o cliente MaxCompute. Uma mensagem de sucesso indica que o cliente se conectou ao projeto MaxCompute.

   Nota

   No Ubuntu, sh odpscmd retorna um erro. Use ./odpscmd em vez disso.

   Ao iniciar o cliente MaxCompute a partir de uma janela de linha de comando, especifique parâmetros de inicialização para executar comandos. Para mais informações, consulte Parâmetros de inicialização.

Operações do cliente MaxCompute

...\odpscmd\bin>odpscmd -h

odps@project_name>whoami;

odps@project_name>quit;
-- The following command is equivalent.
odps@project_name>q;

Documentos relacionados

Após fazer login no cliente MaxCompute, execute comandos SQL em um projeto MaxCompute. Para mais informações, consulte Usar o cliente MaxCompute.

Para detalhes sobre a sintaxe de comandos do cliente MaxCompute, consulte Referência de comandos ou Comandos e funções SQL.

FAQ

Após configurar o arquivo odps_config.ini e iniciar o cliente MaxCompute, você poderá encontrar os seguintes erros comuns:

Parâmetros de inicialização

Usage: odpscmd [OPTION]...
where options include:
    --help                                  (-h)for help
    --config=<config_file>                  specify another config file
    --project=<prj_name>                    use project
    --endpoint=<http://host:port>           set endpoint
    -k <n>                                  will skip begining queries and start from specified position
    -r <n>                                  set retry times
    -f <"file_path;">                       execute command in file
    -e <"command;[command;]...">            execute command, include sql command

Na linha de comando shell ou Windows, use odpscmd -e <SQL_statement> para capturar valores de retorno dinâmicos em uma variável shell para jobs subsequentes. Nesse cenário, o valor de retorno não deve conter informações extras, como detalhes de tempo de execução ou cabeçalho. Para facilitar o scripting em shell, defina o parâmetro use_instance_tunnel no arquivo odps_config.ini como false para desativar o Instance Tunnel. Em seguida, execute o comando set odps.sql.select.output.format={"needHeader":false,"fieldDelim":" "}; para suprimir o cabeçalho.

--Windows command line:
...\odpscmd\bin>odpscmd -e "set odps.sql.select.output.format={""needHeader"":false,""fieldDelim"":"" ""};select * from noheader;" >D:\test.txt
--The result is saved to D:\test.txt.
--Shell:
/Users/.../odpscmd/bin/odpscmd -e "set odps.sql.select.output.format={\"needHeader\":false,\"fieldDelim\":\"\"};select * from noheader;" >/Users/A/temp/test.txt 
--The result is saved to /Users/A/temp/test.txt.
--Output:
1
2
3

Histórico de versões

A tabela a seguir descreve atualizações recentes do odpscmd. Para mais detalhes, clique no link de uma versão específica.

Para obter uma lista completa de versões do odpscmd e notas de lançamento, consulte o GitHub.