Associações de entrada do Azure Data Explorer para Azure Functions (versão prévia)

A associação de entrada do Azure Data Explorer recupera dados de um banco de dados.

Exemplos

A função C# pode ser criada por meio de um dos seguintes modos C#:

• Modelo de trabalho isolado: função C# compilada executada em um processo de trabalho que está isolado do runtime. É necessário um processo de trabalho isolado para dar suporte às funções C# executadas nas versões LTS e não LTS do .NET e do .NET Framework.
• Modelo em processo: função C# compilada no mesmo processo que o runtime do Functions.
• Script C#: usado principalmente ao criar funções C# no portal do Azure.

Importante

O suporte para o modelo em processo terminará em 10 de novembro de 2026. É altamente recomendável que você migre seus aplicativos para o modelo de trabalho isolado para obter suporte completo.

Modelo de trabalho isolado

Mais exemplos da associação de entrada (fora do processo) do Azure Data Explorer estão disponíveis no Repositório do GitHub.

Esta seção contém os seguintes exemplos:

• Gatilho HTTP, obter linha por ID na cadeia de caracteres de consulta
• Gatilho HTTP, obter várias linhas dos dados da rota

Os exemplos referem-se a uma classe Product e à tabela Products, ambas definidas nas seções anteriores.

Gatilho HTTP, obter linha por ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma função C# que recupera um único registro. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar a ID. Essa ID é usada para recuperar um Product registro com a consulta especificada.

Observação

O parâmetro de cadeia de caracteres de consulta HTTP diferencia maiúsculas de minúsculas.

using System.Text.Json.Nodes;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Kusto;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Azure.WebJobs.Extensions.Kusto.SamplesOutOfProc.OutputBindingSamples.Common;

namespace Microsoft.Azure.WebJobs.Extensions.Kusto.SamplesOutOfProc.InputBindingSamples
{
    public static class GetProductsQuery
    {
        [Function("GetProductsQuery")]
        public static JsonArray Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "getproductsquery")] HttpRequestData req,
            [KustoInput(Database: "productsdb",
            KqlCommand = "declare query_parameters (productId:long);Products | where ProductID == productId",
            KqlParameters = "@productId={Query.productId}",Connection = "KustoConnectionString")] JsonArray products)
        {
            return products;
        }
    }
}

Gatilho HTTP, obter várias linhas do parâmetro da rota

O exemplo a seguir mostra uma função C# que recupera registros retornados pela consulta (com base no nome do produto nesse caso). A função é disparada por uma solicitação HTTP que usa dados da rota para especificar o valor de um parâmetro de consulta. Esse parâmetro é usado para filtrar os Product registros na consulta especificada.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Kusto;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Azure.WebJobs.Extensions.Kusto.SamplesOutOfProc.OutputBindingSamples.Common;

namespace Microsoft.Azure.WebJobs.Extensions.Kusto.SamplesOutOfProc.InputBindingSamples
{
    public static class GetProductsFunction
    {
        [Function("GetProductsFunction")]
        public static IEnumerable<Product> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "getproductsfn/{name}")] HttpRequestData req,
            [KustoInput(Database: "productsdb",
            KqlCommand = "declare query_parameters (name:string);GetProductsByName(name)",
            KqlParameters = "@name={name}",Connection = "KustoConnectionString")] IEnumerable<Product> products)
        {
            return products;
        }
    }
}

Modelo em processo

Mais exemplos da associação de entrada do Azure Data Explorer estão disponíveis no Repositório do GitHub.

Esta seção contém os seguintes exemplos:

• Gatilho HTTP, obter linha por ID na cadeia de caracteres de consulta
• Gatilho HTTP, obter várias linhas dos dados da rota

Os exemplos se referem a uma classe Product e a uma tabela de banco de dados correspondente:

public class Product
{
    [JsonProperty(nameof(ProductID))]
    public long ProductID { get; set; }

    [JsonProperty(nameof(Name))]
    public string Name { get; set; }

    [JsonProperty(nameof(Cost))]
    public double Cost { get; set; }
}

.create-merge table Products (ProductID:long, Name:string, Cost:double)

Gatilho HTTP, obter linha por ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma função C# que recupera uma lista dos produtos com um productId fornecido. A função é disparada por uma solicitação HTTP que usa um parâmetro da ID. Essa ID é usada para recuperar uma lista de Product que corresponde à consulta.

Observação

O parâmetro de cadeia de caracteres de consulta HTTP diferencia maiúsculas de minúsculas.

using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.Kusto.Samples.Common;
using Microsoft.Azure.WebJobs.Kusto;

namespace Microsoft.Azure.WebJobs.Extensions.Kusto.Samples.InputBindingSamples
{
    public static class GetProducts
    {
        [FunctionName("GetProductsList")]
        public static async Task<IActionResult> RunAsync(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "getproducts")]
            HttpRequest req,
            [Kusto(Database:"productsdb" ,
            KqlCommand = "declare query_parameters (productId:long);Products | where ProductID == productId" ,
            KqlParameters = "@productId={Query.productId}", // get the value of the query parameter "productId"
            Connection = "KustoConnectionString")]
            IAsyncEnumerable<Product> products)
        {
            IAsyncEnumerator<Product> enumerator = products.GetAsyncEnumerator();
            var productList = new List<Product>();
            while (await enumerator.MoveNextAsync())
            {
                productList.Add(enumerator.Current);
            }
            await enumerator.DisposeAsync();
            return new OkObjectResult(productList);
        }
    }
}

Gatilho HTTP, obter várias linhas do parâmetro da rota

O exemplo a seguir mostra uma função C# que recupera documentos retornados pela consulta. A função é disparada por uma solicitação HTTP que usa dados da rota para especificar o valor de um parâmetro de função KQL. A função simples GetProductsByName recupera um conjunto de produtos que correspondem a um nome de produto.

.create function ifnotexists GetProductsByName(name:string)
{
    Products | where Name == name
}

using System.Collections.Generic;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;

namespace Microsoft.Azure.WebJobs.Extensions.Kusto.Samples.InputBindingSamples
{
  public static class GetProductsFunction
      {
          [FunctionName("GetProductsFunction")]
          public static IActionResult Run(
              [HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "getproductsfn/{name}")]
              HttpRequest req,
              [Kusto(Database:"productsdb" ,
              KqlCommand = "declare query_parameters (name:string);GetProductsByName(name)" ,
              KqlParameters = "@name={name}",
              Connection = "KustoConnectionString")]
              IEnumerable<Product> products)
          {
              return new OkObjectResult(products);
          }
      }
}

Mais exemplos da associação de entrada do Azure Data Explorer java estão disponíveis no Repositório do GitHub.

Esta seção contém os seguintes exemplos:

• Gatilho HTTP, obter várias linhas
• Gatilho HTTP, obter linha por ID na cadeia de caracteres de consulta

Os exemplos se referem a uma classe Product (em um arquivo Product.java separado) e a uma tabela de banco de dados correspondente.

package com.microsoft.azure.kusto.common;

import com.fasterxml.jackson.annotation.JsonProperty;

public class Product {
    @JsonProperty("ProductID")
    public long ProductID;
    @JsonProperty("Name")
    public String Name;
    @JsonProperty("Cost")
    public double Cost;

    public Product() {
    }

    public Product(long ProductID, String name, double Cost) {
        this.ProductID = ProductID;
        this.Name = name;
        this.Cost = Cost;
    }
}

Gatilho HTTP, obter várias linhas

O exemplo usa um parâmetro de rota para especificar o nome da ID dos produtos. Todos os produtos correspondentes são recuperados da tabela de produtos.

package com.microsoft.azure.kusto.inputbindings;

import com.microsoft.azure.functions.HttpMethod;
import com.microsoft.azure.functions.HttpRequestMessage;
import com.microsoft.azure.functions.HttpResponseMessage;
import com.microsoft.azure.functions.HttpStatus;
import com.microsoft.azure.functions.annotation.AuthorizationLevel;
import com.microsoft.azure.functions.annotation.FunctionName;
import com.microsoft.azure.functions.annotation.HttpTrigger;
import com.microsoft.azure.functions.kusto.annotation.KustoInput;
import com.microsoft.azure.kusto.common.Product;


import java.util.Optional;

public class GetProducts {
    @FunctionName("GetProducts")
    public HttpResponseMessage run(
        @HttpTrigger(name = "req", methods = {
            HttpMethod.GET}, authLevel = AuthorizationLevel.ANONYMOUS, route = "getproducts/{productId}") HttpRequestMessage<Optional<String>> request,
            @KustoInput(name = "getjproducts", kqlCommand = "declare query_parameters (productId:long);Products | where ProductID == productId",
                    kqlParameters = "@productId={productId}", database = "productsdb", connection = "KustoConnectionString") Product[] products) {
        return request.createResponseBuilder(HttpStatus.OK).header("Content-Type", "application/json").body(products)
                .build();
    }
}

Gatilho HTTP, obter linha por ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma consulta à tabela de produtos pelo nome do produto. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o valor de um parâmetro de consulta. Esse parâmetro é usado para filtrar os Product registros na consulta especificada.

package com.microsoft.azure.kusto.inputbindings;

import com.microsoft.azure.functions.HttpMethod;
import com.microsoft.azure.functions.HttpRequestMessage;
import com.microsoft.azure.functions.HttpResponseMessage;
import com.microsoft.azure.functions.HttpStatus;
import com.microsoft.azure.functions.annotation.AuthorizationLevel;
import com.microsoft.azure.functions.annotation.FunctionName;
import com.microsoft.azure.functions.annotation.HttpTrigger;
import com.microsoft.azure.functions.kusto.annotation.KustoInput;
import com.microsoft.azure.kusto.common.Product;

import java.util.Optional;

public class GetProductsQueryString {
    @FunctionName("GetProductsQueryString")
    public HttpResponseMessage run(@HttpTrigger(name = "req", methods = {
            HttpMethod.GET}, authLevel = AuthorizationLevel.ANONYMOUS, route = "getproducts") HttpRequestMessage<Optional<String>> request,
            @KustoInput(name = "getjproductsquery", kqlCommand = "declare query_parameters (name:string);GetProductsByName(name)",
                    kqlParameters = "@name={Query.name}", database = "productsdb", connection = "KustoConnectionString") Product[] products) {
        return request.createResponseBuilder(HttpStatus.OK).header("Content-Type", "application/json").body(products)
                .build();
    }
}

Mais exemplos da associação de entrada do Azure Data Explorer estão disponíveis no Repositório do GitHub.

Esta seção contém os seguintes exemplos:

• Gatilho HTTP, obter várias linhas
• Gatilho HTTP, obter linha por ID na cadeia de caracteres de consulta

Os exemplos se referem a uma tabela de banco de dados:

Gatilho HTTP, obter várias linhas

O exemplo a seguir mostra uma associação de entrada do Azure Data Explorer em um arquivo function.json e uma função do JavaScript que lê a partir de uma consulta e retorna os resultados na resposta HTTP.

Veja a seguir a associação de dados no arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "function",
      "name": "req",
      "direction": "in",
      "type": "httpTrigger",
      "methods": [
        "get"
      ],
      "route": "getproducts/{productId}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "productget",
      "type": "kusto",
      "database": "productsdb",
      "direction": "in",
      "kqlCommand": "declare query_parameters (productId:long);Products | where ProductID == productId",
      "kqlParameters": "@productId={productId}",
      "connection": "KustoConnectionString"
    }
  ],
  "disabled": false
}

A seção configuração explica essas propriedades.

O snippet a seguir é um exemplo de código JavaScript:

module.exports = async function (context, req, productget) {
    return {
        status: 200,
        body: productget
    };
}

Gatilho HTTP, obter linha pelo nome na cadeia de caracteres de consulta

O exemplo a seguir mostra uma consulta à tabela de produtos pelo nome do produto. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o valor de um parâmetro de consulta. Esse parâmetro é usado para filtrar os Product registros na consulta especificada.

Veja a seguir a associação de dados no arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "function",
      "name": "req",
      "direction": "in",
      "type": "httpTrigger",
      "methods": [
        "get"
      ],
      "route": "getproductsfn"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "productfnget",
      "type": "kusto",
      "database": "productsdb",
      "direction": "in",
      "kqlCommand": "declare query_parameters (name:string);GetProductsByName(name)",
      "kqlParameters": "@name={Query.name}",
      "connection": "KustoConnectionString"
    }
  ],
  "disabled": false
}

A seção configuração explica essas propriedades.

O snippet a seguir é um exemplo de código JavaScript:

module.exports = async function (context, req, producproductfngettget) {
    return {
        status: 200,
        body: productfnget
    };
}

Mais exemplos da associação de entrada do Azure Data Explorer estão disponíveis no Repositório do GitHub.

Esta seção contém os seguintes exemplos:

• Gatilho HTTP, obter várias linhas
• Gatilho HTTP: obter registros por meio de uma função KQL

Gatilho HTTP, obter várias linhas

O exemplo a seguir mostra uma associação de entrada do Azure Data Explorer em um arquivo function.json e uma função do Python que lê em uma consulta e retorna os resultados na resposta HTTP.

Veja a seguir a associação de dados no arquivo function.json:

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "Anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get"
      ],
      "route": "getproducts/{productId}"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "name": "productsdb",
      "type": "kusto",
      "database": "sdktestsdb",
      "direction": "in",
      "kqlCommand": "declare query_parameters (productId:long);Products | where ProductID == productId",
      "kqlParameters": "@productId={Query.productId}",
      "connection": "KustoConnectionString"
    }
  ]
}

A seção configuração explica essas propriedades.

O snippet a seguir é um exemplo de código Python:

import azure.functions as func
from Common.product import Product


def main(req: func.HttpRequest, products: str) -> func.HttpResponse:
    return func.HttpResponse(
        products,
        status_code=200,
        mimetype="application/json"
    )

Gatilho HTTP, obter linha por ID na cadeia de caracteres de consulta

O exemplo a seguir mostra uma consulta à tabela de produtos pelo nome do produto. A função é disparada por uma solicitação HTTP que usa uma cadeia de caracteres de consulta para especificar o valor de um parâmetro de consulta. Esse parâmetro é usado para filtrar os Product registros na consulta especificada.

Veja a seguir a associação de dados no arquivo function.json:

{
  "bindings": [
    {
      "authLevel": "function",
      "name": "req",
      "direction": "in",
      "type": "httpTrigger",
      "methods": [
        "get"
      ],
      "route": "getproductsfn"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "productfnget",
      "type": "kusto",
      "database": "productsdb",
      "direction": "in",
      "kqlCommand": "declare query_parameters (name:string);GetProductsByName(name)",
      "kqlParameters": "@name={Query.name}",
      "connection": "KustoConnectionString"
    }
  ],
  "disabled": false
}

A seção configuração explica essas propriedades.

O snippet a seguir é um exemplo de código Python:

import azure.functions as func

def main(req: func.HttpRequest, products: str) -> func.HttpResponse:
    return func.HttpResponse(
        products,
        status_code=200,
        mimetype="application/json"
    )

Atributos

A biblioteca C# usa o atributo KustoAttribute para declarar as associações do Azure Data Explorer na função, que tem as seguintes propriedades.

Propriedade de atributo	Descrição
Banco de dados	Obrigatórios. O banco de dados no qual a consulta deve ser executada.
Conexão	Obrigatórios. O nome da variável que contém a cadeia de conexão, resolvida por meio de variáveis de ambiente ou por meio de configurações do aplicativo de funções. O padrão é pesquisar na variável KustoConnectionString. No runtime, essa variável é pesquisada no ambiente. A cadeia de conexão está documentada nas cadeias de conexão do Kusto. Por exemplo: "KustoConnectionString": "Data Source=https://your_cluster.kusto.windows.net;Database=your_Database;Fed=True;AppClientId=your_AppId;AppKey=your_AppKey;Authority Id=your_TenantId.
KqlCommand	Obrigatórios. O parâmetro KqlQuery que deve ser executado. Pode ser uma consulta KQL ou uma chamada de função KQL.
KqlParameters	Opcional. Parâmetros que atuam como variáveis de predicado para KqlCommand. Por exemplo, "@name={name},@Id={id}", em que os parâmetros{name} e {id} são substituídos em runtime por valores reais que atuam como predicados. Nem o nome nem o valor do parâmetro podem conter uma vírgula (,) ou um sinal de igual (=).
ManagedServiceIdentity	Opcional. Uma identidade gerenciada pode ser usada para se conectar ao Azure Data Explorer. Para usar uma identidade gerenciada pelo sistema, use "system". Todos os outros nomes de identidade são interpretados como identidade gerenciada pelo usuário.

Anotações

A biblioteca de runtime de funções Java usa a anotação @KustoInput (com.microsoft.azure.functions.kusto.annotation.KustoInput):

Elemento	Descrição
name	Obrigatórios. O nome da variável que representa os resultados da consulta no código da função.
Banco de Dados	Obrigatórios. O banco de dados no qual a consulta deve ser executada.
connection	Obrigatórios. O nome da variável que contém a cadeia de conexão, resolvida por meio de variáveis de ambiente ou por meio de configurações do aplicativo de funções. O padrão é pesquisar na variável KustoConnectionString. No runtime, essa variável é pesquisada no ambiente. A cadeia de conexão está documentada nas cadeias de conexão do Kusto. Por exemplo: "KustoConnectionString": "Data Source=https://your_cluster.kusto.windows.net;Database=your_Database;Fed=True;AppClientId=your_AppId;AppKey=your_AppKey;Authority Id=your_TenantId.
kqlCommand	Obrigatórios. O parâmetro KqlQuery que deve ser executado. Pode ser uma consulta KQL ou uma chamada de função KQL.
kqlParameters	Opcional. Parâmetros que atuam como variáveis de predicado para KqlCommand. Por exemplo, "@name={name},@Id={id}", em que os parâmetros{name} e {id} são substituídos em runtime por valores reais que atuam como predicados. Nem o nome nem o valor do parâmetro podem conter uma vírgula (,) ou um sinal de igual (=).
managedServiceIdentity	Uma identidade gerenciada pode ser usada para se conectar ao Azure Data Explorer. Para usar uma identidade gerenciada pelo sistema, use "system". Todos os outros nomes de identidade são interpretados como identidade gerenciada pelo usuário.

Configuração

A tabela a seguir explica as propriedades de configuração de associação que você define no arquivo function.json.

Propriedade function.json	Descrição
type	Obrigatórios. Deve ser definido como kusto.
direction	Obrigatórios. Deve ser definido como in.
name	Obrigatórios. O nome da variável que representa os resultados da consulta no código da função.
Banco de Dados	Obrigatórios. O banco de dados no qual a consulta deve ser executada.
connection	Obrigatórios. O nome da variável que contém a cadeia de conexão, resolvida por meio de variáveis de ambiente ou por meio de configurações do aplicativo de funções. O padrão é pesquisar na variável KustoConnectionString. No runtime, essa variável é pesquisada no ambiente. A cadeia de conexão está documentada nas cadeias de conexão do Kusto. Por exemplo: "KustoConnectionString": "Data Source=https://your_cluster.kusto.windows.net;Database=your_Database;Fed=True;AppClientId=your_AppId;AppKey=your_AppKey;Authority Id=your_TenantId.
kqlCommand	Obrigatórios. O parâmetro KqlQuery que deve ser executado. Pode ser uma consulta KQL ou uma chamada de função KQL.
kqlParameters	Opcional. Parâmetros que atuam como variáveis de predicado para KqlCommand. Por exemplo, "@name={name},@Id={id}", em que os parâmetros{name} e {id} são substituídos em runtime por valores reais que atuam como predicados. Nem o nome nem o valor do parâmetro podem conter uma vírgula (,) ou um sinal de igual (=).
managedServiceIdentity	Uma identidade gerenciada pode ser usada para se conectar ao Azure Data Explorer. Para usar uma identidade gerenciada pelo sistema, use "system". Todos os outros nomes de identidade são interpretados como identidade gerenciada pelo usuário.

Quando você estiver desenvolvendo localmente, adicione as configurações do aplicativo no arquivo local.settings.json na coleção Values.

Uso

O construtor do atributo usa o banco de dados e os atributos KQLCommand e KQLParameters e o nome da configuração de conexão. O KQLCommand pode ser uma instrução KQL ou uma função KQL. O nome da configuração da cadeia de conexão corresponde à configuração do aplicativo (em local.settings.json para desenvolvimento local) que contém as cadeias de conexão Kusto. Por exemplo: "KustoConnectionString": "Data Source=https://your_cluster.kusto.windows.net;Database=your_Database;Fed=True;AppClientId=your_AppId;AppKey=your_AppKey;Authority Id=your_TenantId. As consultas executadas pela associação de entrada são parametrizadas. Os valores fornecidos nos parâmetros KQL são usados em runtime.

Próximas etapas

Salvar dados em uma tabela (associação de saída)