Sdílet prostřednictvím


Výstupní vazby tabulek Azure pro Azure Functions

Výstupní vazba tabulky Azure slouží k zápisu entit do tabulky ve službě Azure Cosmos DB pro tabulky nebo Azure Table Storage.

Informace o nastavení a konfiguraci najdete v přehledu .

Poznámka:

Tato výstupní vazba podporuje pouze vytváření nových entit v tabulce. Pokud potřebujete aktualizovat existující entitu z kódu funkce, použijte přímo sadu Azure Tables SDK.

Důležité

Tento článek používá karty pro podporu více verzí programovacího modelu Node.js. Model v4 je obecně dostupný a je navržený tak, aby měl flexibilnější a intuitivnější prostředí pro vývojáře v JavaScriptu a TypeScriptu. Další podrobnosti o tom, jak model v4 funguje, najdete v příručce pro vývojáře služby Azure Functions Node.js. Další informace o rozdílech mezi v3 a v4 najdete v průvodci migrací.

Příklad

Funkci jazyka C# je možné vytvořit pomocí jednoho z následujících režimů jazyka C#:

  • Izolovaný model pracovního procesu: Kompilovaná funkce jazyka C#, která běží v pracovním procesu, který je izolovaný od modulu runtime. Izolovaný pracovní proces je nutný pro podporu funkcí C# spuštěných na LTS a jiných verzích než LTS .NET a rozhraní .NET Framework. Rozšíření pro izolované funkce pracovních procesů používají Microsoft.Azure.Functions.Worker.Extensions.* obory názvů.
  • Model v procesu: Zkompilovaná funkce jazyka C#, která běží ve stejném procesu jako modul runtime služby Functions. Ve variantě tohoto modelu je možné spouštět funkce pomocí skriptování jazyka C#, což je podporováno především pro úpravy portálu C#. Rozšíření pro procesní funkce používají Microsoft.Azure.WebJobs.Extensions.* obory názvů.

Následující MyTableData třída představuje řádek dat v tabulce:

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

Následující funkce, která je spuštěna triggerem Queue Storage, zapíše novou MyDataTable entitu do tabulky s názvem 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}"
    };
}

Následující příklad ukazuje funkci Java, která používá trigger HTTP k zápisu jednoho řádku tabulky.

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

Následující příklad ukazuje funkci Java, která používá trigger HTTP k zápisu více řádků tabulky.

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

Následující příklad ukazuje výstupní vazbu tabulky, která zapisuje více entit tabulky.

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

Následující příklad ukazuje, jak napsat více entit do tabulky z funkce.

Konfigurace vazby v function.json:

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

Kód PowerShellu v souboru run.ps1:

param($InputData, $TriggerMetadata)

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

Následující příklad ukazuje, jak použít výstupní vazbu Table Storage. table Nakonfigurujte vazbu v function.json přiřazením hodnot k name, tableNamepartitionKey, a 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"
    }
  ]
}

Následující funkce vygeneruje jedinečnou UUI pro rowKey hodnotu a zachovají zprávu do služby Table Storage.

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

Atributy

Knihovny C# v procesu i izolovaného pracovního procesu používají atributy k definování funkce. Skript jazyka C# místo toho používá konfigurační soubor function.json, jak je popsáno v průvodci skriptováním jazyka C#.

V knihovnách tříd jazyka TableInputAttribute C# podporuje následující vlastnosti:

Vlastnost atributu Popis
TableName Název tabulky, do které se má zapisovat.
PartitionKey Klíč oddílu entity tabulky, který se má zapisovat.
RowKey Klíč řádku entity tabulky, která se má zapisovat.
Připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Table Service. Viz Připojení.

Poznámky

V knihovně modulu runtime funkcí Java použijte k zápisu hodnot do tabulek poznámku TableOutput s parametry. Atribut podporuje následující prvky:

Element (Prvek) Popis
Jméno Název proměnné použitý v kódu funkce, který představuje tabulku nebo entitu.
Datatype Definuje, jak má modul runtime služby Functions zacházet s hodnotou parametru. Další informace najdete v datovém typu.
tableName Název tabulky, do které se má zapisovat.
partitionKey Klíč oddílu entity tabulky, který se má zapisovat.
rowKey Klíč řádku entity tabulky, která se má zapisovat.
připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Table Service. Viz Připojení.

Konfigurace

Následující tabulka vysvětluje vlastnosti, které můžete nastavit u objektu předaného options metodě output.table() .

Vlastnost Popis
tableName Název tabulky, do které se má zapisovat.
partitionKey Klíč oddílu entity tabulky, který se má zapisovat.
rowKey Klíč řádku entity tabulky, která se má zapisovat.
připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Table Service. Viz Připojení.

Konfigurace

Následující tabulka vysvětluje vlastnosti konfigurace vazby, které jste nastavili v souboru function.json .

vlastnost function.json Popis
type Musí být nastavena na tablehodnotu . Tato vlastnost se nastaví automaticky při vytváření vazby na webu Azure Portal.
direction Musí být nastavena na outhodnotu . Tato vlastnost se nastaví automaticky při vytváření vazby na webu Azure Portal.
Jméno Název proměnné použitý v kódu funkce, který představuje tabulku nebo entitu. Nastaví se tak, aby $return odkaz na vrácenou hodnotu funkce.
tableName Název tabulky, do které se má zapisovat.
partitionKey Klíč oddílu entity tabulky, který se má zapisovat.
rowKey Klíč řádku entity tabulky, která se má zapisovat.
připojení Název nastavení aplikace nebo nastavení kolekce, která určuje, jak se připojit ke službě Table Service. Viz Připojení.

Při místním vývoji přidejte nastavení aplikace do souboru local.settings.json v kolekci Values .

Propojení

Vlastnost connection je odkazem na konfiguraci prostředí, která určuje, jak se má aplikace připojit k tabulkové službě. Může zadat:

Pokud je nakonfigurovaná hodnota přesná shoda pro jedno nastavení i shodu předpony pro jiná nastavení, použije se přesná shoda.

Connection string

Pokud chcete získat připojovací řetězec pro tabulky ve službě Azure Table Storage, postupujte podle kroků uvedených v tématu Správa přístupových klíčů účtu úložiště. Pokud chcete získat připojovací řetězec pro tabulky ve službě Azure Cosmos DB for Table, postupujte podle kroků uvedených v nejčastějších dotazech ke službě Azure Cosmos DB for Table.

Tato připojovací řetězec by měla být uložena v nastavení aplikace s názvem, který connection odpovídá hodnotě určené vlastností konfigurace vazby.

Pokud název nastavení aplikace začíná na "AzureWebJobs", můžete zde zadat pouze zbytek názvu. Pokud například nastavíte connection "MyStorage", modul runtime Functions vyhledá nastavení aplikace s názvem AzureWebJobsMyStorage. Pokud necháte connection prázdné, modul runtime Služby Functions použije výchozí připojovací řetězec úložiště v nastavení aplikace, které je pojmenované AzureWebJobsStorage.

Připojení založená na identitách

Pokud používáte rozšíření Api pro tabulky, nemusíte používat připojovací řetězec s tajným kódem, můžete aplikaci použít identitu Microsoft Entra. To platí jenom při přístupu k tabulkám ve službě Azure Storage. Pokud chcete použít identitu, definujete nastavení pod běžnou předponou, která se mapuje na connection vlastnost v konfiguraci triggeru a vazby.

Pokud nastavujete connection azureWebJobsStorage, přečtěte si téma Připojení k hostitelskému úložišti pomocí identity. Pro všechna ostatní připojení rozšíření vyžaduje následující vlastnosti:

Vlastnost Šablona proměnné prostředí Popis Příklad hodnoty
Table Service URI <CONNECTION_NAME_PREFIX>__tableServiceUri1 Identifikátor URI roviny dat služby Azure Storage, ke které se připojujete, pomocí schématu HTTPS. <https:// storage_account_name.table.core.windows.net>

1 <CONNECTION_NAME_PREFIX>__serviceUri lze použít jako alias. Pokud jsou k dispozici oba formuláře, použije se tableServiceUri formulář. Formulář serviceUri nelze použít, pokud se má použít celková konfigurace připojení napříč objekty blob, frontami a/nebo tabulkami.

Pro přizpůsobení připojení mohou být nastaveny další vlastnosti. Viz Běžné vlastnosti pro připojení založená na identitě.

Formulář serviceUri se nedá použít, pokud se má celková konfigurace připojení použít napříč objekty blob, frontami a/nebo tabulkami ve službě Azure Storage. Identifikátor URI může určit pouze službu tabulky. Jako alternativu můžete zadat identifikátor URI speciálně pro každou službu pod stejnou předponou, což umožňuje použití jediného připojení.

Při hostovaní ve službě Azure Functions používají připojení založená na identitách spravovanou identitu. Identita přiřazená systémem se používá ve výchozím nastavení, i když je možné zadat identitu přiřazenou uživatelem s vlastnostmi a clientID vlastnostmicredential. Všimněte si, že konfigurace identity přiřazené uživatelem s ID prostředku se nepodporuje . Při spuštění v jiných kontextech, jako je místní vývoj, se místo toho použije vaše identita vývojáře, i když je možné ji přizpůsobit. Viz Místní vývoj s připojeními založenými na identitách.

Udělení oprávnění identitě

Jakákoli identita, kterou používáte, musí mít oprávnění k provedení zamýšlených akcí. U většiny služeb Azure to znamená, že potřebujete přiřadit roli v Azure RBAC pomocí předdefinovaných nebo vlastních rolí, které tato oprávnění poskytují.

Důležité

Cílová služba může zpřístupnit některá oprávnění, která nejsou nutná pro všechny kontexty. Pokud je to možné, dodržujte zásadu nejnižšího oprávnění a udělte identitě pouze požadovaná oprávnění. Pokud například aplikace potřebuje jen číst ze zdroje dat, použijte roli, která má oprávnění jen ke čtení. Přiřazení role, která také umožňuje zápis do této služby, by bylo nevhodné, protože by to bylo nadměrné oprávnění pro operaci čtení. Podobně byste chtěli zajistit, aby přiřazení role bylo vymezeno pouze nad prostředky, které je potřeba číst.

Budete muset vytvořit přiřazení role, které poskytuje přístup k tabulkové službě Azure Storage za běhu. Role správy, jako je vlastník , nestačí. Následující tabulka ukazuje předdefinované role, které se doporučují při použití rozšíření Azure Tables pro Azure Storage v normálním provozu. Vaše aplikace může vyžadovat další oprávnění na základě kódu, který napíšete.

Typ vazby Příklad předdefinovaných rolí (Azure Storage1)
Vstupní vazba Čtenář dat tabulky služby Storage
Výstupní vazba Přispěvatel dat tabulky úložiště

1 Pokud se vaše aplikace místo toho připojuje k tabulkám ve službě Azure Cosmos DB for Table, použití identity se nepodporuje a připojení musí používat připojovací řetězec.

Využití

Použití vazby závisí na verzi balíčku rozšíření a na způsobu použití jazyka C# ve vaší aplikaci funkcí, což může být jedna z následujících možností:

Kompilovaná funkce C# v izolované knihovně tříd pracovních procesů běží v procesu izolovaném od modulu runtime.

Zvolte verzi, abyste zobrazili podrobnosti o využití pro režim a verzi.

Pokud chcete, aby funkce zapisuje do jedné entity, výstupní vazba Azure Tables může svázat s následujícími typy:

Typ Popis
Serializovatelný typ JSON, který implementuje [ITableEntity] Funkce se pokusí serializovat typ prostého starého objektu CLR (POCO) jako entitu. Typ musí implementovat [ITableEntity] nebo musí mít řetězcovou RowKey vlastnost a vlastnost řetězce PartitionKey .

Pokud chcete, aby funkce zapisovat do více entit, výstupní vazba Azure Tables může svázat s následujícími typy:

Typ Popis
T[] where T is one of the single entity types Pole obsahující více entit. Každá položka představuje jednu entitu.

V případě jiných výstupních scénářů můžete přímo vytvářet a používat typy z Azure.Data.Tables .

Existují dvě možnosti pro výstup řádku úložiště tabulky z funkce pomocí poznámky TableStorageOutput :

Možnosti Popis
Návratová hodnota Použitím poznámky na samotnou funkci se návratová hodnota funkce zachová jako řádek úložiště tabulky.
Imperativ Chcete-li explicitně nastavit řádek tabulky, použijte poznámku na konkrétní parametr typu OutputBinding<T>, kde T obsahuje PartitionKey a RowKey vlastnosti. Tyto vlastnosti můžete doprovázet implementací ITableEntity nebo děděním TableEntity.

Nastavte data výstupního řádku tak, že vrátíte hodnotu nebo použijete context.extraOutputs.set().

K zápisu do tabulkových dat použijte rutinu Push-OutputBinding -Name TableBinding , nastavte parametr a -Value parametr roven datům řádku. Další podrobnosti najdete v příkladu PowerShellu.

Existují dvě možnosti pro výstup zprávy řádku úložiště tabulky z funkce:

Možnosti Popis
Návratová hodnota name Nastavte vlastnost v function.json na $returnhodnotu . Při této konfiguraci se návratová hodnota funkce zachová jako řádek úložiště tabulky.
Imperativ Předejte hodnotu metodě set parametru deklarovaného jako typ Out . Předaná set hodnota je trvalá jako řádek tabulky.

Konkrétní podrobnosti o využití najdete v příkladu.

Výjimky a návratové kódy

Vazba Reference
Table Kódy chyb tabulky
Objekt blob, tabulka, fronta Kódy chyb úložiště
Objekt blob, tabulka, fronta Řešení potíží

Další kroky