Associações de entrada do Azure Data Explorer para o Azure Functions (visualização)

Artigo
04/07/2024

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

Exemplos

Uma função C# pode ser criada usando um dos seguintes modos C#:

Modelo de trabalho isolado: função C# compilada que é executada em um processo de trabalho isolado do tempo de execução. O processo de trabalho isolado é necessário para suportar funções C# em execução nas versões LTS e não-LTS .NET e .NET Framework.
Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions.
Script C#: usado principalmente quando você cria 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 total.

Modelo de trabalhador isolado
Modelo em processo

Mais exemplos para a vinculação de entrada do Azure Data Explorer (fora do processo) estão disponíveis no repositório GitHub.

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

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

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

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

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

Nota

O parâmetro HTTP query string 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 route

O exemplo a seguir mostra uma função C# que recupera registros retornados pela consulta (com base no nome do produto, neste caso). A função é acionada por uma solicitação HTTP que usa dados de 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;
        }
    }
}

Mais exemplos para a 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 linhas por ID da cadeia de caracteres de consulta
Gatilho HTTP, obter várias linhas de dados de rota

Os exemplos referem-se à classe e a Product 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 da cadeia de caracteres de consulta

O exemplo a seguir mostra uma função C# que recupera uma lista de produtos com uma ID de produto. A função é acionada por uma solicitação HTTP que usa um parâmetro para o ID. Esse ID é usado para recuperar uma Product lista que corresponde à consulta.

Nota

O parâmetro HTTP query string 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 route

O exemplo a seguir mostra uma função C# que recupera documentos retornados pela consulta. A função é acionada por uma solicitação HTTP que usa dados de rota para especificar o valor de um parâmetro de função KQL. A função GetProductsByName simples recupera um conjunto de produtos que correspondem ao nome de um 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 para a vinculação de entrada do Java Azure Data Explorer estão disponíveis no repositório GitHub.

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

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

Os exemplos referem-se a uma Product classe (em um arquivo Product.javaseparado) 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 route 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 da cadeia de caracteres de consulta

O exemplo a seguir mostra uma consulta para a tabela de produtos pelo nome do produto. A função é acionada 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 para a 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 da cadeia de caracteres de consulta

Os exemplos referem-se 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 JavaScript que lê de uma consulta e retorna os resultados na resposta HTTP.

Os seguintes dados de ligação estão 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 de configuração explica essas propriedades.

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

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

Gatilho HTTP, obter linha por nome da cadeia de caracteres de consulta

Os seguintes dados de ligação estão 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 de configuração explica essas propriedades.

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

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

Mais exemplos para a 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 usando 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 Python que lê de uma consulta e retorna os resultados na resposta HTTP.

Os seguintes dados de ligação estão 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 de configuração explica essas propriedades.

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

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 da cadeia de caracteres de consulta

Os seguintes dados de ligação estão 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 de configuração explica essas propriedades.

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

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 Attribute	Description
Base de Dados	Obrigatório. O banco de dados no qual a consulta deve ser executada.
Connection	Obrigatório. 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 de aplicativo de função. O padrão é procurar a variável `KustoConnectionString`. No tempo de execução, essa variável é analisada em relação ao ambiente. A documentação sobre a cadeia de conexão está em 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`.
KqlComando	Obrigatório. O `KqlQuery` parâmetro que deve ser executado. Pode ser uma consulta KQL ou uma chamada de função KQL.
KqlParâmetros	Opcional. Parâmetros que atuam como variáveis de predicado para `KqlCommand`. Por exemplo, "@name={name},@Id={id}", onde {name} e {id} são substituídos em tempo de execução por valores reais atuando como predicados. O nome do parâmetro e o valor do parâmetro não podem conter uma vírgula (`,`) ou um sinal de igual (`=`).
ManagedServiceIdentity	Opcional. Você pode usar uma identidade gerenciada para se conectar ao Azure Data Explorer. Para usar uma identidade gerenciada pelo sistema, use "system". Quaisquer outros nomes de identidade são interpretados como uma identidade gerenciada pelo usuário.

Anotações

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

Elemento	Description
nome	Necessário. O nome da variável que representa a consulta resulta em código de função.
base de dados	Obrigatório. O banco de dados no qual a consulta deve ser executada.
ligação	Obrigatório. 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 de aplicativo de função. O padrão é procurar a variável `KustoConnectionString`. No tempo de execução, essa variável é analisada em relação ao ambiente. A documentação sobre a cadeia de conexão está em 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`.
kqlComando	Obrigatório. O `KqlQuery` parâmetro que deve ser executado. Pode ser uma consulta KQL ou uma chamada de função KQL.
kqlParâmetros	Opcional. Parâmetros que atuam como variáveis de predicado para `KqlCommand`. Por exemplo, "@name={name},@Id={id}", onde {name} e {id} são substituídos em tempo de execução por valores reais atuando como predicados. O nome do parâmetro e o valor do parâmetro não 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". Quaisquer outros nomes de identidade são interpretados como uma identidade gerenciada pelo usuário.

Configuração

A tabela a seguir explica as propriedades de configuração de associação definidas no arquivo function.json .

function.json propriedade	Description
tipo	Necessário. Deve ser definido como `kusto`.
direção	Obrigatório. Deve ser definido como `in`.
nome	Necessário. O nome da variável que representa a consulta resulta em código de função.
base de dados	Obrigatório. O banco de dados no qual a consulta deve ser executada.
ligação	Obrigatório. 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 de aplicativo de função. O padrão é procurar a variável `KustoConnectionString`. No tempo de execução, essa variável é analisada em relação ao ambiente. A documentação sobre a cadeia de conexão está em 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`.
kqlComando	Obrigatório. O `KqlQuery` parâmetro que deve ser executado. Pode ser uma consulta KQL ou uma chamada de função KQL.
kqlParâmetros	Opcional. Parâmetros que atuam como variáveis de predicado para `KqlCommand`. Por exemplo, "@name={name},@Id={id}", onde {name} e {id} são substituídos em tempo de execução por valores reais atuando como predicados. O nome do parâmetro e o valor do parâmetro não 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". Quaisquer outros nomes de identidade são interpretados como uma identidade gerenciada pelo usuário.

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

Utilização

O construtor do atributo usa o banco de dados e os atributos KQLCommand e KQLParameters o nome da configuração de conexão. O comando KQL 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 (para local.settings.json 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 tempo de execução.

Próximos passos

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

Associações de entrada do Azure Data Explorer para o Azure Functions (visualização)

Exemplos

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

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

Gatilho HTTP, obter várias linhas

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

Gatilho HTTP, obter várias linhas

Gatilho HTTP, obter linha por nome da cadeia de caracteres de consulta

Gatilho HTTP, obter várias linhas

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

Atributos

Anotações

Configuração

Utilização

Próximos passos

Recursos adicionais