Powiązania wyjściowe tabel platformy Azure dla usługi Azure Functions

  • Artykuł

Użyj powiązania wyjściowego tabel platformy Azure, aby zapisywać jednostki w tabeli w usłudze Azure Cosmos DB dla tabel lub usługi Azure Table Storage.

Aby uzyskać informacje o konfiguracji i konfiguracji, zobacz omówienie

Uwaga

To powiązanie wyjściowe obsługuje tylko tworzenie nowych jednostek w tabeli. Jeśli musisz zaktualizować istniejącą jednostkę z kodu funkcji, zamiast tego użyj bezpośrednio zestawu Azure Tables SDK.

Ważne

W tym artykule są używane karty do obsługi wielu wersji modelu programowania Node.js. Model w wersji 4 jest ogólnie dostępny i ma bardziej elastyczne i intuicyjne środowisko dla deweloperów języka JavaScript i Języka TypeScript. Aby uzyskać więcej informacji na temat sposobu działania modelu w wersji 4, zapoznaj się z przewodnikiem dewelopera dotyczącym usługi Azure Functions Node.js. Aby dowiedzieć się więcej o różnicach między wersjami 3 i v4, zapoznaj się z przewodnikiem migracji.

Przykład

Funkcję języka C# można utworzyć przy użyciu jednego z następujących trybów języka C#:

  • Model izolowanego procesu roboczego: skompilowana funkcja języka C#, która jest uruchamiana w procesie roboczym izolowanym od środowiska uruchomieniowego. Proces izolowanego procesu roboczego jest wymagany do obsługi funkcji języka C# uruchomionych w wersjach LTS i innych niż LTS platformy .NET oraz programu .NET Framework. Rozszerzenia dla izolowanych funkcji procesu roboczego używają Microsoft.Azure.Functions.Worker.Extensions.* przestrzeni nazw.
  • Model przetwarzania: skompilowana funkcja języka C#, która działa w tym samym procesie co środowisko uruchomieniowe usługi Functions. W odmianie tego modelu funkcje można uruchamiać przy użyciu skryptów języka C#, które są obsługiwane głównie w przypadku edytowania portalu języka C#. Rozszerzenia dla funkcji przetwarzania używają Microsoft.Azure.WebJobs.Extensions.* przestrzeni nazw.

Ważne

Wsparcie zostanie zakończone dla modelu procesu 10 listopada 2026 r. Zdecydowanie zalecamy przeprowadzenie migracji aplikacji do izolowanego modelu procesu roboczego w celu uzyskania pełnej obsługi.

Poniższa MyTableData klasa reprezentuje wiersz danych w tabeli:

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

Następująca funkcja, która jest uruchamiana przez wyzwalacz usługi Queue Storage, zapisuje nową MyDataTable jednostkę w tabeli o nazwie 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}"
    };
}

W poniższym przykładzie pokazano funkcję Języka Java, która używa wyzwalacza HTTP do zapisu pojedynczego wiersza tabeli.

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

W poniższym przykładzie pokazano funkcję Języka Java, która używa wyzwalacza HTTP do zapisywania wielu wierszy tabeli.

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

W poniższym przykładzie pokazano powiązanie danych wyjściowych tabeli, które zapisuje wiele jednostek tabeli.

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

W poniższym przykładzie pokazano, jak napisać wiele jednostek do tabeli z funkcji.

Konfiguracja powiązania w function.json:

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

Kod programu PowerShell w pliku run.ps1:

param($InputData, $TriggerMetadata)

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

W poniższym przykładzie pokazano, jak używać powiązania wyjściowego usługi Table Storage. table Skonfiguruj powiązanie w function.json, przypisując wartości do name, tableName, partitionKeyi 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"
    }
  ]
}

Poniższa funkcja generuje unikatowy interfejs użytkownika dla rowKey wartości i utrwala komunikat w usłudze 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}")

Atrybuty

Biblioteki języka C# procesu roboczego zarówno w procesie przetwarzania procesów procesowych, jak i izolowanych, używają atrybutów do zdefiniowania funkcji. Zamiast tego skrypt języka C# używa pliku konfiguracji function.json zgodnie z opisem w przewodniku obsługi skryptów języka C#.

W bibliotekachTableInputAttribute klas języka C# obsługiwane są następujące właściwości:

Właściwość atrybutu opis
TableName Nazwa tabeli, do której ma być zapisywany.
PartitionKey Klucz partycji jednostki tabeli do zapisu.
RowKey Klucz wiersza jednostki tabeli do zapisu.
Połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą tabel. Zobacz Połączenie ions.

Adnotacje

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj adnotacji TableOutput dla parametrów, aby zapisać wartości w tabelach. Atrybut obsługuje następujące elementy:

Element opis
name Nazwa zmiennej używana w kodzie funkcji, która reprezentuje tabelę lub jednostkę.
Datatype Definiuje sposób, w jaki środowisko uruchomieniowe usługi Functions powinno traktować wartość parametru. Aby dowiedzieć się więcej, zobacz dataType.
Tablename Nazwa tabeli, do której ma być zapisywany.
partitionKey Klucz partycji jednostki tabeli do zapisu.
rowKey Klucz wiersza jednostki tabeli do zapisu.
Połączenia Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą tabel. Zobacz Połączenie ions.

Konfigurowanie

W poniższej tabeli opisano właściwości, które można ustawić dla options obiektu przekazanego output.table() do metody .

Właściwości opis
Tablename Nazwa tabeli, do której ma być zapisywany.
partitionKey Klucz partycji jednostki tabeli do zapisu.
rowKey Klucz wiersza jednostki tabeli do zapisu.
Połączenia Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą tabel. Zobacz Połączenie ions.

Konfigurowanie

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json .

właściwość function.json opis
type Musi być ustawiona wartość table. Ta właściwość jest ustawiana automatycznie podczas tworzenia powiązania w witrynie Azure Portal.
direction Musi być ustawiona wartość out. Ta właściwość jest ustawiana automatycznie podczas tworzenia powiązania w witrynie Azure Portal.
name Nazwa zmiennej używana w kodzie funkcji, która reprezentuje tabelę lub jednostkę. Ustaw wartość na , aby $return odwoływać się do wartości zwracanej przez funkcję.
Tablename Nazwa tabeli, do której ma być zapisywany.
partitionKey Klucz partycji jednostki tabeli do zapisu.
rowKey Klucz wiersza jednostki tabeli do zapisu.
Połączenia Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą tabel. Zobacz Połączenie ions.

Podczas tworzenia aplikacji lokalnie dodaj ustawienia aplikacji w pliku local.settings.json w kolekcji Values .

Połączenia

Właściwość connection jest odwołaniem do konfiguracji środowiska, która określa sposób łączenia aplikacji z usługą tabel. Może to określać:

Jeśli skonfigurowana wartość jest dokładnie zgodna z pojedynczym ustawieniem i dopasowaniem prefiksu dla innych ustawień, zostanie użyte dokładne dopasowanie.

Connection string

Aby uzyskać parametry połączenia dla tabel w usłudze Azure Table Storage, wykonaj kroki opisane w temacie Zarządzanie kluczami dostępu do konta magazynu. Aby uzyskać parametry połączenia dla tabel w usłudze Azure Cosmos DB dla tabel, wykonaj kroki przedstawione w artykule Azure Cosmos DB for Table FAQ (Często zadawane pytania dotyczące usługi Azure Cosmos DB dla tabel).

Ta parametry połączenia powinna być przechowywana w ustawieniu aplikacji z nazwą zgodną z wartością określoną przez connection właściwość konfiguracji powiązania.

Jeśli nazwa ustawienia aplikacji zaczyna się od "AzureWebJobs", możesz określić tylko pozostałą część nazwy w tym miejscu. Jeśli na przykład ustawiono connection wartość "MyStorage", środowisko uruchomieniowe usługi Functions wyszukuje ustawienie aplikacji o nazwie "AzureWebJobsMyStorage". W przypadku pozostawienia connection pustego środowisko uruchomieniowe usługi Functions używa domyślnej parametry połączenia Storage w ustawieniu aplikacji o nazwie AzureWebJobsStorage.

Połączenia oparte na tożsamościach

Jeśli używasz rozszerzenia interfejsu API tabel, zamiast używać parametry połączenia z wpisem tajnym, możesz użyć tożsamości microsoft Entra. Ma to zastosowanie tylko w przypadku uzyskiwania dostępu do tabel w usłudze Azure Storage. Aby użyć tożsamości, należy zdefiniować ustawienia w ramach wspólnego prefiksu, który mapuje na connection właściwość w konfiguracji wyzwalacza i powiązania.

Jeśli ustawisz wartość connection "AzureWebJobsStorage", zobacz Połączenie do hostowania magazynu z tożsamością. W przypadku wszystkich innych połączeń rozszerzenie wymaga następujących właściwości:

Właściwości Szablon zmiennej środowiskowej opis Przykładowa wartość
Table Service URI <CONNECTION_NAME_PREFIX>__tableServiceUri1 Identyfikator URI płaszczyzny danych usługi tabel usługi Azure Storage, z którą nawiązujesz połączenie, przy użyciu schematu HTTPS. <https:// storage_account_name.table.core.windows.net>

1<CONNECTION_NAME_PREFIX>__serviceUri może służyć jako alias. Jeśli podano oba formularze, tableServiceUri zostanie użyty formularz. Nie serviceUri można użyć formularza, gdy ogólna konfiguracja połączenia ma być używana w obiektach blob, kolejkach i/lub tabelach.

Inne właściwości można ustawić, aby dostosować połączenie. Zobacz Typowe właściwości połączeń opartych na tożsamościach.

Nie serviceUri można użyć formularza, gdy ogólna konfiguracja połączenia ma być używana w obiektach blob, kolejkach i/lub tabelach w usłudze Azure Storage. Identyfikator URI może wyznaczyć tylko usługę tabel. Alternatywnie możesz podać identyfikator URI przeznaczony dla każdej usługi pod tym samym prefiksem, co pozwala na użycie jednego połączenia.

W przypadku hostowania w usłudze Azure Functions połączenia oparte na tożsamościach używają tożsamości zarządzanej. Tożsamość przypisana przez system jest używana domyślnie, chociaż tożsamości przypisanej przez użytkownika można określić za credential pomocą właściwości i clientID . Należy pamiętać, że konfigurowanie tożsamości przypisanej przez użytkownika przy użyciu identyfikatora zasobu nie jest obsługiwane. W przypadku uruchamiania w innych kontekstach, takich jak programowanie lokalne, tożsamość dewelopera jest używana, chociaż można to dostosować. Zobacz Programowanie lokalne z połączeniami opartymi na tożsamościach.

Udzielanie uprawnień tożsamości

Niezależnie od używanej tożsamości musi mieć uprawnienia do wykonywania zamierzonych akcji. W przypadku większości usług platformy Azure oznacza to, że musisz przypisać rolę w kontroli dostępu opartej na rolach platformy Azure przy użyciu wbudowanych lub niestandardowych ról, które zapewniają te uprawnienia.

Ważne

Niektóre uprawnienia mogą być uwidocznione przez usługę docelową, które nie są niezbędne dla wszystkich kontekstów. Jeśli to możliwe, przestrzegaj zasady najniższych uprawnień, udzielając tożsamości tylko wymaganych uprawnień. Jeśli na przykład aplikacja musi mieć możliwość odczytu tylko ze źródła danych, użyj roli, która ma uprawnienia tylko do odczytu. Niewłaściwe byłoby przypisanie roli, która umożliwia również zapisywanie w tej usłudze, ponieważ byłoby to nadmierne uprawnienie do operacji odczytu. Podobnie należy upewnić się, że przypisanie roli jest ograniczone tylko do zasobów, które należy odczytać.

Musisz utworzyć przypisanie roli, które zapewnia dostęp do usługi tabel usługi Azure Storage w czasie wykonywania. Role zarządzania, takie jak Właściciel , nie są wystarczające. W poniższej tabeli przedstawiono wbudowane role, które są zalecane podczas korzystania z rozszerzenia Tabele platformy Azure w usłudze Azure Storage w normalnej operacji. Aplikacja może wymagać dodatkowych uprawnień na podstawie zapisanego kodu.

Typ powiązania Przykładowe wbudowane role (Azure Storage1)
Powiązanie wejściowe Czytnik danych tabeli usługi Storage
Powiązanie wyjściowe Współautor danych tabeli usługi Storage

1 Jeśli aplikacja zamiast tego łączy się z tabelami w usłudze Azure Cosmos DB dla tabel, użycie tożsamości nie jest obsługiwane i połączenie musi używać parametry połączenia.

Użycie

Użycie powiązania zależy od wersji pakietu rozszerzenia i modalności języka C# używanej w aplikacji funkcji, co może być jednym z następujących elementów:

Izolowana biblioteka klas procesów roboczych skompilowana funkcja języka C# jest uruchamiana w procesie odizolowanym od środowiska uruchomieniowego.

Wybierz wersję, aby wyświetlić szczegóły użycia dla trybu i wersji.

Jeśli chcesz, aby funkcja zapisywała w jednej jednostce, powiązanie wyjściowe tabel platformy Azure może wiązać się z następującymi typami:

Type Opis
Typ z możliwością serializacji JSON implementujący element [ITableEntity] Funkcje próbują serializować zwykły typ obiektu CLR (POCO) jako jednostkę. Typ musi zaimplementować właściwość [ITableEntity] lub mieć właściwość string RowKey i właściwość string PartitionKey .

Jeśli chcesz, aby funkcja zapisywała w wielu jednostkach, powiązanie wyjściowe tabel platformy Azure może wiązać się z następującymi typami:

Type Opis
T[] gdzie T jest jednym z typów pojedynczej jednostki Tablica zawierająca wiele jednostek. Każdy wpis reprezentuje jedną jednostkę.

W przypadku innych scenariuszy wyjściowych utwórz typy i użyj ich bezpośrednio na podstawie tabeli Azure.Data.Tables .

Istnieją dwie opcje wyprowadzania wiersza usługi Table Storage z funkcji przy użyciu adnotacji TableStorageOutput :

Opcje opis
Wartość zwracana Stosując adnotację do samej funkcji, zwracana wartość funkcji jest zachowywana jako wiersz usługi Table Storage.
Imperatyw Aby jawnie ustawić wiersz tabeli, zastosuj adnotację do określonego parametru typu OutputBinding<T>, gdzie T zawiera PartitionKey właściwości i RowKey . Te właściwości można towarzyszyć przez zaimplementowanie ITableEntity lub dziedziczenie TableEntity.

Ustaw dane wiersza wyjściowego, zwracając wartość lub używając polecenia context.extraOutputs.set().

Aby zapisać dane w tabeli, użyj Push-OutputBinding polecenia cmdlet , ustaw -Name TableBinding parametr i -Value parametr równy danych wierszy. Zobacz przykład programu PowerShell, aby uzyskać więcej szczegółów.

Istnieją dwie opcje wyprowadzania komunikatu wiersza usługi Table Storage z funkcji:

Opcje opis
Wartość zwracana name Ustaw właściwość w function.json na $return. W przypadku tej konfiguracji wartość zwracana funkcji jest zachowywana jako wiersz usługi Table Storage.
Imperatyw Przekaż wartość do metody set parametru zadeklarowanego jako typ out . Przekazana wartość jest utrwalana set jako wiersz tabeli.

Aby uzyskać szczegółowe informacje o użyciu, zobacz Przykład.

Wyjątki i kody powrotne

Wiązanie Odwołanie
Table Kody błędów tabeli
Obiekt blob, tabela, kolejka Kody błędów magazynu
Obiekt blob, tabela, kolejka Rozwiązywanie problemów

Następne kroki

Dowiedz się więcej o wyzwalaczach i powiązaniach usługi Azure Functions