Condividi tramite

Associazioni di output delle tabelle di Azure per Funzioni di Azure

  • Articolo

Usare un'associazione di output tabelle di Azure per scrivere entità in una tabella in Azure Cosmos DB per Tabelle o Archiviazione tabelle di Azure.

Per informazioni sull'installazione e sulla configurazione, vedere la panoramica

Nota

Questa associazione di output supporta solo la creazione di nuove entità in una tabella. Se è necessario aggiornare un'entità esistente dal codice della funzione, usare invece direttamente Azure Tables SDK.

Importante

Questo articolo usa schede per supportare le versioni diverse del modello di programmazione Node.js. Il modello v4 è disponibile a livello generale ed è progettato per offrire un'esperienza più flessibile e intuitiva per gli sviluppatori JavaScript e TypeScript. Per altre informazioni sul funzionamento del modello v4, vedere la guida per gli sviluppatori di Node.js per Funzioni di Azure. Altre informazioni sulle differenze tra i modelli v3 e v4 sono disponibili nella guida alla migrazione.

Esempio

È possibile creare una funzione C# usando una delle modalità C# seguenti:

  • Modello di lavoro isolato: funzione C# compilata eseguita in un processo di lavoro isolato dal runtime. Il processo di lavoro isolato è necessario per supportare le funzioni C# in esecuzione in LTS e versioni non LTS .NET e .NET Framework. Le estensioni per le funzioni del processo di lavoro isolato usano Microsoft.Azure.Functions.Worker.Extensions.* spazi dei nomi.
  • Modello in-process: funzione C# compilata eseguita nello stesso processo del runtime di Funzioni. In una variante di questo modello, le funzioni possono essere eseguite usando script C#, che è supportato principalmente per la modifica del portale C#. Le estensioni per le funzioni in-process usano Microsoft.Azure.WebJobs.Extensions.* spazi dei nomi.

Importante

Il supporto terminerà per il modello in-process il 10 novembre 2026. È consigliabile eseguire la migrazione delle app al modello di lavoro isolato per il supporto completo.

La classe seguente MyTableData rappresenta una riga di dati nella tabella:

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; }
}

La funzione seguente, avviata da un trigger di archiviazione code, scrive una nuova MyDataTable entità in una tabella denominata 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}"
    };
}

L'esempio seguente illustra una funzione Java che usa un trigger HTTP per scrivere una singola riga di tabella.

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();
    }
}

L'esempio seguente illustra una funzione Java che usa un trigger HTTP per scrivere più righe di tabella.

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();
    }
}

Nell'esempio seguente viene illustrata un'associazione di output di tabella che scrive più entità di tabella.

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 };
    },
});

Nell'esempio seguente viene illustrato come scrivere più entità in una tabella da una funzione.

Configurazione dell'associazione in function.json:

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

Codice di PowerShell in run.ps1:

param($InputData, $TriggerMetadata)

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

Nell'esempio seguente viene illustrato come usare l'associazione di output dell'archiviazione tabelle. Configurare l'associazione nel function.json assegnando valori a name, tableNamepartitionKey, e connection: table

{
  "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"
    }
  ]
}

La funzione seguente genera un'interfaccia utente univoca per il rowKey valore e salva in modo permanente il messaggio nell'archiviazione tabelle.

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

Attributi

Sia le librerie C# in-process che il processo di lavoro isolato usano attributi per definire la funzione. Lo script C# usa invece un file di configurazione function.json come descritto nella guida per gli script C#.

Nelle librerie diTableInputAttribute classi C# supporta le proprietà seguenti:

Proprietà dell'attributo Descrizione
TableName Nome della tabella in cui scrivere.
PartitionKey Chiave di partizione dell'entità della tabella da scrivere.
RowKey Chiave di riga dell'entità della tabella da scrivere.
Connessione Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi al servizio tabelle. Vedere Connessioni.

Annotazioni

Nella libreria di runtime delle funzioni Java usare l'annotazione TableOutput sui parametri per scrivere valori nelle tabelle. L'attributo supporta gli elementi seguenti:

Elemento Descrizione
name Nome della variabile usato nel codice della funzione che rappresenta la tabella o l'entità.
dataType Definisce il modo in cui il runtime di Funzioni deve gestire il valore del parametro. Per altre informazioni, vedere dataType.
tableName Nome della tabella in cui scrivere.
partitionKey Chiave di partizione dell'entità della tabella da scrivere.
rowKey Chiave di riga dell'entità della tabella da scrivere.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi al servizio tabelle. Vedere Connessioni.

Impostazione

Nella tabella seguente vengono illustrate le proprietà che è possibile impostare sull'oggetto options passato al output.table() metodo .

Proprietà Descrizione
tableName Nome della tabella in cui scrivere.
partitionKey Chiave di partizione dell'entità della tabella da scrivere.
rowKey Chiave di riga dell'entità della tabella da scrivere.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi al servizio tabelle. Vedere Connessioni.

Impostazione

Nella tabella seguente sono illustrate le proprietà di configurazione dell'associazione impostate nel file function.json.

Proprietà di function.json Descrizione
type Deve essere impostato su table. Questa proprietà viene impostata automaticamente quando si crea l'associazione nel portale di Azure.
direction Deve essere impostato su out. Questa proprietà viene impostata automaticamente quando si crea l'associazione nel portale di Azure.
name Nome della variabile usato nel codice della funzione che rappresenta la tabella o l'entità. Impostare su $return per fare riferimento al valore restituito della funzione.
tableName Nome della tabella in cui scrivere.
partitionKey Chiave di partizione dell'entità della tabella da scrivere.
rowKey Chiave di riga dell'entità della tabella da scrivere.
connection Nome di un'impostazione o di una raccolta di impostazioni dell'app che specifica come connettersi al servizio tabelle. Vedere Connessioni.

Quando si sviluppa in locale, aggiungere le impostazioni dell'applicazione nel file local.settings.json nella Values raccolta.

Connessioni

La connection proprietà è un riferimento alla configurazione dell'ambiente che specifica come l'app deve connettersi al servizio tabelle. Può specificare:

Se il valore configurato è una corrispondenza esatta per una singola impostazione e una corrispondenza di prefisso per altre impostazioni, viene usata la corrispondenza esatta.

Stringa di connessione

Per ottenere un stringa di connessione per le tabelle nell'archiviazione tabelle di Azure, seguire la procedura illustrata in Gestire le chiavi di accesso dell'account di archiviazione. Per ottenere un stringa di connessione per le tabelle in Azure Cosmos DB per tabella, seguire la procedura illustrata nelle domande frequenti su Azure Cosmos DB per la tabella.

Questo stringa di connessione deve essere archiviato in un'impostazione dell'applicazione con un nome corrispondente al valore specificato dalla connection proprietà della configurazione dell'associazione.

Se il nome dell'impostazione dell'app inizia con "AzureWebJobs", è possibile specificare solo il resto del nome. Ad esempio, se si imposta connection su "MyStorage", il runtime di Funzioni cerca un'impostazione dell'app denominata "AzureWebJobsMyStorage". Se si lascia vuoto connection, il runtime di Funzioni di Azure usa la stringa di connessione di archiviazione predefinita nell'impostazione dell'app denominata AzureWebJobsStorage.

Connessioni basate su identità

Se si usa l'estensione dell'API Tabelle, anziché usare un stringa di connessione con un segreto, è possibile che l'app usi un'identità Microsoft Entra. Questo vale solo quando si accede alle tabelle in Archiviazione di Azure. Per usare un'identità, definire le impostazioni con un prefisso comune che esegue il connection mapping alla proprietà nella configurazione del trigger e dell'associazione.

Se si imposta connection su "AzureWebJobsStorage", vedere Connessione all'archiviazione host con un'identità. Per tutte le altre connessioni, l'estensione richiede le proprietà seguenti:

Proprietà Modello di variabile di ambiente Descrizione Valore di esempio
URI del servizio tabelle <CONNECTION_NAME_PREFIX>__tableServiceUri1 URI del piano dati del servizio tabelle Archiviazione di Azure a cui ci si connette usando lo schema HTTPS. https://<storage_account_name>.table.core.windows.net

1 <CONNECTION_NAME_PREFIX>__serviceUri può essere usato come alias. Se vengono forniti entrambi i moduli, viene utilizzato il tableServiceUri modulo. Il serviceUri modulo non può essere usato quando la configurazione di connessione complessiva deve essere usata tra BLOB, code e/o tabelle.

È possibile impostare altre proprietà per personalizzare la connessione. Vedere Proprietà comuni per le connessioni basate su identità.

Il serviceUri modulo non può essere usato quando la configurazione di connessione complessiva deve essere usata tra BLOB, code e/o tabelle in Archiviazione di Azure. L'URI può designare solo il servizio tabelle. In alternativa, è possibile fornire un URI specifico per ogni servizio con lo stesso prefisso, consentendo l'uso di una singola connessione.

Quando sono ospitate nel servizio Azure Functions, le connessioni basate su identità usano una identità gestita. Per impostazione predefinita, viene usata l’identità assegnata a livello di sistema, ma è comunque possibile specificare un’identità assegnata dall’utente a cui siano associate le proprietà credential e clientID. Si noti che la configurazione di un'identità assegnata dall'utente con un ID risorsa non è supportata. Quando viene eseguita in altri contesti, ad esempio lo sviluppo locale, viene usata l'identità dello sviluppatore, anche se può essere personalizzata. Vedere Sviluppo locale con connessioni basate su identità.

Concedere l'autorizzazione all'identità

Qualsiasi identità usata deve avere le autorizzazioni necessarie per eseguire le azioni previste. Per la maggior parte dei servizi di Azure, questo significa che è necessario assegnare un ruolo nel controllo degli accessi in base al ruolo di Azure, usando ruoli predefiniti o personalizzati che forniscono tali autorizzazioni.

Importante

È possibile che alcune autorizzazioni esposte dal servizio di destinazione non siano necessarie per tutti i contesti. Laddove possibile, rispettare il principio dei privilegi minimi e concedere all’identità solo i privilegi necessari. Ad esempio, se l'app deve essere in grado di leggere solo da un'origine dati, usare un ruolo che disponga solo dell'autorizzazione per la lettura. Sarebbe inappropriato assegnare un ruolo che consenta anche la scrittura in tale servizio, in quanto sarebbe eccessiva l'autorizzazione per un'operazione di lettura. Analogamente, è consigliabile assicurarsi che l'assegnazione di ruolo sia con ambito solo sulle risorse che devono essere lette.

È necessario creare un'assegnazione di ruolo che fornisca l'accesso al servizio tabelle di Archiviazione di Azure in fase di esecuzione. I ruoli di gestione come Proprietario non sono sufficienti. La tabella seguente illustra i ruoli predefiniti consigliati quando si usa l'estensione Tabelle di Azure per Archiviazione di Azure in un normale funzionamento. L'applicazione potrebbe richiedere autorizzazioni aggiuntive in base al codice scritto.

Tipo di associazione Ruoli predefiniti di esempio (Archiviazione di Azure1)
Associazione di input Lettore dei dati della tabella di archiviazione
Associazione di output Collaboratore ai dati della tabella di archiviazione

1 Se l'app si connette a tabelle in Azure Cosmos DB for Table, l'uso di un'identità non è supportato e la connessione deve usare una stringa di connessione.

Utilizzo

L'utilizzo dell'associazione dipende dalla versione del pacchetto di estensione e dalla modalità C# usata nell'app per le funzioni, che può essere una delle seguenti:

Una funzione C# compilata di libreria di classi di processo di lavoro viene eseguita in un processo isolato dal runtime.

Scegliere una versione per visualizzare i dettagli di utilizzo per la modalità e la versione.

Quando si vuole che la funzione scriva in una singola entità, l'associazione di output tabelle di Azure può essere associata ai tipi seguenti:

Tipo Descrizione
Tipo serializzabile JSON che implementa [ITableEntity] Funzioni tenta di serializzare un tipo POCO (Plain-Old CLR Object) come entità. Il tipo deve implementare [ITableEntity] o avere una proprietà stringa RowKey e una proprietà stringa PartitionKey .

Quando si vuole che la funzione scriva in più entità, l'associazione di output tabelle di Azure può essere associata ai tipi seguenti:

Tipo Descrizione
T[] dove T è uno dei singoli tipi di entità Matrice contenente più entità. Ogni voce rappresenta un'entità.

Per altri scenari di output, creare e usare i tipi direttamente da Azure.Data.Tables .

Sono disponibili due opzioni per l'output di una riga di archiviazione tabelle da una funzione usando l'annotazione TableStorageOutput :

Opzioni Descrizione
Valore restituito Applicando l'annotazione alla funzione stessa, il valore restituito della funzione viene mantenuto come riga di archiviazione tabelle.
Imperativo Per impostare in modo esplicito la riga della tabella, applicare l'annotazione a un parametro specifico del tipo OutputBinding<T>, dove T include le PartitionKey proprietà e RowKey . È possibile accompagnare queste proprietà implementando ITableEntity o ereditando TableEntity.

Impostare i dati delle righe di output restituendo il valore o usando context.extraOutputs.set().

Per scrivere nei dati della tabella, usare il Push-OutputBinding cmdlet , impostare il parametro e -Value il -Name TableBinding parametro uguali ai dati della riga. Per altri dettagli, vedere l'esempio di PowerShell.

Sono disponibili due opzioni per l'output di un messaggio di riga di archiviazione tabelle da una funzione:

Opzioni Descrizione
Valore restituito impostare la proprietà name in function.json su $return. Con questa configurazione, il valore restituito della funzione viene mantenuto come riga di archiviazione tabelle.
Imperativo passare un valore al metodo set del parametro dichiarato come tipo Out. Il valore passato a set viene salvato in modo permanente come riga della tabella.

Per informazioni dettagliate sull'utilizzo, vedere Esempio.

Eccezioni e codici restituiti

Binding Riferimento
Tabella Codici di errore del servizio tabelle
Blob, Table, Queue Codici di errore di archiviazione
Blob, Table, Queue Risoluzione dei problemi

Passaggi successivi

Altre informazioni su trigger e associazioni di Funzioni di Azure