Executar e testar U-SQL com o SDK do U-SQL do Azure Data Lake
Importante
O Azure Data Lake Analytics desativado em 29 de fevereiro de 2024. Saiba mais nesse comunicado.
Para análise de dados, sua organização pode usar o Azure Synapse Analytics ou o Microsoft Fabric.
Ao desenvolver o script U-SQL, é comum executar e testar o script U-SQL localmente antes de enviá-lo para a nuvem. O Azure Data Lake fornece um pacote NuGet chamado SDK do U-SQL do Azure Data Lake para esse cenário, por meio do qual você pode dimensionar facilmente a execução e o teste do U-SQL. Também é possível integrar esse teste do U-SQL ao sistema de CI (Integração Contínua) para automatizar a compilação e o teste.
Se você se preocupa em como executar e depurar o script U-SQL no local manualmente com ferramentas de GUI, é possível usar as Ferramentas do Azure Data Lake para Visual Studio para essa finalidade. Saiba mais aqui.
Instalar o SDK do U-SQL do Azure Data Lake
Você pode obter o SDK do U-SQL do Azure Data Lake aqui em NuGet.org. Antes de usá-lo, você precisa verificar se tem dependências da maneira a seguir.
Dependências
O SDK para U-SQL do Data Lake exige as seguintes dependências:
Microsoft Visual C++ 14 e SDK do Windows 10.0.10240.0 ou mais novo (que é chamado CppSDK neste artigo). Há duas maneiras de obter o CppSDK:
Instalar o Visual Studio Community Edition. Você terá uma pasta \Windows Kits\10 na pasta Arquivos de Programa – por exemplo, C:\Program Files (x86) \Windows Kits\10. Você também encontrará a versão do SDK do Windows 10 em \Windows Kits\10\Lib. Se você não vir essas pastas, reinstale o Visual Studio e selecione o SDK do Windows 10 durante a instalação. Se você tiver isso instalado com o Visual Studio, o compilador local do U-SQL o encontrará automaticamente.
Instalar Ferramentas do Data Lake para Visual Studio. Você pode encontrar os arquivos predefinidos do SDK do Windows e do Visual C++ em
C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.Nesse caso, o compilador local do U-SQL não consegue localizar as dependências automaticamente. Você precisa especificar o caminho CppSDK para ele. Você pode copiar os arquivos para outro local ou usá-los como estão.
Entender os conceitos básicos
Raiz de dados
A pasta raiz de dados é um "repositório local" para a conta de computador local. Ela equivale à conta do Azure Data Lake Store de uma conta do Data Lake Analytics. Alternar para uma pasta raiz de dados diferente é como alternar para uma conta de repositório diferente. Se você quiser acessar dados compartilhados normalmente com pastas raiz de dados diferentes, deverá usar caminhos absolutos em seus scripts. Ou criar links simbólicos de sistema de arquivo (por exemplo, mklink em NTFS) na pasta raiz de dados para apontar para os dados compartilhados.
A pasta raiz de dados é usada para:
- Armazenar metadados locais, incluindo bancos de dados, tabelas, TVFs (funções com valor de tabela) e assemblies.
- Pesquisar os caminhos de entrada e saída que são definidos como caminhos relativos no U-SQL. Usar caminhos relativos facilita a implantação dos projetos U-SQL no Azure.
Caminho de arquivo no U-SQL
Você pode usar um caminho relativo e um caminho absoluto local em scripts U-SQL. O caminho relativo é relativo ao caminho da pasta raiz de dados especificado. Recomendamos que você use "/" como o separador de caminho para tornar seus scripts compatíveis com o lado do servidor. A seguir, alguns exemplos de caminhos relativos e os respectivos caminhos absolutos equivalentes. Nesses exemplos, C:\LocalRunDataRoot é a pasta raiz de dados.
| Caminho relativo | Caminho absoluto |
|---|---|
| /abc/def/input.csv | C:\LocalRunDataRoot\abc\def\input.csv |
| abc/def/input.csv | C:\LocalRunDataRoot\abc\def\input.csv |
| D:/abc/def/input.csv | D:\abc\def\input.csv |
Diretório de trabalho
Ao executar o script U-SQL localmente, um diretório de trabalho é criado durante a compilação no diretório de execução atual. Além das saídas de compilação, os arquivos de runtime necessários para execução local são copiados em sombra para esse diretório de trabalho. A pasta raiz do diretório de trabalho é chamada “ScopeWorkDir” e os arquivos no diretório de trabalho são os seguintes:
| Diretório/arquivo | Diretório/arquivo | Diretório/arquivo | Definição | Descrição |
|---|---|---|---|---|
| C6A101DDCB470506 | Cadeia de caracteres de hash da versão do runtime | Cópia de sombra dos arquivos de runtime necessários para execução local | ||
| Script_66AE4909AA0ED06C | Nome do script + cadeia de caracteres de hash do caminho do script | Saídas da compilação e log das etapas de execução | ||
| _script_.abr | Saída do compilador | Arquivo de álgebra | ||
| _ScopeCodeGen_.* | Saída do compilador | Código gerenciado gerado | ||
| _ScopeCodeGenEngine_.* | Saída do compilador | Código nativo gerado | ||
| assemblies referenciados | Referência de assembly | Arquivos de assembly referenciado | ||
| deployed_resources | Implantação de recursos | Arquivos da implantação de recursos | ||
| xxxxxxxx.xxx[1..n]_*.* | Log de execução | Log das etapas de execução |
Usar o SDK da linha de comando
Interface de linha de comando do aplicativo auxiliar
Em directory\build\runtime do SDK, LocalRunHelper.exe é o aplicativo auxiliar de linha de comando que fornece interfaces para a maioria das funções de execução local frequentemente usadas. As opções de comando e argumento diferenciam maiúsculas de minúsculas. Para invocá-lo:
LocalRunHelper.exe <command> <Required-Command-Arguments> [Optional-Command-Arguments]
Execute LocalRunHelper.exe sem argumentos ou com a opção help para mostrar as informações de ajuda:
> LocalRunHelper.exe help
Command 'help' : Show usage information
Command 'compile' : Compile the script
Required Arguments :
-Script param
Script File Path
Optional Arguments :
-Shallow [default value 'False']
Shallow compile
Nas informações de ajuda:
- Command fornece o nome do comando.
- Required Argument lista argumentos que devem ser fornecidos.
- Optional Argument lista argumentos que são opcionais e com valores padrão. Os argumentos boolianos opcionais não têm parâmetros e as respectivas aparências são negativas para o respectivo valor padrão.
Valor de retorno e registro em log
O aplicativo auxiliar retorna 0 em caso de sucesso e -1 em caso de falha. Por padrão, o auxiliar enviará todas as mensagens para o console atual. No entanto, a maioria dos comandos dá suporte ao argumento opcional -MessageOut path_to_log_file, que redireciona as saídas para um arquivo de log.
Configurando variáveis de ambiente
A execução local do U-SQL precisa de uma raiz de dados especificada como conta de armazenamento local e um caminho CppSDK especificado para dependências. É possível definir o argumento na linha de comando ou definir a variável de ambiente para elas.
Defina a variável de ambiente SCOPE_CPP_SDK.
Se obtiver o SDK do Windows e Microsoft Visual C++ instalando as Ferramentas do Data Lake para Visual Studio, verifique se você tem a seguinte pasta:
C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\Microsoft Azure Data Lake Tools for Visual Studio 2015\X.X.XXXX.X\CppSDKDefina uma nova variável de ambiente chamada SCOPE_CPP_SDK para pontar para esse diretório. Ou copie a pasta para outro local e especifique SCOPE_CPP_SDK dessa forma.
Além de definir a variável de ambiente, você também pode especificar o argumento -CppSDK ao usar a linha de comando. Esse argumento substitui a variável de ambiente CppSDK padrão.
Defina a variável de ambiente LOCALRUN_DATAROOT.
Defina uma nova variável de ambiente chamada LOCALRUN_DATAROOT que aponta para a raiz de dados.
Além de definir a variável de ambiente, você pode especificar o argumento -DataRoot com o caminho raiz de dados ao usar a linha de comando. Esse argumento substitui a variável de ambiente de raiz de dados padrão. Você precisa adicionar esse argumento para cada linha de comando em execução para que você possa substituir a variável de ambiente de raiz de dados padrão em todas as operações.
Amostras de uso da linha de comando do SDK
Compilar e executar
O comando run é usado para compilar o script e executar resultados compilados. Seus argumentos de linha de comando são uma combinação dos argumentos de compile e execute.
LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]
Estes são os argumentos opcionais para run:
| Argumento | Valor padrão | Descrição |
|---|---|---|
| -CodeBehind | Falso | O script tem o code-behind .cs |
| -CppSDK | Diretório do CppSDK | |
| -DataRoot | Variável de ambiente DataRoot | DataRoot para execução local, padrão para a variável de ambiente “LOCALRUN_DATAROOT” |
| -MessageOut | Mensagens de despejo no console para um arquivo | |
| -Parallel | 1 | Executar o plano com o paralelismo especificado |
| -References | Lista de caminhos para os assemblies de referência extra ou arquivos de dados do code-behind, separados por ';' | |
| -UdoRedirect | Falso | Gerar configuração de redirecionamento de assembly UDO |
| -UseDatabase | master | Banco de dados a ser usado para registro do assembly temporário do code-behind |
| -Verbose | Falso | Mostrar saídas detalhadas do runtime |
| -WorkDir | Diretório atual | Diretório para uso do compilador e saídas |
| -RunScopeCEP | 0 | Modo ScopeCEP a ser usado |
| -ScopeCEPTempPath | temp | Caminho temporário a ser usado para transmissão de dados |
| -OptFlags | Lista separada por vírgula de sinalizadores do otimizador |
Veja um exemplo:
LocalRunHelper run -Script d:\test\test1.usql -WorkDir d:\test\bin -CodeBehind -References "d:\asm\ref1.dll;d:\asm\ref2.dll" -UseDatabase testDB –Parallel 5 -Verbose
Além de combinar compile e execute, é possível compilar e executar os executáveis compilados separadamente.
Compilar um script U-SQL
O comando compile é usado para compilar um script U-SQL para executáveis.
LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]
Estes são os argumentos opcionais para compile:
| Argumento | Descrição |
|---|---|
| -CodeBehind [valor padrão 'False'] | O script tem o code-behind .cs |
| -CppSDK [valor padrão ''] | Diretório do CppSDK |
| -DataRoot [valor padrão “variável de ambiente DataRoot”] | DataRoot para execução local, padrão para a variável de ambiente “LOCALRUN_DATAROOT” |
| -MessageOut [valor padrão ''] | Mensagens de despejo no console para um arquivo |
| -References [valor padrão ''] | Lista de caminhos para os assemblies de referência extra ou arquivos de dados do code-behind, separados por ';' |
| -Shallow [valor padrão 'False'] | Compilação superficial |
| -UdoRedirect [valor padrão 'False'] | Gerar configuração de redirecionamento de assembly UDO |
| -UseDatabase [valor padrão 'master'] | Banco de dados a ser usado para registro do assembly temporário do code-behind |
| -WorkDir [valor padrão “Diretório Atual”] | Diretório para uso do compilador e saídas |
| -RunScopeCEP [valor padrão “0”] | Modo ScopeCEP a ser usado |
| -ScopeCEPTempPath [valor padrão “temp”] | Caminho temporário a ser usado para transmissão de dados |
| -OptFlags [valor padrão ''] | Lista separada por vírgula de sinalizadores do otimizador |
Veja alguns exemplos de uso.
Compilar um script U-SQL:
LocalRunHelper compile -Script d:\test\test1.usql
Compilar um script U-SQL e definir a pasta raiz de dados. Isso substituirá a variável de ambiente set.
LocalRunHelper compile -Script d:\test\test1.usql –DataRoot c:\DataRoot
Compilar um script U-SQL e definir um diretório de trabalho, o assembly de referência e o banco de dados:
LocalRunHelper compile -Script d:\test\test1.usql -WorkDir d:\test\bin -References "d:\asm\ref1.dll;d:\asm\ref2.dll" -UseDatabase testDB
Executar resultados compilados
O comando execute é usado para executar os resultados compilados.
LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]
Estes são os argumentos opcionais para execute:
| Argumento | Valor padrão | Descrição |
|---|---|---|
| -DataRoot | '' | Raiz de dados para a execução de metadados. A variável de ambiente LOCALRUN_DATAROOT passa a ser o padrão. |
| -MessageOut | '' | Despeje as mensagens do console em um arquivo. |
| -Parallel | '1' | Indicador para executar as etapas de execução local geradas com o nível de paralelismo especificado. |
| -Verbose | 'False' | Indicador para mostrar saídas detalhadas do runtime. |
Aqui está um exemplo de uso:
LocalRunHelper execute -Algebra d:\test\workdir\C6A101DDCB470506\Script_66AE4909AA0ED06C\__script__.abr –DataRoot c:\DataRoot –Parallel 5
Usar o SDK com interfaces de programação
As interfaces de programação estão localizadas no LocalRunHelper.exe. Você pode usá-los para integrar a funcionalidade do SDK para U-SQL e a estrutura de teste C# a fim de dimensionar o teste local do script U-SQL. Neste artigo, usarei o projeto de teste de unidade C# padrão para mostrar como usar essas interfaces para testar o script U-SQL.
Etapa 1: Criar o projeto de teste de unidade do C# e a configuração
Crie um projeto de teste de unidade do C# por meio de Arquivo > Novo > Projeto > Visual C# > Teste > Projeto de Teste de Unidade.
Adicione LocalRunHelper.exe como uma referência do projeto. O LocalRunHelper.exe está localizado em \build\runtime\LocalRunHelper.exe no pacote NuGet.
O SDK do U-SQL dá suporte apenas ao ambiente x64, certifique-se de definir o destino da plataforma de build como x64. É possível definir isso por meio de Propriedade do Projeto > Build > Destino da plataforma.
Lembre-se de definir o ambiente de teste como x64. No Visual Studio, é possível defini-lo por meio de Teste > Configurações do Teste > Arquitetura do Processador Padrão > x64.
Copie todos os arquivos de dependência em NugetPackage\build\runtime\ para o diretório de trabalho do projeto, que geralmente está em ProjectFolder\bin\x64\Debug.
Etapa 2: Criar um caso de teste do script U-SQL
Veja abaixo o código de exemplo para o teste de script U-SQL. Para testar, você precisa preparar scripts, arquivos de entrada e os arquivos de saída esperados.
using System;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using System.IO;
using System.Text;
using System.Security.Cryptography;
using Microsoft.Analytics.LocalRun;
namespace UnitTestProject1
{
[TestClass]
public class USQLUnitTest
{
[TestMethod]
public void TestUSQLScript()
{
//Specify the local run message output path
StreamWriter MessageOutput = new StreamWriter("../../../log.txt");
LocalRunHelper localrun = new LocalRunHelper(MessageOutput);
//Configure the DateRoot path, Script Path and CPPSDK path
localrun.DataRoot = "../../../";
localrun.ScriptPath = "../../../Script/Script.usql";
localrun.CppSdkDir = "../../../CppSDK";
//Run U-SQL script
localrun.DoRun();
//Script output
string Result = Path.Combine(localrun.DataRoot, "Output/result.csv");
//Expected script output
string ExpectedResult = "../../../ExpectedOutput/result.csv";
Test.Helpers.FileAssert.AreEqual(Result, ExpectedResult);
//Don't forget to close MessageOutput to get logs into file
MessageOutput.Close();
}
}
}
namespace Test.Helpers
{
public static class FileAssert
{
static string GetFileHash(string filename)
{
Assert.IsTrue(File.Exists(filename));
using (var hash = new SHA1Managed())
{
var clearBytes = File.ReadAllBytes(filename);
var hashedBytes = hash.ComputeHash(clearBytes);
return ConvertBytesToHex(hashedBytes);
}
}
static string ConvertBytesToHex(byte[] bytes)
{
var sb = new StringBuilder();
for (var i = 0; i < bytes.Length; i++)
{
sb.Append(bytes[i].ToString("x"));
}
return sb.ToString();
}
public static void AreEqual(string filename1, string filename2)
{
string hash1 = GetFileHash(filename1);
string hash2 = GetFileHash(filename2);
Assert.AreEqual(hash1, hash2);
}
}
}
Interfaces de programação em LocalRunHelper.exe
O LocalRunHelper.exe fornece as interfaces de programação para compilação local do U-SQL, execução etc. As interfaces são listadas como abaixo.
Construtor
public LocalRunHelper([System.IO.TextWriter messageOutput = null])
| Parâmetro | Tipo | Descrição |
|---|---|---|
| messageOutput | System.IO.TextWriter | para mensagens de saída, definido como nulo para usar o Console |
Propriedades
| Propriedade | Tipo | Descrição |
|---|---|---|
| AlgebraPath | string | O caminho para o arquivo de álgebra (o arquivo de álgebra é um dos resultados da compilação) |
| CodeBehindReferences | string | Se o script tiver outras referências de código por trás, especifique os caminhos separados com ';' |
| CppSdkDir | string | Diretório do CppSDK |
| CurrentDir | string | Diretório atual |
| DataRoot | string | Caminho da raiz de dados |
| DebuggerMailPath | string | O caminho para o slot de correio do depurador |
| GenerateUdoRedirect | bool | Se quisermos gerar a configuração de substituição do redirecionamento de carregamento do assembly |
| HasCodeBehind | bool | Se o script tiver code-behind |
| InputDir | string | Diretório dos dados de entrada |
| MessagePath | string | Caminho do arquivo de despejo da mensagem |
| OutputDir | string | Diretório dos dados de saída |
| Paralelismo | INT | Paralelismo para executar a álgebra |
| ParentPid | INT | PID do pai no qual o serviço monitora a saída, definido como 0 ou negativo para ignorar |
| ResultPath | string | Caminho do arquivo de despejo do resultado |
| RuntimeDir | string | Diretório do runtime |
| ScriptPath | string | Local em que o script pode ser encontrado |
| Shallow | bool | Compilação superficial ou não |
| TempDir | string | Diretório temporário |
| UseDataBase | string | Especifique o banco de dados a ser usado para o registro de assembly temporário code-behind, mestre por padrão |
| WorkDir | string | Diretório de trabalho preferencial |
Método
| Método | Descrição | Retorno | Parâmetro |
|---|---|---|---|
| public bool DoCompile() | Compilar o script U-SQL | Verdadeiro se tiver êxito | |
| public bool DoExec() | Executar o resultado compilado | Verdadeiro se tiver êxito | |
| public bool DoRun() | Executar o script U-SQL (Compilar + Executar) | Verdadeiro se tiver êxito | |
| public bool IsValidRuntimeDir(string path) | Verificar se o caminho fornecido é um caminho de runtime válido | Verdadeiro para válido | O caminho do diretório de runtime |
Perguntas frequentes sobre um problema comum
Erro 1
E_CSC_SYSTEM_INTERNAL: Erro interno. Não foi possível carregar o arquivo ou o assembly “ScopeEngineManaged.dll” ou uma de suas dependências. O módulo especificado não pôde ser encontrado.
Verifique o seguinte:
- Verifique se você tem o ambiente x64. A plataforma de destino do build e o ambiente de teste devem ser x64; consulte Etapa 1: Criar configuração e projeto de teste de unidade do C# acima.
- Verifique se você copiou todos os arquivos de dependência em NugetPackage\build\runtime\ para o diretório de trabalho do projeto.
Próximas etapas
- Para aprender a usar o U-SQL, veja Introdução à linguagem U-SQL da Análise do Azure Data Lake.
- Para registrar em log as informações de diagnóstico, veja Acessando os logs de diagnóstico para o Azure Data Lake Analytics.
- Para ver uma consulta mais complexa, consulte Analisar logs de site usando o Azure Data Lake Analytics.
- Para ver detalhes do trabalho, confira Usar o Navegador de Trabalhos e o Modo de Exibição de Trabalho para trabalhos do Azure Data Lake Analytics.
- Para usar o modo de exibição de execução de vértice, veja Usar o Modo de Exibição de Execução de Vértice nas Ferramentas do Data Lake para Visual Studio.