Executar e testar U-SQL com o SDK U-SQL do Azure Data Lake

Artigo
12/20/2023

Importante

O Azure Data Lake Analytics descontinuado a 29 de fevereiro de 2024. Saiba mais com este anúncio.

Para análise de dados, a sua organização pode utilizar 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 submetê-lo para a cloud. O Azure Data Lake fornece um pacote NuGet denominado SDK U-SQL do Azure Data Lake para este cenário, através do qual pode facilmente dimensionar a execução e o teste do U-SQL. Também é possível integrar este teste U-SQL com o sistema CI (Integração Contínua) para automatizar a compilação e o teste.

Se quiser saber como executar e depurar manualmente o script U-SQL com ferramentas GUI, pode utilizar o Azure Data Lake Tools para Visual Studio para tal. Pode saber mais a partir daqui.

Instalar o SDK U-SQL do Azure Data Lake

Pode obter o SDK U-SQL do Azure Data Lake aqui no Nuget.org. Antes de utilizá-lo, tem de se certificar de que tem dependências da seguinte forma.

Dependências

O SDK U-SQL do Data Lake requer as seguintes dependências:

Microsoft .NET Framework 4.6 ou mais recente.
Microsoft Visual C++ 14 e Windows SDK 10.0.10240.0 ou mais recente (denominado CppSDK neste artigo). Existem duas formas de obter o CppSDK:
- Instale o Visual Studio Community Edition. Terá uma pasta \Windows Kits\10 na pasta Ficheiros do Programa, por exemplo, C:\Programas (x86)\Windows Kits\10. Também encontrará a versão do SDK Windows 10 em \Windows Kits\10\Lib. Se não vir estas pastas, reinstale o Visual Studio e certifique-se de que seleciona o SDK Windows 10 durante a instalação. Se tiver isto instalado com o Visual Studio, o compilador local U-SQL irá encontrá-lo automaticamente.
- Instale o Data Lake Tools para Visual Studio. Pode encontrar os ficheiros visual C++ e Windows SDK pré-embalados emC:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE\Extensions\Microsoft\ADL Tools\X.X.XXXX.X\CppSDK.
  
  Neste caso, o compilador local U-SQL não consegue localizar as dependências automaticamente. Tem de especificar o caminho do CppSDK para o mesmo. Pode copiar os ficheiros para outra localização ou utilizá-los tal como estão.

Compreender conceitos básicos

Raiz de dados

A pasta raiz de dados é um "arquivo local" para a conta de computação local. É equivalente à conta do Azure Data Lake Store de uma conta Data Lake Analytics. Mudar para uma pasta de raiz de dados diferente é como mudar para uma conta de arquivo diferente. Se quiser aceder a dados normalmente partilhados com diferentes pastas de raiz de dados, tem de utilizar caminhos absolutos nos seus scripts. Em alternativa, crie ligações simbólicas do sistema de ficheiros (por exemplo, mklink no NTFS) na pasta raiz de dados para apontar para os dados partilhados.

A pasta raiz de dados é utilizada para:

Armazene metadados locais, incluindo bases de dados, tabelas, funções com valor de tabela (TVFs) e assemblagens.
Procure os caminhos de entrada e saída definidos como caminhos relativos no U-SQL. A utilização de caminhos relativos facilita a implementação dos seus projetos U-SQL no Azure.

Caminho do ficheiro no U-SQL

Pode utilizar 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 utilize "/" como separador de caminho para tornar os scripts compatíveis com o lado do servidor. Seguem-se alguns exemplos de caminhos relativos e os seus caminhos absolutos equivalentes. Nestes 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, é criado um diretório de trabalho durante a compilação no diretório de execução atual. Além das saídas de compilação, os ficheiros de runtime necessários para a execução local serão copiados para este diretório de trabalho. A pasta raiz do diretório de trabalho chama-se "ScopeWorkDir" e os ficheiros no diretório de trabalho são os seguintes:

Diretório/ficheiro	Diretório/ficheiro	Diretório/ficheiro	Definição	Description
C6A101DDCB470506			Cadeia hash da versão de runtime	Cópia sombra dos ficheiros de runtime necessários para a execução local
	Script_66AE4909AA0ED06C		Nome do script + cadeia hash do caminho do script	Registo de saídas de compilação e passo de execução
		_script_.abr	Saída do compilador	Ficheiro Álgebra
		_ScopeCodeGen_.*	Saída do compilador	Código gerido gerado
		_ScopeCodeGenEngine_.*	Saída do compilador	Código nativo gerado
		assemblagens referenciadas	Referência da assemblagem	Ficheiros de assemblagem referenciados
		deployed_resources	Implementação de recursos	Ficheiros de implementação de recursos
		xxxxxxxx.xxx[1.n]_.	Registo de execução	Passos de registo de execução

Utilizar o SDK a partir da linha de comandos

Interface de linha de comandos da aplicação auxiliar

Em Diretório do SDK\build\runtime, LocalRunHelper.exe é a aplicação auxiliar de linha de comandos que fornece interfaces para a maioria das funções de execução local mais utilizadas. Tanto o comando como os comutadores de argumentos são sensíveis a maiúsculas e minúsculas. Para invocá-lo:

LocalRunHelper.exe <command> <Required-Command-Arguments> [Optional-Command-Arguments]

Execute LocalRunHelper.exe sem argumentos ou com a mudança de ajuda 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:

O comando dá o nome do comando.
O Argumento Obrigatório lista os argumentos que têm de ser fornecidos.
O Argumento Opcional lista os argumentos que são opcionais, com valores predefinidos. Os argumentos booleanos opcionais não têm parâmetros e as respetivas aparências significam negativas para o valor predefinido.

Valor devolvido e registo

A aplicação auxiliar devolve 0 para êxito e -1 para falha. Por predefinição, o programa auxiliar envia todas as mensagens para a consola atual. No entanto, a maioria dos comandos suporta o argumento -MessageOut path_to_log_file opcional que redireciona as saídas para um ficheiro de registo.

Configuração da variável de ambiente

A execução local de U-SQL precisa de uma raiz de dados especificada como conta de armazenamento local e de um caminho CppSDK especificado para dependências. Ambos podem definir o argumento na linha de comandos ou definir a variável de ambiente para os mesmos.

Defina a variável de ambiente SCOPE_CPP_SDK .

Se receber o Microsoft Visual C++ e o Windows SDK ao instalar as Ferramentas do Data Lake para Visual Studio, verifique se 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\CppSDK

Defina uma nova variável de ambiente denominada SCOPE_CPP_SDK para apontar para este diretório. Em alternativa, copie a pasta para a outra localização e especifique SCOPE_CPP_SDK como tal.

Além de definir a variável de ambiente, pode especificar o argumento -CppSDK quando estiver a utilizar a linha de comandos. Este argumento substitui a variável de ambiente do CppSDK predefinida.
Defina a variável de ambiente LOCALRUN_DATAROOT .

Defina uma nova variável de ambiente denominada LOCALRUN_DATAROOT que aponte para a raiz de dados.

Além de definir a variável de ambiente, pode especificar o argumento -DataRoot com o caminho de raiz de dados quando estiver a utilizar uma linha de comandos. Este argumento substitui a variável de ambiente de raiz de dados predefinida. Tem de adicionar este argumento a todas as linhas de comandos que estiver a executar para que possa substituir a variável de ambiente de raiz de dados predefinida para todas as operações.

Exemplos de utilização da linha de comandos do SDK

Compilar e executar

O comando executar é utilizado para compilar o script e, em seguida, executar resultados compilados. Os respetivos argumentos da linha de comandos são uma combinação dos argumentos de compilação e execução.

LocalRunHelper run -Script path_to_usql_script.usql [optional_arguments]

Seguem-se os argumentos opcionais para executar:

Argumento	Valor predefinido	Description
-CodeBehind	Falso	O script tem .cs código por trás
-CppSDK		Diretório CppSDK
-DataRoot	Variável de ambiente DataRoot	DataRoot para execução local, predefinição para variável de ambiente "LOCALRUN_DATAROOT"
-MessageOut		Capturar mensagens na consola para um ficheiro
-Paralelo	1	Executar o plano com o paralelismo especificado
-Referências		Lista de caminhos para assemblagens de referência adicionais ou ficheiros de dados de código por trás, separados por ';'
-UdoRedirect	Falso	Gerar configuração de redirecionamento de assemblagem Udo
-UseDatabase	master	Base de dados a utilizar para o código subjacente ao registo de assemblagem temporária
-Verboso	Falso	Mostrar saídas detalhadas do runtime
-WorkDir	Diretório Atual	Diretório para utilização e saídas do compilador
-RunScopeCEP	0	Modo ScopeCEP a utilizar
-ScopeCEPTempPath	temp	Caminho temporário a utilizar para transmissão em fluxo de dados
-OptFlags		Lista separada por vírgulas de sinalizadores otimizadores

Eis 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 compilar e executar, pode compilar e executar os executáveis compilados separadamente.

Compilar um script U-SQL

O comando compilar é utilizado para compilar um script U-SQL para executáveis.

LocalRunHelper compile -Script path_to_usql_script.usql [optional_arguments]

Seguem-se argumentos opcionais para compilar:

Argumento	Description
-CodeBehind [valor predefinido 'False']	O script tem .cs código por trás
-CppSDK [valor predefinido '']	Diretório CppSDK
-DataRoot [valor predefinido 'DataRoot environment variable']	DataRoot para execução local, predefinição para variável de ambiente "LOCALRUN_DATAROOT"
-MessageOut [valor predefinido '']	Capturar mensagens na consola para um ficheiro
-Referências [valor predefinido '']	Lista de caminhos para assemblagens de referência adicionais ou ficheiros de dados de código por trás, separados por ';'
-Raso [valor predefinido 'False']	Compilação rasa
-UdoRedirect [valor predefinido 'False']	Gerar configuração de redirecionamento de assemblagem Udo
-UseDatabase [valor predefinido 'master']	Base de dados a utilizar para o código subjacente ao registo de assemblagem temporária
-WorkDir [valor predefinido 'Diretório Atual']	Diretório para utilização e saídas do compilador
-RunScopeCEP [valor predefinido '0']	Modo ScopeCEP a utilizar
-ScopeCEPTempPath [valor predefinido 'temp']	Caminho temporário a utilizar para transmissão em fluxo de dados
-OptFlags [valor predefinido '']	Lista separada por vírgulas de sinalizadores otimizadores

Eis alguns exemplos de utilização.

Compilar um script U-SQL:

LocalRunHelper compile -Script d:\test\test1.usql

Compile um script U-SQL e defina a pasta raiz de dados. Esta ação substituirá a variável de ambiente definida.

LocalRunHelper compile -Script d:\test\test1.usql –DataRoot c:\DataRoot

Compile um script U-SQL e defina um diretório de trabalho, uma assemblagem de referência e uma base 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 é utilizado para executar resultados compilados.

LocalRunHelper execute -Algebra path_to_compiled_algebra_file [optional_arguments]

Seguem-se argumentos opcionais para execução:

Argumento	Valor predefinido	Description
-DataRoot	''	Raiz de dados para a execução de metadados. A predefinição é a variável de ambiente LOCALRUN_DATAROOT .
-MessageOut	''	Enviar mensagens na consola para um ficheiro.
-Paralelo	'1'	Indicador para executar os passos de execução local gerados com o nível de paralelismo especificado.
-Verboso	'Falso'	Indicador para mostrar saídas detalhadas do runtime.

Eis um exemplo de utilização:

LocalRunHelper execute -Algebra d:\test\workdir\C6A101DDCB470506\Script_66AE4909AA0ED06C\__script__.abr –DataRoot c:\DataRoot –Parallel 5

Utilizar o SDK com interfaces de programação

As interfaces de programação estão todas localizadas no LocalRunHelper.exe. Pode utilizá-los para integrar a funcionalidade do SDK U-SQL e da arquitetura de teste C# para dimensionar o teste local do script U-SQL. Neste artigo, vou utilizar o projeto de teste de unidade C# padrão para mostrar como utilizar estas interfaces para testar o script U-SQL.

Passo 1: Criar a configuração e o projeto de teste de unidadeS C#

Crie um projeto de teste de unidade C# através do > Projeto de Teste de Unidade de Teste > Do Novo Projeto Visual C# > do Projeto >>.
Adicione LocalRunHelper.exe como referência para o projeto. O LocalRunHelper.exe está localizado em \build\runtime\LocalRunHelper.exe no pacote NuGet.
O SDK U-SQL suporta apenas o ambiente x64 e certifique-se de que define o destino da plataforma de compilação como x64. Pode defini-lo através do destino da Plataforma de Compilação > de Propriedades > do Project.
Certifique-se de que define o ambiente de teste como x64. No Visual Studio, pode defini-lo através de Definições > de Teste > Arquitetura de Processador Predefinida > x64.
Certifique-se de que copia todos os ficheiros de dependência em NugetPackage\build\runtime\ para projetar o diretório de trabalho, que normalmente se encontra em ProjectFolder\bin\x64\Debug.

Passo 2: criar um caso de teste de script U-SQL

Abaixo encontra-se o código de exemplo para o teste do script U-SQL. Para testar, tem de preparar scripts, ficheiros de entrada e ficheiros 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 no LocalRunHelper.exe

LocalRunHelper.exe fornece as interfaces de programação para compilação local U-SQL, execução, etc. As interfaces estão listadas da seguinte forma.

Construtor

localRunHelper público([System.IO.TextWriter messageOutput = null])

Parâmetro	Tipo	Description
messageOutput	System.IO.TextWriter	para mensagens de saída, defina como nula para utilizar a Consola

Propriedades

Propriedade	Tipo	Description
AlgebraPath	string	O caminho para o ficheiro de álgebra (o ficheiro de álgebra é um dos resultados da compilação)
CodeBehindReferences	string	Se o script tiver outro código atrás das referências, especifique os caminhos separados por ";"
CppSdkDir	string	Diretório CppSDK
CurrentDir	string	Diretório atual
DataRoot	string	Caminho de raiz de dados
DebuggerMailPath	string	O caminho para o maillot de depurador
GenerateUdoRedirect	bool	Se quisermos gerar a configuração de substituição de redirecionamento de carregamento de assemblagem
HasCodeBehind	bool	Se o script tiver código por trás
InputDir	string	Diretório para dados de entrada
MessagePath	string	Caminho do ficheiro de captura de mensagens
OutputDir	string	Diretório para dados de saída
Paralelismo	int	Paralelismo para executar a álgebra
ParentPid	int	PID do elemento principal no qual o serviço monitoriza a saída, definido como 0 ou negativo para ignorar
ResultPath	string	Caminho do ficheiro de informação de falha de sistema de resultados
RuntimeDir	string	Diretório runtime
ScriptPath	string	Onde encontrar o script
Raso	bool	Compilação rasa ou não
TempDir	string	Diretório temporário
UseDataBase	string	Especifique a base de dados a utilizar para o código subjacente ao registo de assemblagem temporária, mestre por predefinição
WorkDir	string	Diretório de trabalho preferencial

Método

Método	Descrição	Devolver	Parâmetro
public bool DoCompile()	Compilar o script U-SQL	Verdadeiro no sucesso
public bool DoExec()	Executar o resultado compilado	Verdadeiro no sucesso
public bool DoRun()	Executar o script U-SQL (Compilar + Executar)	Verdadeiro no sucesso
bool público IsValidRuntimeDir(caminho da cadeia)	Verificar se o caminho especificado é um caminho de runtime válido	Verdadeiro para válido	O caminho do diretório de runtime

FAQ sobre o problema comum

Erro 1

E_CSC_SYSTEM_INTERNAL: Erro interno! Não foi possível carregar o ficheiro ou a assemblagem "ScopeEngineManaged.dll" ou uma das respetivas dependências. Não foi possível localizar o módulo especificado.

Verifique o seguinte:

Certifique-se de que tem um ambiente x64. A plataforma de destino da compilação e o ambiente de teste devem ser x64. Veja o Passo 1: Criar o projeto de teste de unidades C# e a configuração acima.
Certifique-se de que copiou todos os ficheiros de dependência em NugetPackage\build\runtime\ para o diretório de trabalho do projeto.

Passos seguintes

Para saber mais sobre U-SQL, consulte Introdução à linguagem U-SQL da Análise do Azure Data Lake.
Para registar informações de diagnóstico, veja Aceder aos registos de diagnóstico do Azure Data Lake Analytics.
Para ver uma consulta mais complexa, veja Analisar registos de sites com o Azure Data Lake Analytics.
Para ver os detalhes da tarefa, veja Utilizar o Browser de Tarefas e a Vista de Tarefas para tarefas do Azure Data Lake Analytics.
Para utilizar a vista de execução de vértice, veja Utilizar a Vista de Execução de Vértice nas Ferramentas do Data Lake para Visual Studio.

Partilhar via