Share via


Azure Tables-invoerbindingen voor Azure Functions

Gebruik de Azure Tables-invoerbinding om een tabel te lezen in Azure Cosmos DB voor Table of Azure Table Storage.

Zie het overzicht voor informatie over het instellen en configureren van details.

Belangrijk

In dit artikel worden tabbladen gebruikt ter ondersteuning van meerdere versies van het Node.js programmeermodel. Het v4-model is algemeen beschikbaar en is ontworpen voor een flexibelere en intuïtievere ervaring voor JavaScript- en TypeScript-ontwikkelaars. Raadpleeg de ontwikkelaarshandleiding voor Azure Functions Node.js voor meer informatie over hoe het v4-model werkt. Raadpleeg de migratiehandleiding voor meer informatie over de verschillen tussen v3 en v4.

Opmerking

Het gebruik van de binding is afhankelijk van de versie van het extensiepakket en de C#-modaliteit die wordt gebruikt in uw functie-app. Dit kan een van de volgende zijn:

Een geïsoleerde werkprocesklassebibliotheek gecompileerde C#-functie wordt uitgevoerd in een proces dat is geïsoleerd van de runtime.

Kies een versie om voorbeelden voor de modus en versie weer te geven.

De volgende MyTableData klasse vertegenwoordigt een rij met gegevens in de tabel:

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

De volgende functie, die wordt gestart door een Queue Storage-trigger, leest een rijsleutel uit de wachtrij, die wordt gebruikt om de rij op te halen uit de invoertabel. De expressie {queueTrigger} verbindt de rijsleutel met de metagegevens van het bericht, de berichttekenreeks.

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

De volgende door wachtrij geactiveerde functie retourneert de eerste vijf entiteiten als een IEnumerable<T>, waarbij de waarde van de partitiesleutel is ingesteld als het wachtrijbericht.

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

De Filter en Take eigenschappen worden gebruikt om het aantal geretourneerde entiteiten te beperken.

In het volgende voorbeeld ziet u een door HTTP geactiveerde functie die een lijst met persoonsobjecten retourneert die zich in een opgegeven partitie in Table Storage bevinden. In het voorbeeld wordt de partitiesleutel uit de HTTP-route geëxtraheerd en zijn de tableName en de verbinding afkomstig van de functie-instellingen.

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

De aantekening van TableInput kan ook de bindingen uit de json-hoofdtekst van de aanvraag extraheren, zoals in het volgende voorbeeld wordt weergegeven.

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

In het volgende voorbeeld wordt een filter gebruikt om een query uit te voeren op personen met een specifieke naam in een Azure-tabel en wordt het aantal mogelijke overeenkomsten beperkt tot 10 resultaten.

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

In het volgende voorbeeld ziet u een tabelinvoerbinding die gebruikmaakt van een wachtrijtrigger om één tabelrij te lezen. De binding geeft een partitionKey en een rowKey. De rowKey waarde {queueTrigger} geeft aan dat de rijsleutel afkomstig is van de tekenreeks voor wachtrijberichten.

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

De volgende functie gebruikt een wachtrijtrigger om één tabelrij als invoer voor een functie te lezen.

In dit voorbeeld geeft de bindingsconfiguratie een expliciete waarde op voor de tabel partitionKey en gebruikt een expressie die moet worden doorgegeven aan de rowKeytabel. De rowKey expressie geeft {queueTrigger}aan dat de rijsleutel afkomstig is van de tekenreeks van het wachtrijbericht.

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

PowerShell-code in run.ps1:

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

De volgende functie gebruikt een HTTP-trigger om één tabelrij als invoer voor een functie te lezen.

In dit voorbeeld geeft de bindingsconfiguratie een expliciete waarde op voor de tabel partitionKey en wordt een expressie gebruikt die moet worden doorgegeven aan de rowKeytabel. De rowKey expressie {id} geeft aan dat de rijsleutel afkomstig is van het {id} deel van de route in de aanvraag.

Bindingsconfiguratie in het function.json-bestand :

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

Python-code in het bestand __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}")

Met deze eenvoudige binding kunt u niet programmatisch omgaan met een geval waarin geen rij met een rijsleutel-id wordt gevonden. Gebruik de opslag-SDK voor meer verfijnde gegevensselectie.


Kenmerken

Zowel in-process als geïsoleerde werkproces C#-bibliotheken gebruiken kenmerken om de functie te definiëren. C#-script maakt in plaats daarvan gebruik van een function.json configuratiebestand, zoals beschreven in de handleiding voor C#-scripts.

In C#-klassebibliotheken ondersteunt de TableInputAttribute volgende eigenschappen:

Kenmerkeigenschap Beschrijving
TableName De naam van de tabel.
PartitionKey Optioneel. De partitiesleutel van de tabelentiteit die moet worden gelezen.
RowKey Optioneel. De rijsleutel van de tabelentiteit die moet worden gelezen.
Nemen Optioneel. Het maximum aantal entiteiten dat moet worden ingelezen in een IEnumerable<T>. Kan niet worden gebruikt met RowKey.
Filteren Optioneel. Een OData-filterexpressie voor entiteiten die moeten worden ingelezen in een IEnumerable<T>. Kan niet worden gebruikt met RowKey.
Verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met de tabelservice. Zie verbindingen.

Aantekeningen

Gebruik in de Java Functions Runtime-bibliotheek de @TableInput aantekening voor parameters waarvan de waarde afkomstig is uit Table Storage. Deze aantekening kan worden gebruikt met systeemeigen Java-typen, POJO's of nullbare waarden met Optional<T>. Deze aantekening ondersteunt de volgende elementen:

Element Description
name De naam van de variabele die de tabel of entiteit in functiecode vertegenwoordigt.
tableName De naam van de tabel.
partitionKey Optioneel. De partitiesleutel van de tabelentiteit die moet worden gelezen.
rowKey Optioneel. De rijsleutel van de tabelentiteit die moet worden gelezen.
nemen Optioneel. Het maximum aantal entiteiten dat moet worden gelezen.
filter Optioneel. Een OData-filterexpressie voor tabelinvoer.
verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met de tabelservice. Zie verbindingen.

Configuratie

In de volgende tabel worden de eigenschappen uitgelegd die u kunt instellen voor het options object dat aan de input.table() methode is doorgegeven.

Eigenschappen Beschrijving
tableName De naam van de tabel.
partitionKey Optioneel. De partitiesleutel van de tabelentiteit die moet worden gelezen.
rowKey Optioneel. De rijsleutel van de tabelentiteit die moet worden gelezen. Kan niet worden gebruikt met take of filter.
nemen Optioneel. Het maximum aantal entiteiten dat moet worden geretourneerd. Kan niet worden gebruikt met rowKey.
filter Optioneel. Een OData-filterexpressie voor de entiteiten die moeten worden geretourneerd uit de tabel. Kan niet worden gebruikt met rowKey.
verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met de tabelservice. Zie verbindingen.

Configuratie

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u in het function.json-bestand hebt ingesteld.

function.json-eigenschap Beschrijving
type Moet worden ingesteld op table. Deze eigenschap wordt automatisch ingesteld wanneer u de binding maakt in Azure Portal.
direction Moet worden ingesteld op in. Deze eigenschap wordt automatisch ingesteld wanneer u de binding maakt in Azure Portal.
name De naam van de variabele die de tabel of entiteit in functiecode vertegenwoordigt.
tableName De naam van de tabel.
partitionKey Optioneel. De partitiesleutel van de tabelentiteit die moet worden gelezen.
rowKey Optioneel. De rijsleutel van de tabelentiteit die moet worden gelezen. Kan niet worden gebruikt met take of filter.
nemen Optioneel. Het maximum aantal entiteiten dat moet worden geretourneerd. Kan niet worden gebruikt met rowKey.
filter Optioneel. Een OData-filterexpressie voor de entiteiten die moeten worden geretourneerd uit de tabel. Kan niet worden gebruikt met rowKey.
verbinding De naam van een app-instelling of instellingsverzameling die aangeeft hoe verbinding moet worden gemaakt met de tabelservice. Zie verbindingen.

Wanneer u lokaal ontwikkelt, voegt u uw toepassingsinstellingen toe aan het local.settings.json-bestand in de Values verzameling.

Connecties

De connection eigenschap is een verwijzing naar de omgevingsconfiguratie die aangeeft hoe de app verbinding moet maken met uw tabelservice. Het kan het volgende opgeven:

Als de geconfigureerde waarde zowel een exacte overeenkomst is voor één instelling als een voorvoegselovereenkomst voor andere instellingen, wordt de exacte overeenkomst gebruikt.

Connection string

Als u een verbindingsreeks voor tabellen in Azure Table Storage wilt verkrijgen, volgt u de stappen in Toegangssleutels voor opslagaccounts beheren. Als u een verbindingsreeks voor tabellen in Azure Cosmos DB for Table wilt verkrijgen, volgt u de stappen die worden weergegeven in de veelgestelde vragen over Azure Cosmos DB for Table.

Deze verbindingsreeks moet worden opgeslagen in een toepassingsinstelling met een naam die overeenkomt met de waarde die is opgegeven door de connection eigenschap van de bindingsconfiguratie.

Als de naam van de app-instelling begint met 'AzureWebJobs', kunt u hier alleen de rest van de naam opgeven. Als u bijvoorbeeld instelt connection op 'MyStorage', zoekt de Functions-runtime naar een app-instelling met de naam 'AzureWebJobsMyStorage'. Als u leeg laatconnection, gebruikt de Functions-runtime de standaardopslag-verbindingsreeks in de app-instelling met de naamAzureWebJobsStorage.

Op identiteit gebaseerde verbindingen

Als u de table-API-extensie gebruikt, in plaats van een verbindingsreeks met een geheim te gebruiken, kunt u de app een Microsoft Entra-identiteit laten gebruiken. Dit geldt alleen voor toegang tot tabellen in Azure Storage. Als u een identiteit wilt gebruiken, definieert u instellingen onder een gemeenschappelijk voorvoegsel dat wordt toegewezen aan de connection eigenschap in de trigger- en bindingsconfiguratie.

Als u 'AzureWebJobsStorage' instelt connection , raadpleegt u Verbinding maken met hostopslag met een identiteit. Voor alle andere verbindingen vereist de extensie de volgende eigenschappen:

Eigenschappen Sjabloon voor omgevingsvariabele Beschrijving Voorbeeldwaarde
Tabelservice-URI <CONNECTION_NAME_PREFIX>__tableServiceUri1 De gegevensvlak-URI van de Azure Storage-tabelservice waarmee u verbinding maakt, met behulp van het HTTPS-schema. <https:// storage_account_name.table.core.windows.net>

1 <CONNECTION_NAME_PREFIX>__serviceUri kan als alias worden gebruikt. Als beide formulieren worden opgegeven, wordt het tableServiceUri formulier gebruikt. Het serviceUri formulier kan niet worden gebruikt wanneer de algemene verbindingsconfiguratie moet worden gebruikt in blobs, wachtrijen en/of tabellen.

Andere eigenschappen kunnen worden ingesteld om de verbinding aan te passen. Zie Algemene eigenschappen voor op identiteit gebaseerde verbindingen.

Het serviceUri formulier kan niet worden gebruikt wanneer de algehele verbindingsconfiguratie moet worden gebruikt in blobs, wachtrijen en/of tabellen in Azure Storage. De URI kan alleen de tabelservice aanwijzen. Als alternatief kunt u een URI specifiek opgeven voor elke service onder hetzelfde voorvoegsel, zodat één verbinding kan worden gebruikt.

Wanneer deze worden gehost in de Azure Functions-service, maken identiteitsverbindingen gebruik van een beheerde identiteit. De door het systeem toegewezen identiteit wordt standaard gebruikt, hoewel een door de gebruiker toegewezen identiteit kan worden opgegeven met de credential en clientID eigenschappen. Houd er rekening mee dat het configureren van een door de gebruiker toegewezen identiteit met een resource-id niet wordt ondersteund. Wanneer uw ontwikkelaarsidentiteit wordt uitgevoerd in andere contexten, zoals lokale ontwikkeling, wordt in plaats daarvan uw ontwikkelaarsidentiteit gebruikt, hoewel dit kan worden aangepast. Zie Lokale ontwikkeling met op identiteit gebaseerde verbindingen.

Toestemming verlenen aan de identiteit

Elke identiteit die wordt gebruikt, moet machtigingen hebben om de beoogde acties uit te voeren. Voor de meeste Azure-services betekent dit dat u een rol in Azure RBAC moet toewijzen met behulp van ingebouwde of aangepaste rollen die deze machtigingen bieden.

Belangrijk

Sommige machtigingen worden mogelijk weergegeven door de doelservice die niet nodig is voor alle contexten. Waar mogelijk moet u zich houden aan het principe van minimale bevoegdheid, waarbij de identiteit alleen vereiste bevoegdheden verleent. Als de app bijvoorbeeld alleen uit een gegevensbron moet kunnen lezen, gebruikt u een rol die alleen gemachtigd is om te lezen. Het zou ongepast zijn om een rol toe te wijzen die ook schrijfbewerkingen naar die service toestaat, omdat dit overmatige machtigingen zou zijn voor een leesbewerking. Op dezelfde manier wilt u ervoor zorgen dat de roltoewijzing alleen is afgestemd op de resources die moeten worden gelezen.

U moet een roltoewijzing maken die tijdens runtime toegang biedt tot uw Azure Storage-tabelservice. Beheerrollen zoals Eigenaar zijn niet voldoende. In de volgende tabel ziet u ingebouwde rollen die worden aanbevolen bij het gebruik van de Azure Tables-extensie voor Azure Storage in normale werking. Uw toepassing vereist mogelijk extra machtigingen op basis van de code die u schrijft.

Bindingstype Voorbeeld van ingebouwde rollen (Azure Storage1)
Invoerbinding Opslagtabelgegevenslezer
Uitvoerbinding Inzender voor opslagtabelgegevens

1 Als uw app in plaats daarvan verbinding maakt met tabellen in Azure Cosmos DB for Table, wordt het gebruik van een identiteit niet ondersteund en moet de verbinding een verbindingsreeks gebruiken.

Gebruik

Het gebruik van de binding is afhankelijk van de versie van het extensiepakket en de C#-modaliteit die wordt gebruikt in uw functie-app. Dit kan een van de volgende zijn:

Een geïsoleerde werkprocesklassebibliotheek gecompileerde C#-functie wordt uitgevoerd in een proces dat is geïsoleerd van de runtime.

Kies een versie om gebruiksgegevens voor de modus en versie te bekijken.

Wanneer u met één tabelentiteit werkt, kan de Azure Tables-invoerbinding worden gekoppeld aan de volgende typen:

Type Description
Een serialiseerbaar JSON-type dat ITableEntity implementeert Functions probeert de entiteit te deserialiseren in een niet-oud CLR-objecttype (POCO). Het type moet ITableEntity implementeren of een tekenreekseigenschap RowKey en een tekenreekseigenschap PartitionKey hebben.
TableEntity1 De entiteit als een woordenlijstachtig type.

Wanneer u met meerdere entiteiten vanuit een query werkt, kan de Azure Tables-invoerbinding worden gekoppeld aan de volgende typen:

Type Description
IEnumerable<T>waarbij T ITableEntity wordt geïmplementeerd Een opsomming van entiteiten die door de query worden geretourneerd. Elke vermelding vertegenwoordigt één entiteit. Het type T moet ITableEntity implementeren of een tekenreekseigenschap RowKey en een tekenreekseigenschap PartitionKey hebben.
TableClient1 Een client die is verbonden met de tabel. Dit biedt het meeste beheer voor het verwerken van de tabel en kan worden gebruikt om ernaar te schrijven als de verbinding voldoende machtigingen heeft.

1 Als u deze typen wilt gebruiken, moet u verwijzen naar Microsoft.Azure.Functions.Worker.Extensions.Tables 1.2.0 of hoger en de algemene afhankelijkheden voor SDK-typebindingen.

Het kenmerk TableInput geeft u toegang tot de tabelrij die de functie heeft geactiveerd.

Haal de invoerrijgegevens op met behulp van context.extraInputs.get().

Gegevens worden doorgegeven aan de invoerparameter zoals opgegeven door de name sleutel in het function.json-bestand . Hiermee geeft u De partitionKey op en rowKey kunt u filteren op specifieke records.

Tabelgegevens worden als een JSON-tekenreeks doorgegeven aan de functie. De serialiseer het bericht door aan te roepen json.loads zoals wordt weergegeven in het invoervoorbeeld.

Zie Voorbeeld voor specifieke gebruiksgegevens.

Volgende stappen