Compartilhar via

Criar um aplicativo para executar consultas básicas

  • Artigo

Aplica-se a: ✅Microsoft Fabric✅ do Azure Data Explorer

Neste artigo, você aprenderá a:

Pré-requisitos

Configurar seu ambiente de desenvolvimento para usar a biblioteca de clientes do Kusto.

Executar uma consulta básica e processar os resultados

Em seu IDE ou editor de texto preferido, crie um projeto ou arquivo chamado consulta básica usando a convenção apropriada para seu idioma preferido. Em seguida, adicione o seguinte código:

  1. Crie um aplicativo cliente que se conecte ao cluster de ajuda .

    using Kusto.Data;
using Kusto.Data.Net.Client;

namespace BasicQuery {
  class BasicQuery {
    static void Main(string[] args) {
      var clusterUri = "https://help.kusto.windows.net/";
      var kcsb = new KustoConnectionStringBuilder(clusterUri)
          .WithAadUserPromptAuthentication();

      using (var kustoClient = KustoClientFactory.CreateCslQueryProvider(kcsb)) {
      }
    }
  }
}

  2. Defina o banco de dados e a consulta a serem executadas. A consulta retorna a data, o estado e o dano total relacionados ao tornado onde o dano total excedeu 100 milhões de dólares.

    var database = "Samples";
var query = @"StormEvents
              | where EventType == 'Tornado'
              | extend TotalDamage = DamageProperty + DamageCrops
              | summarize DailyDamage=sum(TotalDamage) by State, bin(StartTime, 1d)
              | where DailyDamage > 100000000
              | order by DailyDamage desc";

  3. Execute a consulta e imprima o resultado.

    using (var response = kustoClient.ExecuteQuery(database, query, null)) {
  int columnNoStartTime = response.GetOrdinal("StartTime");
  int columnNoState = response.GetOrdinal("State");
  int columnNoDailyDamage = response.GetOrdinal("DailyDamage");
  Console.WriteLine("Daily tornado damages over 100,000,000$:");

  while (response.Read()) {
    Console.WriteLine("{0} - {1}, {2}",
      response.GetDateTime(columnNoStartTime),
      response.GetString(columnNoState),
      response.GetInt64(columnNoDailyDamage));
  }
}

O código completo deve ter esta aparência:

using Kusto.Data;
using Kusto.Data.Net.Client;

namespace BasicQuery {
  class BasicQuery {
    static void Main(string[] args) {
      string clusterUri = "https://help.kusto.windows.net/";
      var kcsb = new KustoConnectionStringBuilder(clusterUri)
          .WithAadUserPromptAuthentication();

      using (var kustoClient = KustoClientFactory.CreateCslQueryProvider(kcsb)) {
        string database = "Samples";
        string query = @"StormEvents
                         | where EventType == 'Tornado'
                         | extend TotalDamage = DamageProperty + DamageCrops
                         | summarize DailyDamage=sum(TotalDamage) by State, bin(StartTime, 1d)
                         | where DailyDamage > 100000000
                         | order by DailyDamage desc";

        using (var response = kustoClient.ExecuteQuery(database, query, null)) {
          int columnNoStartTime = response.GetOrdinal("StartTime");
          int columnNoState = response.GetOrdinal("State");
          int columnNoDailyDamage = response.GetOrdinal("DailyDamage");

          Console.WriteLine("Daily tornado damages over 100,000,000$:");

          while (response.Read()) {
            Console.WriteLine("{0} - {1}, {2}",
              response.GetDateTime(columnNoStartTime),
              response.GetString(columnNoState),
              response.GetInt64(columnNoDailyDamage));
          }
        }
      }
    }
  }
}

Executar seu aplicativo

Em um shell de comando, use o seguinte comando para executar seu aplicativo:

# Change directory to the folder that contains the basic queries project
dotnet run .

Você deverá ver um resultado semelhante ao seguinte:

Daily damages tornado with damages over 100,000,000$:
2007-02-02 00:00:00+00:00 - FLORIDA , 270004000 $
2007-03-01 00:00:00+00:00 - ALABAMA , 266853000 $
2007-05-04 00:00:00+00:00 - KANSAS , 251625000 $
2007-03-01 00:00:00+00:00 - GEORGIA , 143688000 $

Usar posições ordinais para acessar valores de coluna

Quando a ordem das colunas em um resultado de consulta é conhecida, é mais eficiente acessar os valores das colunas pela posição ordinal no conjunto de resultados do que pelo nome da coluna. Opcionalmente, no runtime, você pode usar um método de biblioteca para determinar um ordinal da coluna do nome da coluna.

Nota

Você pode controlar a presença e a ordem das colunas em um resultado de consulta usando os operadores project ou project-away.

Por exemplo, você pode modificar o código anterior para acessar os valores das colunas StartTime, Statee DailyDamage por suas posições ordinais no conjunto de resultados:

Em C#, você só pode acessar os valores das colunas por suas posições ordinais no conjunto de resultados. Você não pode usar os nomes de coluna; portanto, o código permanece o mesmo.

int columnNoStartTime = response.GetOrdinal("StartTime");
int columnNoState = response.GetOrdinal("State");
int columnNoDailyDamage = response.GetOrdinal("DailyDamage");
Console.WriteLine("Daily tornado damages over 100,000,000$:");

while (response.Read()) {
  Console.WriteLine("{0} - {1}, {2}",
    response.GetDateTime(columnNoStartTime),
    response.GetString(columnNoState),
    response.GetInt64(columnNoDailyDamage));
}

Personalizar o comportamento da consulta com as propriedades da solicitação do cliente

Você pode personalizar o comportamento de uma consulta definindo as propriedades da solicitação do cliente. Para obter mais informações sobre as opções disponíveis, confira propriedades de solicitação de cliente.

Por exemplo, você pode substituir a chamada kusto_client.execute_query no código anterior para passar uma ID de solicitação personalizada e definir o tempo limite da consulta como 1 minuto. Para usar as propriedades de solicitação do cliente, você deve importar a classe ClientRequestProperties.

using Kusto.Data.Common;

var crp = new ClientRequestProperties();
// Set a custom client request identifier
crp.ClientRequestId = "QueryDemo" + Guid.NewGuid().ToString();
// Set the query timeout to 1 minute
crp.SetOption(ClientRequestProperties.OptionServerTimeout, "1m");

using (var response = kustoClient.ExecuteQuery(database, query, crp)) {
}

Usar parâmetros de consulta para proteger a entrada do usuário

Os parâmetros de consulta são importantes para manter a segurança e a proteção de seus dados. Ele o protege de potenciais atores mal-intencionados que podem tentar obter acesso não autorizado ou corromper seus dados. Para obter mais informações sobre consultas parametrizadas, consulte instrução de declaração de parâmetros de consulta.

Por exemplo, você pode modificar o código anterior para passar o valor EventType e DailyDamage valor mínimo como parâmetros para a consulta. Para usar parâmetros:

  1. Declarar os parâmetros no texto da consulta
  2. Substitua os valores de propriedade no texto da consulta pelos nomes dos parâmetros
  3. Definir os valores de parâmetro nas propriedades de solicitação do cliente passadas para o método execute
string query = @"declare query_parameters(event_type:string, daily_damage:int);
                  StormEvents
                  | where EventType == event_type
                  | extend TotalDamage = DamageProperty + DamageCrops
                  | summarize DailyDamage=sum(TotalDamage) by State, bin(StartTime, 1d)
                  | where DailyDamage > daily_damage
                  | order by DailyDamage desc";

var crp = new ClientRequestProperties();
crp.SetParameter("event_type", "Flash Flood");
crp.SetParameter("daily_damage", 200000000.ToString());

using (var response = kustoClient.ExecuteQuery(database, query, crp)) {
  int columnNoStartTime = response.GetOrdinal("StartTime");
  int columnNoState = response.GetOrdinal("State");
  int columnNoDailyDamage = response.GetOrdinal("DailyDamage");
  Console.WriteLine("Daily flash flood damages over 200,000,000$:");

  while (response.Read()) {
    Console.WriteLine("{0} - {1}, {2}",
      response.GetDateTime(columnNoStartTime),
      response.GetString(columnNoState),
      response.GetInt64(columnNoDailyDamage));
  }
}

O código completo usando posições ordinais para acessar valores e parâmetros de coluna deve ter esta aparência:

using Kusto.Data;
using Kusto.Data.Common;
using Kusto.Data.Net.Client;

namespace BasicQuery {
  class BasicQuery {
    static void Main(string[] args) {
      string clusterUri = "https://help.kusto.windows.net/";
      var kcsb = new KustoConnectionStringBuilder(clusterUri)
          .WithAadUserPromptAuthentication();

      using (var kustoClient = KustoClientFactory.CreateCslQueryProvider(kcsb)) {
        string database = "Samples";
        string query = @"declare query_parameters(event_type:string, daily_damage:int);
                         StormEvents
                         | where EventType == event_type
                         | extend TotalDamage = DamageProperty + DamageCrops
                         | summarize DailyDamage=sum(TotalDamage) by State, bin(StartTime, 1d)
                         | where DailyDamage > daily_damage
                         | order by DailyDamage desc";

        var crp = new ClientRequestProperties();
        crp.ClientRequestId = "QueryDemo" + Guid.NewGuid().ToString();
        crp.SetOption(ClientRequestProperties.OptionServerTimeout, "1m");
        crp.SetParameter("event_type", "Flash Flood");
        crp.SetParameter("daily_damage", 200000000.ToString());

        using (var response = kustoClient.ExecuteQuery(database, query, crp)) {
          int columnNoStartTime = response.GetOrdinal("StartTime");
          int columnNoState = response.GetOrdinal("State");
          int columnNoDailyDamage = response.GetOrdinal("DailyDamage");

          Console.WriteLine("Daily flash flood damages over 200,000,000$:");

          while (response.Read()) {
            Console.WriteLine("{0} - {1}, {2}",
              response.GetDateTime(columnNoStartTime),
              response.GetString(columnNoState),
              response.GetInt64(columnNoDailyDamage));
          }
        }
      }
    }
  }
}

Você deverá ver um resultado semelhante ao seguinte:

Daily flash flood damages over 200,000,000$:
2007-08-21 00:00:00+00:00 - OHIO , 253320000 $

Próxima etapa

Criar um aplicativo para executar comandos de gerenciamento