Criar uma aplicação para executar consultas básicas

  • Artigo

Neste artigo, vai aprender a:

Pré-requisitos

Configure o seu ambiente de desenvolvimento para utilizar a biblioteca de cliente Kusto.

Executar uma consulta básica e processar os resultados

No seu IDE ou editor de texto preferido, crie um projeto ou ficheiro com o nome de consulta básica com a convenção adequada para o seu idioma preferido. Em seguida, adicione o seguinte código:

  1. Crie uma aplicação cliente que se ligue 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 a base de dados e a consulta a executar. A consulta devolve a data, o estado e os danos totais relacionados com tornados em que os danos totais ultrapassaram os 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 o seguinte aspeto:

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 a aplicação

Numa shell de comandos, utilize o seguinte comando para executar a sua aplicação:

# 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 $

Utilizar posições ordinais para aceder aos valores das colunas

Quando a ordem das colunas num resultado de consulta é conhecida, é mais eficiente aceder aos valores das colunas pela respetiva posição ordinal no conjunto de resultados do que pelo respetivo nome de coluna. Opcionalmente, no runtime, pode utilizar um método de biblioteca para determinar uma coluna ordinal do respetivo nome de coluna.

Nota

Pode controlar a presença e a ordem das colunas num resultado de consulta com os project operadores ou project-away .

Por exemplo, pode modificar o código anterior para aceder aos valores das StartTimecolunas , Statee DailyDamage pelas respetivas posições ordinais no conjunto de resultados:

Em C#, só pode aceder aos valores das colunas pelas respetivas posições ordinais no conjunto de resultados. Não pode utilizar os nomes das colunas; assim, 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 do pedido de cliente

Pode personalizar o comportamento de uma consulta ao definir as propriedades do pedido de cliente. Para obter mais informações sobre as opções disponíveis, veja Propriedades do pedido de cliente.

Por exemplo, pode substituir a kusto_client.execute_query chamada no código anterior para transmitir um ID de pedido personalizado e definir o tempo limite da consulta para 1 minuto. Para utilizar as propriedades do pedido de cliente, tem de importar a ClientRequestProperties classe.

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)) {
}

Utilizar parâmetros de consulta para proteger a entrada do utilizador

Os parâmetros de consulta são importantes para manter a segurança e a proteção dos seus dados. Protege-o de potenciais atores maliciosos que podem tentar obter acesso não autorizado ou danificar os seus dados. Para obter mais informações sobre consultas parametrizadas, veja Declaração de declaração de parâmetros de consulta.

Por exemplo, pode modificar o código anterior para transmitir o valor EventType e o valor mínimo DailyDamage como parâmetros para a consulta. Para utilizar 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 dos parâmetros nas propriedades do pedido de cliente transmitidas ao método de execução
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 que utiliza posições ordinais para aceder a valores e parâmetros de coluna deve ter o seguinte aspeto:

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 $

Passo seguinte

Criar uma aplicação para executar comandos de gestão