Udostępnij za pośrednictwem


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

Użyj powiązania wejściowego tabel platformy Azure, aby odczytać tabelę w usłudze Azure Cosmos DB dla tabel lub usługi Azure Table Storage.

Aby uzyskać informacje na temat konfiguracji i konfiguracji, zobacz omówienie.

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

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ć przykłady dla trybu i wersji.

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, odczytuje klucz wiersza z kolejki, który służy do pobierania wiersza z tabeli wejściowej. Wyrażenie {queueTrigger} wiąże klucz wiersza z metadanymi komunikatu, czyli ciągiem komunikatu.

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

Następująca funkcja wyzwalana przez kolejkę zwraca pierwsze 5 jednostek jako IEnumerable<T>, z wartością klucza partycji ustawioną jako komunikat kolejki.

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

Właściwości Filter i Take służą do ograniczania liczby zwracanych jednostek.

W poniższym przykładzie pokazano funkcję wyzwalaną przez protokół HTTP, która zwraca listę obiektów osób znajdujących się w określonej partycji w usłudze Table Storage. W tym przykładzie klucz partycji jest wyodrębniany z trasy http, a parametr tableName i połączenie pochodzą z ustawień funkcji.

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

Adnotacja TableInput może również wyodrębnić powiązania z treści json żądania, jak pokazano w poniższym przykładzie.

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

W poniższym przykładzie użyto filtru do wykonywania zapytań dotyczących osób o określonej nazwie w tabeli platformy Azure i ogranicza liczbę możliwych dopasowań do 10 wyników.

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

W poniższym przykładzie przedstawiono powiązanie wejściowe tabeli, które używa wyzwalacza kolejki do odczytywania pojedynczego wiersza tabeli. Powiązanie określa element partitionKey i rowKey. rowKey Wartość "{queueTrigger}" wskazuje, że klucz wiersza pochodzi z ciągu komunikatu kolejki.

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

Poniższa funkcja używa wyzwalacza kolejki do odczytywania pojedynczego wiersza tabeli jako danych wejściowych funkcji.

W tym przykładzie konfiguracja powiązania określa jawną wartość tabeli partitionKey i używa wyrażenia do przekazania do elementu rowKey. Wyrażenie rowKey , wskazuje, {queueTrigger}że klucz wiersza pochodzi z ciągu komunikatu kolejki.

Konfiguracja powiązania w 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
}

Kod programu PowerShell w pliku run.ps1:

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

Poniższa funkcja używa wyzwalacza HTTP do odczytywania pojedynczego wiersza tabeli jako danych wejściowych funkcji.

W tym przykładzie konfiguracja powiązania określa jawną wartość tabeli partitionKey i używa wyrażenia do przekazania do elementu rowKey. Wyrażenie rowKey wskazuje, {id} że klucz wiersza pochodzi z {id} części trasy w żądaniu.

Konfiguracja powiązania w pliku 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
}

Kod języka Python w pliku __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}")

Za pomocą tego prostego powiązania nie można programowo obsłużyć przypadku, w którym nie znaleziono wiersza o identyfikatorze klucza wiersza. Aby uzyskać więcej szczegółowego wyboru danych, użyj zestawu SDK magazynu.


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.
PartitionKey Opcjonalny. Klucz partycji jednostki tabeli do odczytania.
RowKey Opcjonalny. Klucz wiersza jednostki tabeli do odczytania.
Brać Opcjonalny. Maksymalna liczba jednostek do odczytania w obiekcie IEnumerable<T>. Nie można używać z RowKeyprogramem .
Filtr Opcjonalny. Wyrażenie filtru OData dla jednostek do odczytu do elementu IEnumerable<T>. Nie można używać z RowKeyprogramem .
Połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą tabel. Zobacz Połączenia.

Adnotacje

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj @TableInput adnotacji dla parametrów, których wartość pochodziłaby z usługi Table Storage. Tej adnotacji można używać z natywnymi typami Języka Java, obiektami POJO lub wartościami dopuszczanymi wartościami null przy użyciu polecenia Optional<T>. Ta adnotacja obsługuje następujące elementy:

Element opis
name Nazwa zmiennej reprezentującej tabelę lub jednostkę w kodzie funkcji.
tableName Nazwa tabeli.
partitionKey Opcjonalny. Klucz partycji jednostki tabeli do odczytania.
rowKey Opcjonalny. Klucz wiersza jednostki tabeli do odczytania.
brać Opcjonalny. Maksymalna liczba jednostek do odczytania.
filter Opcjonalny. Wyrażenie filtru OData dla danych wejściowych tabeli.
połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą tabel. Zobacz Połączenia.

Konfigurowanie

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

Właściwości opis
tableName Nazwa tabeli.
partitionKey Opcjonalny. Klucz partycji jednostki tabeli do odczytania.
rowKey Opcjonalny. Klucz wiersza jednostki tabeli do odczytania. Nie można używać z take programem lub filter.
brać Opcjonalny. Maksymalna liczba jednostek do zwrócenia. Nie można używać z rowKeyprogramem .
filter Opcjonalny. Wyrażenie filtru OData dla jednostek, które mają być zwracane z tabeli. Nie można używać z rowKeyprogramem .
połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą tabel. Zobacz Połączenia.

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ść in. Ta właściwość jest ustawiana automatycznie podczas tworzenia powiązania w witrynie Azure Portal.
name Nazwa zmiennej reprezentującej tabelę lub jednostkę w kodzie funkcji.
tableName Nazwa tabeli.
partitionKey Opcjonalny. Klucz partycji jednostki tabeli do odczytania.
rowKey Opcjonalny. Klucz wiersza jednostki tabeli do odczytania. Nie można używać z take programem lub filter.
brać Opcjonalny. Maksymalna liczba jednostek do zwrócenia. Nie można używać z rowKeyprogramem .
filter Opcjonalny. Wyrażenie filtru OData dla jednostek, które mają być zwracane z tabeli. Nie można używać z rowKeyprogramem .
połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z usługą tabel. Zobacz Połączenia.

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 Nawiązywanie połączenia z magazynem hostów przy użyciu 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.

Podczas pracy z jednostką z jedną tabelą powiązanie wejś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 interfejs ITableEntity Funkcje próbują wykonać deserializacji jednostki w zwykły typ obiektu CLR (POCO). Typ musi implementować ITableEntity lub mieć właściwość string RowKey i właściwość string PartitionKey .
TableEntity1 Jednostka jako typ przypominający słownik.

Podczas pracy z wieloma jednostkami z zapytania powiązanie wejściowe tabel platformy Azure może wiązać się z następującymi typami:

Type Opis
IEnumerable<T> gdzie T implementuje interfejs ITableEntity Wyliczenie jednostek zwróconych przez zapytanie. Każdy wpis reprezentuje jedną jednostkę. Typ T musi implementować ITableEntity lub mieć właściwość string RowKey i właściwość string PartitionKey .
TableClient1 Klient połączony z tabelą. Zapewnia to największą kontrolę przetwarzania tabeli i może służyć do zapisywania w niej, jeśli połączenie ma wystarczające uprawnienia.

1 Aby użyć tych typów, należy odwołać się do elementów Microsoft.Azure.Functions.Worker.Extensions.Tables 1.2.0 lub nowszych oraz typowych zależności dla powiązań typu zestawu SDK.

Atrybut TableInput zapewnia dostęp do wiersza tabeli, który wyzwolił funkcję.

Pobierz dane wejściowego wiersza przy użyciu polecenia context.extraInputs.get().

Dane są przekazywane do parametru wejściowego określonego name przez klucz w pliku function.json . Określanie wartości i partitionKey rowKey umożliwia filtrowanie do określonych rekordów.

Dane tabeli są przekazywane do funkcji jako ciąg JSON. Desemalizuj komunikat przez wywołanie metody json.loads , jak pokazano w przykładzie wejściowym.

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

Następne kroki