Associazioni di input di tabelle di Azure per Funzioni di Azure

Usare l'associazione di input tabelle di Azure per leggere una tabella in Azure Cosmos DB per Tabelle o Archiviazione tabelle di Azure.

Per informazioni sui dettagli di impostazione e configurazione, vedere la panoramica.

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

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 libreria di classi di processo di lavoro isolata compilata C# viene eseguita in un processo isolato dal runtime.

Scegliere una versione per visualizzare esempi per la modalità e la versione.

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, legge una chiave di riga dalla coda, che viene usata per ottenere la riga dalla tabella di input. L'espressione {queueTrigger} associa la chiave di riga ai metadati del messaggio, ovvero la stringa del messaggio.

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

La funzione attivata dalla coda seguente restituisce le prime 5 entità come IEnumerable<T>, con il valore della chiave di partizione impostato come messaggio della coda.

[Function("TestFunction")]
public static void Run([QueueTrigger("myqueue", Connection = "AzureWebJobsStorage")] string partition,
    [TableInput("inTable", "{queueTrigger}", Take = 5, Filter = "Text eq 'test'", 
    Connection = "AzureWebJobsStorage")] IEnumerable<MyTableData> tableInputs,
    FunctionContext context)
{
    var logger = context.GetLogger("TestFunction");
    logger.LogInformation(partition);
    foreach (MyTableData tableInput in tableInputs)
    {
        logger.LogInformation($"PK={tableInput.PartitionKey}, RK={tableInput.RowKey}, Text={tableInput.Text}");
    }
}

Le Filter proprietà e Take vengono usate per limitare il numero di entità restituite.

Nell'esempio seguente viene illustrata una funzione attivata da HTTP che restituisce un elenco di oggetti persona che si trovano in una partizione specificata nell'archiviazione tabelle. Nell'esempio la chiave di partizione viene estratta dalla route HTTP e tableName e la connessione provengono dalle impostazioni della funzione.

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

@FunctionName("getPersonsByPartitionKey")
public Person[] get(
        @HttpTrigger(name = "getPersons", methods = {HttpMethod.GET}, authLevel = AuthorizationLevel.FUNCTION, route="persons/{partitionKey}") HttpRequestMessage<Optional<String>> request,
        @BindingName("partitionKey") String partitionKey,
        @TableInput(name="persons", partitionKey="{partitionKey}", tableName="%MyTableName%", connection="MyConnectionString") Person[] persons,
        final ExecutionContext context) {

    context.getLogger().info("Got query for person related to persons with partition key: " + partitionKey);

    return persons;
}

L'annotazione TableInput può anche estrarre le associazioni dal corpo json della richiesta, come illustrato nell'esempio seguente.

@FunctionName("GetPersonsByKeysFromRequest")
public HttpResponseMessage get(
        @HttpTrigger(name = "getPerson", methods = {HttpMethod.GET}, authLevel = AuthorizationLevel.FUNCTION, route="query") HttpRequestMessage<Optional<String>> request,
        @TableInput(name="persons", partitionKey="{partitionKey}", rowKey = "{rowKey}", tableName="%MyTableName%", connection="MyConnectionString") Person person,
        final ExecutionContext context) {

    if (person == null) {
        return request.createResponseBuilder(HttpStatus.NOT_FOUND)
                    .body("Person not found.")
                    .build();
    }

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

L'esempio seguente usa un filtro per eseguire una query per le persone con un nome specifico in una tabella di Azure e limita il numero di corrispondenze possibili a 10 risultati.

@FunctionName("getPersonsByName")
public Person[] get(
        @HttpTrigger(name = "getPersons", methods = {HttpMethod.GET}, authLevel = AuthorizationLevel.FUNCTION, route="filter/{name}") HttpRequestMessage<Optional<String>> request,
        @BindingName("name") String name,
        @TableInput(name="persons", filter="Name eq '{name}'", take = "10", tableName="%MyTableName%", connection="MyConnectionString") Person[] persons,
        final ExecutionContext context) {

    context.getLogger().info("Got query for person related to persons with name: " + name);

    return persons;
}

Nell'esempio seguente viene illustrata un'associazione di input di tabella che usa un trigger della coda per leggere una singola riga di tabella. L'associazione specifica un partitionKey oggetto e un oggetto rowKey. Il valore rowKey "{queueTrigger}" indica che la chiave della riga proviene dalla stringa di messaggio della coda.

import { app, input, InvocationContext } from '@azure/functions';

const tableInput = input.table({
    tableName: 'Person',
    partitionKey: 'Test',
    rowKey: '{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

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

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    context.log('Node.js queue trigger function processed work item', queueItem);
    const person = <PersonEntity>context.extraInputs.get(tableInput);
    context.log('Person entity name: ' + person.Name);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [tableInput],
    handler: storageQueueTrigger1,
});
const { app, input } = require('@azure/functions');

const tableInput = input.table({
    tableName: 'Person',
    partitionKey: 'Test',
    rowKey: '{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [tableInput],
    handler: (queueItem, context) => {
        context.log('Node.js queue trigger function processed work item', queueItem);
        const person = context.extraInputs.get(tableInput);
        context.log('Person entity name: ' + person.Name);
    },
});

La funzione seguente usa un trigger della coda per leggere una singola riga di tabella come input in una funzione.

In questo esempio, la configurazione dell'associazione specifica un valore esplicito per la tabella e usa un'espressione partitionKey per passare all'oggetto rowKey. L'espressione rowKey , {queueTrigger}, indica che la chiave di riga proviene dalla stringa del messaggio della coda.

Configurazione dell'associazione in function.json:

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "MyQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "PersonEntity",
      "type": "table",
      "tableName": "Person",
      "partitionKey": "Test",
      "rowKey": "{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    }
  ],
  "disabled": false
}

Codice di PowerShell in run.ps1:

param($MyQueueItem, $PersonEntity, $TriggerMetadata)
Write-Host "PowerShell queue trigger function processed work item: $MyQueueItem"
Write-Host "Person entity name: $($PersonEntity.Name)"

La funzione seguente usa un trigger HTTP per leggere una singola riga di tabella come input in una funzione.

In questo esempio, la configurazione dell'associazione specifica un valore esplicito per la tabella e usa un'espressione partitionKey per passare all'oggetto rowKey. L'espressione rowKey indica {id} che la chiave di riga proviene dalla {id} parte della route nella richiesta.

Configurazione dell'associazione nel file function.json :

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

Codice Python nel file __init__.py :

import json

import azure.functions as func

def main(req: func.HttpRequest, messageJSON) -> func.HttpResponse:

    message = json.loads(messageJSON)
    return func.HttpResponse(f"Table row: {messageJSON}")

Con questa semplice associazione, non è possibile gestire a livello di codice un caso in cui non viene trovata alcuna riga con ID chiave di riga. Per una selezione più dettagliata dei dati, usare l'SDK di archiviazione.


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.
PartitionKey Facoltativo. Chiave di partizione dell'entità della tabella da leggere.
RowKey Facoltativo. Chiave di riga dell'entità della tabella da leggere.
Take Facoltativo. Numero massimo di entità da leggere in un oggetto IEnumerable<T>. Non può essere usato con RowKey.
Filtra Facoltativo. Espressione di filtro OData per le entità da leggere in un oggetto IEnumerable<T>. Non può essere usato con RowKey.
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 di funzioni Java, usare @TableInput l'annotazione per i parametri il cui valore deriva dall’archiviazione tabelle. Questa annotazione è utilizzabile con i tipi Java nativi, con oggetti POJO o con valori nullable tramite Optional<T>. Questa annotazione supporta gli elementi seguenti:

Elemento Descrizione
name Nome della variabile che rappresenta la tabella o l'entità nel codice della funzione.
tableName Nome della tabella.
partitionKey Facoltativo. Chiave di partizione dell'entità della tabella da leggere.
rowKey Facoltativo. Chiave di riga dell'entità della tabella da leggere.
take Facoltativo. Numero massimo di entità da leggere.
filter Facoltativo. Espressione di filtro OData per l'input della tabella.
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 input.table() metodo .

Proprietà Descrizione
tableName Nome della tabella.
partitionKey Facoltativo. Chiave di partizione dell'entità della tabella da leggere.
rowKey Facoltativo. Chiave di riga dell'entità della tabella da leggere. Non è possibile usare con take o filter.
take Facoltativo. Numero massimo di entità da restituire. Non può essere usato con rowKey.
filter Facoltativo. Espressione di filtro OData per le entità da restituire dalla tabella. Non può essere usato con rowKey.
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 in. Questa proprietà viene impostata automaticamente quando si crea l'associazione nel portale di Azure.
name Nome della variabile che rappresenta la tabella o l'entità nel codice della funzione.
tableName Nome della tabella.
partitionKey Facoltativo. Chiave di partizione dell'entità della tabella da leggere.
rowKey Facoltativo. Chiave di riga dell'entità della tabella da leggere. Non è possibile usare con take o filter.
take Facoltativo. Numero massimo di entità da restituire. Non può essere usato con rowKey.
filter Facoltativo. Espressione di filtro OData per le entità da restituire dalla tabella. Non può essere usato con rowKey.
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 usa una singola entità di tabella, l'associazione di input tabelle di Azure può essere associata ai tipi seguenti:

Tipo Descrizione
Tipo serializzabile JSON che implementa ITableEntity Funzioni tenta di deserializzare l'entità in un tipo POCO (Plain-Old CLR Object). Il tipo deve implementare ITableEntity o avere una proprietà stringa RowKey e una proprietà stringa PartitionKey .
TableEntity1 Entità come tipo di dizionario.

Quando si usano più entità da una query, l'associazione di input tabelle di Azure può essere associata ai tipi seguenti:

Tipo Descrizione
IEnumerable<T> dove T implementa ITableEntity Enumerazione delle entità restituite dalla query. Ogni voce rappresenta un'entità. Il tipo T deve implementare ITableEntity o avere una proprietà stringa RowKey e una proprietà stringa PartitionKey .
TableClient1 Un client connesso alla tabella. Ciò offre il controllo più importante per l'elaborazione della tabella e può essere usato per scrivervi se la connessione dispone di autorizzazioni sufficienti.

1 Per usare questi tipi, è necessario fare riferimento a Microsoft.Azure.Functions.Worker.Extensions.Tables 1.2.0 o versioni successive e alle dipendenze comuni per le associazioni di tipi SDK.

L'attributo TableInput consente di accedere alla riga della tabella che ha attivato la funzione.

Ottenere i dati delle righe di input usando context.extraInputs.get().

I dati vengono passati al parametro di input come specificato dalla name chiave nel file function.json . Specificando The partitionKey e rowKey è possibile filtrare in base a record specifici.

I dati della tabella vengono passati alla funzione come stringa JSON. De-serializzare il messaggio chiamando json.loads come illustrato nell'esempio di input.

Per informazioni dettagliate sull'utilizzo, vedere Esempio.

Passaggi successivi