Associações de saída de Tabelas do Azure para o Azure Functions

  • Artigo

Use uma associação de saída de Tabelas do Azure para gravar entidades em uma tabela no Azure Cosmos DB para Tabela ou Armazenamento de Tabela do Azure.

Para obter informações sobre detalhes de instalação e configuração, consulte a visão geral

Nota

Essa associação de saída oferece suporte apenas à criação de novas entidades em uma tabela. Se você precisar atualizar uma entidade existente do seu código de função, use um SDK de Tabelas do Azure diretamente.

Importante

Este artigo usa guias para oferecer suporte a várias versões do modelo de programação Node.js. O modelo v4 está geralmente disponível e foi projetado para ter uma experiência mais flexível e intuitiva para desenvolvedores JavaScript e TypeScript. Para obter mais detalhes sobre como o modelo v4 funciona, consulte o Guia do desenvolvedor do Azure Functions Node.js. Para saber mais sobre as diferenças entre v3 e v4, consulte o guia de migração.

Exemplo

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. As extensões para funções isoladas do processo de trabalho usam Microsoft.Azure.Functions.Worker.Extensions.* namespaces.
  • Modelo em processo: função C# compilada que é executada no mesmo processo que o tempo de execução do Functions. Em uma variação desse modelo, as funções podem ser executadas usando scripts em C#, que são suportados principalmente para edição de portal em C#. As extensões para funções em processo usam Microsoft.Azure.WebJobs.Extensions.* namespaces.

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.

A classe a seguir MyTableData representa uma linha de dados na tabela:

public class MyTableData : Azure.Data.Tables.ITableEntity
{
    public string Text { get; set; }

    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public DateTimeOffset? Timestamp { get; set; }
    public ETag ETag { get; set; }
}

A função a seguir, que é iniciada por um gatilho de armazenamento de fila, grava uma nova MyDataTable entidade em uma tabela chamada OutputTable.

[Function("TableFunction")]
[TableOutput("OutputTable", Connection = "AzureWebJobsStorage")]
public static MyTableData Run(
    [QueueTrigger("table-items")] string input,
    [TableInput("MyTable", "<PartitionKey>", "{queueTrigger}")] MyTableData tableInput,
    FunctionContext context)
{
    var logger = context.GetLogger("TableFunction");

    logger.LogInformation($"PK={tableInput.PartitionKey}, RK={tableInput.RowKey}, Text={tableInput.Text}");

    return new MyTableData()
    {
        PartitionKey = "queue",
        RowKey = Guid.NewGuid().ToString(),
        Text = $"Output record with rowkey {input} created at {DateTime.Now}"
    };
}

O exemplo a seguir mostra uma função Java que usa um gatilho HTTP para escrever uma única linha de tabela.

public class Person {
    private String PartitionKey;
    private String RowKey;
    private String Name;

    public String getPartitionKey() {return this.PartitionKey;}
    public void setPartitionKey(String key) {this.PartitionKey = key; }
    public String getRowKey() {return this.RowKey;}
    public void setRowKey(String key) {this.RowKey = key; }
    public String getName() {return this.Name;}
    public void setName(String name) {this.Name = name; }
}

public class AddPerson {

    @FunctionName("addPerson")
    public HttpResponseMessage get(
            @HttpTrigger(name = "postPerson", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION, route="persons/{partitionKey}/{rowKey}") HttpRequestMessage<Optional<Person>> request,
            @BindingName("partitionKey") String partitionKey,
            @BindingName("rowKey") String rowKey,
            @TableOutput(name="person", partitionKey="{partitionKey}", rowKey = "{rowKey}", tableName="%MyTableName%", connection="MyConnectionString") OutputBinding<Person> person,
            final ExecutionContext context) {

        Person outPerson = new Person();
        outPerson.setPartitionKey(partitionKey);
        outPerson.setRowKey(rowKey);
        outPerson.setName(request.getBody().get().getName());

        person.setValue(outPerson);

        return request.createResponseBuilder(HttpStatus.OK)
                        .header("Content-Type", "application/json")
                        .body(outPerson)
                        .build();
    }
}

O exemplo a seguir mostra uma função Java que usa um gatilho HTTP para escrever várias linhas de tabela.

public class Person {
    private String PartitionKey;
    private String RowKey;
    private String Name;

    public String getPartitionKey() {return this.PartitionKey;}
    public void setPartitionKey(String key) {this.PartitionKey = key; }
    public String getRowKey() {return this.RowKey;}
    public void setRowKey(String key) {this.RowKey = key; }
    public String getName() {return this.Name;}
    public void setName(String name) {this.Name = name; }
}

public class AddPersons {

    @FunctionName("addPersons")
    public HttpResponseMessage get(
            @HttpTrigger(name = "postPersons", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION, route="persons/") HttpRequestMessage<Optional<Person[]>> request,
            @TableOutput(name="person", tableName="%MyTableName%", connection="MyConnectionString") OutputBinding<Person[]> persons,
            final ExecutionContext context) {

        persons.setValue(request.getBody().get());

        return request.createResponseBuilder(HttpStatus.OK)
                        .header("Content-Type", "application/json")
                        .body(request.getBody().get())
                        .build();
    }
}

O exemplo a seguir mostra uma ligação de saída de tabela que grava várias entidades de tabela.

import { app, HttpRequest, HttpResponseInit, InvocationContext, output } from '@azure/functions';

const tableOutput = output.table({
    tableName: 'Person',
    connection: 'MyStorageConnectionAppSetting',
});

interface PersonEntity {
    PartitionKey: string;
    RowKey: string;
    Name: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const rows: PersonEntity[] = [];
    for (let i = 1; i < 10; i++) {
        rows.push({
            PartitionKey: 'Test',
            RowKey: i.toString(),
            Name: `Name ${i}`,
        });
    }
    context.extraOutputs.set(tableOutput, rows);
    return { status: 201 };
}

app.http('httpTrigger1', {
    methods: ['POST'],
    authLevel: 'anonymous',
    extraOutputs: [tableOutput],
    handler: httpTrigger1,
});

const { app, output } = require('@azure/functions');

const tableOutput = output.table({
    tableName: 'Person',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['POST'],
    authLevel: 'anonymous',
    extraOutputs: [tableOutput],
    handler: async (request, context) => {
        const rows = [];
        for (let i = 1; i < 10; i++) {
            rows.push({
                PartitionKey: 'Test',
                RowKey: i.toString(),
                Name: `Name ${i}`,
            });
        }
        context.extraOutputs.set(tableOutput, rows);
        return { status: 201 };
    },
});

O exemplo a seguir demonstra como gravar várias entidades em uma tabela a partir de uma função.

Configuração de vinculação em function.json:

{
  "bindings": [
    {
      "name": "InputData",
      "type": "manualTrigger",
      "direction": "in"
    },
    {
      "tableName": "Person",
      "connection": "MyStorageConnectionAppSetting",
      "name": "TableBinding",
      "type": "table",
      "direction": "out"
    }
  ],
  "disabled": false
}

Código do PowerShell em run.ps1:

param($InputData, $TriggerMetadata)

foreach ($i in 1..10) {
    Push-OutputBinding -Name TableBinding -Value @{
        PartitionKey = 'Test'
        RowKey = "$i"
        Name = "Name $i"
    }
}

O exemplo a seguir demonstra como usar a associação de saída de armazenamento de tabela. Configure a table associação no function.json atribuindo valores a name, tableName, partitionKeye connection:

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "message",
      "type": "table",
      "tableName": "messages",
      "partitionKey": "message",
      "connection": "AzureWebJobsStorage",
      "direction": "out"
    },
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

A função a seguir gera uma UUI exclusiva para o rowKey valor e persiste a mensagem no armazenamento de tabela.

import logging
import uuid
import json

import azure.functions as func

def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:

    rowKey = str(uuid.uuid4())

    data = {
        "Name": "Output binding message",
        "PartitionKey": "message",
        "RowKey": rowKey
    }

    message.set(json.dumps(data))

    return func.HttpResponse(f"Message created with the rowKey: {rowKey}")

Atributos

As bibliotecas C# do processo de trabalho em processo e isoladas usam atributos para definir a função. Em vez disso, o script C# usa um arquivo de configuração function.json, conforme descrito no guia de script C#.

Em bibliotecas de classe C#, o TableInputAttribute suporta as seguintes propriedades:

Propriedade Attribute Description
TableName O nome da tabela na qual escrever.
PartitionKey A chave de partição da entidade da tabela a ser gravada.
Chave de linha A chave de linha da entidade da tabela a ser gravada.
Ligação O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao serviço de tabela. Consulte Conexões.

Anotações

Na biblioteca de tempo de execução de funções Java, use a anotação TableOutput em parâmetros para gravar valores em suas tabelas. O atributo suporta os seguintes elementos:

Elemento Description
Designação O nome da variável usada no código da função que representa a tabela ou entidade.
Tipo de dados Define como o tempo de execução do Functions deve tratar o valor do parâmetro. Para saber mais, consulte dataType.
nome_da_tabela O nome da tabela na qual escrever.
partitionKey A chave de partição da entidade da tabela a ser gravada.
rowKey [en] A chave de linha da entidade da tabela a ser gravada.
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao serviço de tabela. Consulte Conexões.

Configuração

A tabela a seguir explica as propriedades que você pode definir no options objeto passado para o output.table() método.

Property Description
nome_da_tabela O nome da tabela na qual escrever.
partitionKey A chave de partição da entidade da tabela a ser gravada.
rowKey [en] A chave de linha da entidade da tabela a ser gravada.
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao serviço de tabela. Consulte Conexões.

Configuração

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

function.json propriedade Description
type Deve ser definido como table. Essa propriedade é definida automaticamente quando você cria a associação no portal do Azure.
direção Deve ser definido como out. Essa propriedade é definida automaticamente quando você cria a associação no portal do Azure.
Designação O nome da variável usada no código da função que representa a tabela ou entidade. Defina como $return para fazer referência ao valor de retorno da função.
nome_da_tabela O nome da tabela na qual escrever.
partitionKey A chave de partição da entidade da tabela a ser gravada.
rowKey [en] A chave de linha da entidade da tabela a ser gravada.
conexão O nome de uma configuração de aplicativo ou coleção de configurações que especifica como se conectar ao serviço de tabela. Consulte Conexões.

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

Ligações

A connection propriedade é uma referência à configuração do ambiente que especifica como o aplicativo deve se conectar ao seu serviço de tabela. Pode especificar:

Se o valor configurado for uma correspondência exata para uma única configuração e uma correspondência de prefixo para outras configurações, a correspondência exata será usada.

Connection string

Para obter uma cadeia de conexão para tabelas no armazenamento de tabelas do Azure, siga as etapas mostradas em Gerenciar chaves de acesso da conta de armazenamento. Para obter uma cadeia de conexão para tabelas no Azure Cosmos DB for Table, siga as etapas mostradas nas Perguntas frequentes do Azure Cosmos DB for Table.

Essa cadeia de conexão deve ser armazenada em uma configuração de aplicativo com um nome correspondente ao valor especificado pela connection propriedade da configuração de ligação.

Se o nome da configuração do aplicativo começar com "AzureWebJobs", você poderá especificar apenas o restante do nome aqui. Por exemplo, se você definir connection como "MyStorage", o tempo de execução do Functions procurará uma configuração de aplicativo chamada "AzureWebJobsMyStorage". Se você deixar connection vazio, o tempo de execução do Functions usará a cadeia de conexão de armazenamento padrão na configuração do aplicativo chamada AzureWebJobsStorage.

Conexões baseadas em identidade

Se você estiver usando a extensão da API Tables, em vez de usar uma cadeia de conexão com um segredo, poderá fazer com que o aplicativo use uma identidade do Microsoft Entra. Isso só se aplica ao acessar tabelas no Armazenamento do Azure. Para usar uma identidade, defina as configurações sob um prefixo comum que mapeia para a connection propriedade na configuração de gatilho e ligação.

Se você estiver definindo connection como "AzureWebJobsStorage", consulte Conectando-se ao armazenamento de host com uma identidade. Para todas as outras conexões, a extensão requer as seguintes propriedades:

Property Modelo de variável de ambiente Description Valor de exemplo
URI do serviço de tabela <CONNECTION_NAME_PREFIX>__tableServiceUri1 O URI do plano de dados do serviço de tabela de Armazenamento do Azure ao qual você está se conectando, usando o esquema HTTPS. https://< storage_account_name.table.core.windows.net>

<CONNECTION_NAME_PREFIX>__serviceUri 1 pode ser usado como um alias. Se ambos os formulários forem fornecidos, o tableServiceUri formulário é usado. O serviceUri formulário não pode ser usado quando a configuração geral da conexão deve ser usada em blobs, filas e/ou tabelas.

Outras propriedades podem ser definidas para personalizar a conexão. Consulte Propriedades comuns para conexões baseadas em identidade.

O serviceUri formulário não pode ser usado quando a configuração geral de conexão deve ser usada em blobs, filas e/ou tabelas no Armazenamento do Azure. O URI só pode designar o serviço de tabela. Como alternativa, você pode fornecer um URI especificamente para cada serviço sob o mesmo prefixo, permitindo que uma única conexão seja usada.

Quando hospedadas no serviço Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. A identidade atribuída ao sistema é usada por padrão, embora uma identidade atribuída ao usuário possa ser especificada com as credential propriedades e clientID . Observe que não há suporte para a configuração de uma identidade atribuída pelo usuário com uma ID de recurso. Quando executado em outros contextos, como desenvolvimento local, sua identidade de desenvolvedor é usada, embora isso possa ser personalizado. Consulte Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão à identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços do Azure, isso significa que você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem essas permissões.

Importante

Algumas permissões podem ser expostas pelo serviço de destino que não são necessárias para todos os contextos. Sempre que possível, aderir ao princípio do menor privilégio, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo só precisa ser capaz de ler de uma fonte de dados, use uma função que só tenha permissão para ler. Seria inadequado atribuir uma função que também permita escrever a esse serviço, pois isso seria uma permissão excessiva para uma operação de leitura. Da mesma forma, convém garantir que a atribuição de função tenha escopo apenas sobre os recursos que precisam ser lidos.

Você precisará criar uma atribuição de função que forneça acesso ao seu serviço de tabela do Armazenamento do Azure em tempo de execução. Funções de gerenciamento como Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão Tabelas do Azure no Armazenamento do Azure em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código que você escreve.

Tipo de vinculação Exemplo de funções internas (Armazenamentodo Azure 1)
Vinculação de entrada Leitor de dados da tabela de armazenamento
Vinculação de saída Contribuidor de dados da tabela de armazenamento

1 Se, em vez disso, seu aplicativo estiver se conectando a tabelas no Azure Cosmos DB for Table, o uso de uma identidade não será suportado e a conexão deverá usar uma cadeia de conexão.

Utilização

O uso da associação depende da versão do pacote de extensão e da modalidade C# usada em seu aplicativo de função, que pode ser uma das seguintes:

Uma biblioteca de classes de processo de trabalho isolada compilada função C# é executada em um processo isolado do tempo de execução.

Escolha uma versão para ver os detalhes de uso do modo e da versão.

Quando você deseja que a função grave em uma única entidade, a associação de saída Tabelas do Azure pode se vincular aos seguintes tipos:

Tipo Description
Um tipo serializável JSON que implementa [ITableEntity] As funções tentam serializar um tipo de objeto CLR (POCO) simples como a entidade. O tipo deve implementar [ITableEntity] ou ter uma propriedade string RowKey e uma propriedade string PartitionKey .

Quando você deseja que a função grave em várias entidades, a associação de saída Tabelas do Azure pode se vincular aos seguintes tipos:

Tipo Description
T[] onde T é um dos tipos de entidade única Uma matriz que contém várias entidades. Cada entrada representa uma entidade.

Para outros cenários de saída, crie e use tipos de Azure.Data.Tables diretamente.

Há duas opções para a saída de uma linha de armazenamento de tabela de uma função usando a anotação TableStorageOutput :

Opções Description
Valor de retorno Ao aplicar a anotação à própria função, o valor de retorno da função persiste como uma linha de armazenamento de tabela.
Imperativo Para definir explicitamente a linha da tabela, aplique a anotação a um parâmetro específico do tipo OutputBinding<T>, onde T inclui as PartitionKey propriedades e RowKey . Você pode acompanhar essas propriedades implementando ITableEntity ou herdando TableEntity.

Defina os dados da linha de saída retornando o valor ou usando context.extraOutputs.set().

Para gravar dados na tabela, use o Push-OutputBinding cmdlet, defina o parâmetro e -Value o -Name TableBinding parâmetro iguais aos dados da linha. Consulte o exemplo do PowerShell para obter mais detalhes.

Há duas opções para enviar uma mensagem de linha de armazenamento de tabela de uma função:

Opções Description
Valor de retorno Defina a name propriedade em function.json como $return. Com essa configuração, o valor de retorno da função persiste como uma linha de armazenamento de tabela.
Imperativo Passe um valor para o método set do parâmetro declarado como um tipo out . O valor passado para set é persistido como linha da tabela.

Para obter detalhes de uso específicos, consulte Exemplo.

Exceções e códigos de devolução

Enlace Referência
Tabela Códigos de erro de tabela
Blob, Tabela, Fila Códigos de erro de armazenamento
Blob, Tabela, Fila Resolução de problemas

Próximos passos

Saiba mais sobre funções, gatilhos e associações do Azure