Partilhar via


Criar um aplicativo para executar consultas básicas

Aplica-se a: ✅Microsoft FabricAzure Data Explorer

Neste artigo, você aprenderá a:

Pré-requisitos

Configure seu ambiente de desenvolvimento para usar a biblioteca de cliente Kusto.

Executar uma consulta básica e processar os resultados

Em seu IDE ou editor de texto preferido, crie um projeto ou arquivo chamado de 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 executados. A consulta retorna a data, o estado e o dano total relacionado ao tornado em que 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 .

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 as posições ordinais para aceder aos valores das colunas

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

Observação

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. Não é possível usar os nomes das colunas; 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 de solicitação do cliente

Você pode personalizar o comportamento de uma consulta definindo as propriedades de solicitação do cliente. Para mais informações sobre as opções disponíveis, consulte as propriedades do pedido do 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 de consulta para 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 dos seus dados. Protege-o de potenciais agentes maliciosos que possam tentar obter acesso não autorizado ou corromper os seus dados. Para obter mais informações sobre consultas parametrizadas, consulte instrução de declaração de parâmetros de consulta.

Por exemplo, pode modificar o código anterior para passar o valor de EventType e o valor mínimo de DailyDamage 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. Defina 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));
          }
        }
      }
    }
  }
}

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óximo passo