Выходные привязки таблиц Azure для службы "Функции Azure"

  • Статья

Используйте выходную привязку таблиц Azure для записи сущностей в таблицу в Azure Cosmos DB для таблицы или таблицы Azure служба хранилища.

Сведения об установке и настройке см. в этой обзорной статье.

Примечание.

Эта выходная привязка поддерживает только создание новых сущностей в таблице. Если необходимо обновить существующую сущность из кода функции, используйте пакет SDK таблиц Azure напрямую.

Внимание

В этой статье используются вкладки для поддержки нескольких версий модели программирования Node.js. Модель версии 4 общедоступна и предназначена для более гибкого и интуитивно понятного интерфейса для разработчиков JavaScript и TypeScript. Дополнительные сведения о том, как работает модель версии 4, см. в руководстве разработчика по Функции Azure Node.js. Дополнительные сведения о различиях между версиями 3 и 4 см. в руководстве по миграции.

Пример

Функцию C# можно создать с помощью одного из следующих режимов C#:

  • Изолированная рабочая модель: скомпилированная функция C#, которая выполняется в рабочем процессе, изолированном от среды выполнения. Изолированный рабочий процесс необходим для поддержки функций C#, работающих в LTS и не LTS-версиях .NET и платформа .NET Framework. Расширения для изолированных рабочих процессов используют Microsoft.Azure.Functions.Worker.Extensions.* пространства имен.
  • Модель внутрипроцессного процесса: скомпилированная функция C#, которая выполняется в том же процессе, что и среда выполнения Функций. В варианте этой модели функции можно запускать с помощью скриптов C#, которая поддерживается главным образом для редактирования портала C#. Расширения для функций в процессе используют Microsoft.Azure.WebJobs.Extensions.* пространства имен.

Внимание

Поддержка будет завершена для модели в процессе 10 ноября 2026 г. Настоятельно рекомендуется перенести приложения в изолированную рабочую модель для полной поддержки.

Следующий класс MyTableData представляет строку данных в таблице:

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

Следующая функция, которая запускается триггером Хранилища очередей, записывает новую сущность MyDataTable в таблицу с именем 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}"
    };
}

В следующем примере показана функция Java, которая использует триггер HTTP для записи одной строки таблицы.

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

В следующем примере показана функция Java, которая использует триггер HTTP для записи нескольких строк таблицы.

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

В следующем примере показана выходная привязка таблицы, которая записывает несколько сущностей таблицы.

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

В следующем примере показано, как записать несколько сущностей в таблицу из функции.

Конфигурация привязки в function.json:

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

Код PowerShell в run.ps1:

param($InputData, $TriggerMetadata)

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

В следующем примере показано, как использовать выходную привязку хранилища таблиц. Чтобы настроить привязку table в файле function.json, присвойте значения для параметров name, tableName, partitionKey и 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"
    }
  ]
}

Следующая функция создает уникальный UUI для значения rowKey и сохраняет сообщение в хранилище таблиц.

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

Атрибуты

Библиотеки C# в процессе и изолированном рабочем процессе используют атрибуты для определения функции. Вместо этого скрипт C# использует файл конфигурации function.json, как описано в руководстве по скриптам C#.

В библиотеках классов C#TableInputAttribute поддерживает следующие свойства:

Свойство атрибута Description
TableName Имя таблицы, в которую нужно записать.
PartitionKey Ключ раздела сущности таблицы, которую нужно записать.
RowKey Ключ строки сущности таблицы, которую нужно записать.
Соединение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к службе таблицы. См. раздел Подключения.

Заметки

В библиотеке времени выполнения функций Java используйте заметку TableOutput в параметрах для записи значений в таблицы. Атрибут поддерживает следующие элементы:

Элемент Description
name Имя переменной, используемое в функции кода, которая представляет таблицу или сущность.
dataType Определяет, как среда выполнения Функций должна обрабатывать значение параметра. Дополнительные сведения см. в разделе dataType.
tableName Имя таблицы, в которую нужно записать.
partitionKey Ключ раздела сущности таблицы, которую нужно записать.
rowKey Ключ строки сущности таблицы, которую нужно записать.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к службе таблицы. См. раздел Подключения.

Настройка

В следующей таблице описываются свойства, которые можно задать для options объекта, переданного методу output.table() .

Свойство Description
tableName Имя таблицы, в которую нужно записать.
partitionKey Ключ раздела сущности таблицы, которую нужно записать.
rowKey Ключ строки сущности таблицы, которую нужно записать.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к службе таблицы. См. раздел Подключения.

Настройка

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json.

Свойство в function.json Описание
type Должен иметь значениеtable. Это свойство задается автоматически при создании привязки на портале Azure.
direction Должен иметь значениеout. Это свойство задается автоматически при создании привязки на портале Azure.
name Имя переменной, используемое в функции кода, которая представляет таблицу или сущность. Задайте значение $return, ссылающееся на возвращаемое значение функции.
tableName Имя таблицы, в которую нужно записать.
partitionKey Ключ раздела сущности таблицы, которую нужно записать.
rowKey Ключ строки сущности таблицы, которую нужно записать.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к службе таблицы. См. раздел Подключения.

Если разработка ведется на локальном компьютере, добавьте параметры приложения в файл local.settings.json в коллекции Values.

Связи

Свойство connection является ссылкой на конфигурацию среды, которая указывает, как приложение должно подключаться к службе таблицы. В данном свойстве может быть указано:

Если настроенное значение одновременно точно соответствует одному параметру и является префиксом для других параметров, то используется точное совпадение.

Connection string

Чтобы получить строка подключения для таблиц в хранилище таблиц Azure, выполните действия, описанные в разделе "Управление ключами доступа к учетной записи хранения". Чтобы получить строка подключения таблиц в Azure Cosmos DB для таблицы, выполните действия, приведенные в статье "Часто задаваемые вопросы о таблице Azure Cosmos DB".

Эта строка подключения должна храниться в параметре приложения с именем, соответствующим значению, которое указано свойством connection конфигурации привязки.

Если имя параметра приложения начинается с AzureWebJobs, можно указать только остальную часть имени. Например, если задать для connection значение MyStorage, среда выполнения Функций Azure будет искать параметр приложения с именем AzureWebJobsMyStorage. Если оставить строку connection пустой, среда выполнения службы "Функции" будет использовать строку подключения к службе хранилища по умолчанию для параметра приложения с именем AzureWebJobsStorage.

Подключения на основе удостоверений

Если вы используете расширение API таблиц, а не используете строка подключения с секретом, вы можете использовать удостоверение Microsoft Entra. Это возможно только при доступе к таблицам в службе хранилища Azure. Чтобы использовать удостоверение, вы определяете параметры под общим префиксом, который сопоставляется со connection свойством в конфигурации триггера и привязки.

Если для параметра connection "AzureWebJobs служба хранилища" задано значение "AzureWebJobs служба хранилища", см. Подключение размещение хранилища с удостоверением. Для всех других подключений требуются следующие свойства в расширении:

Свойство Шаблон переменной среды Description Пример значения
Универсальный код ресурса (URI) службы таблиц <CONNECTION_NAME_PREFIX>__tableServiceUri1 URI плоскости данных службы таблиц служба хранилища Azure, к которой вы подключаетесь, с помощью схемы HTTPS. https://<storage_account_name>.table.core.windows.net

1<CONNECTION_NAME_PREFIX>__serviceUri можно использовать в качестве псевдонима. Если указаны обе формы, tableServiceUri используется форма. Форму serviceUri нельзя использовать, если общая конфигурация подключения должна использоваться для больших двоичных объектов, очередей и (или) таблиц.

Другие свойства могут быть заданы для настройки подключения. См. раздел Общие свойства подключений на основе удостоверений.

Форму serviceUri нельзя использовать, если общая конфигурация подключения будет использоваться для больших двоичных объектов, очередей и (или) таблиц в служба хранилища Azure. Универсальный код ресурса (URI) может назначать только службу таблиц. В качестве альтернативы можно специально указать универсальный код ресурса (URI) для каждой службы с тем же префиксом, что позволит использовать одно подключение.

При размещении в службе "Функции Azure" для подключений на основе удостоверений используется управляемое удостоверение. По умолчанию используется назначаемое системой удостоверение, однако вы можете указать назначаемое пользователем удостоверение с помощью свойств credential и clientID. Обратите внимание, что настройка назначаемого пользователем удостоверения с идентификатором ресурса не поддерживается. При выполнении в других контекстах, например при локальной разработке, вместо этого используется удостоверение разработчика, хотя это можно настроить. См. раздел Локальная разработка с использованием подключений на основе удостоверений.

Предоставление разрешения удостоверению

Любое используемое удостоверение должно иметь разрешения на выполнение предполагаемых действий. Для большинства служб Azure это означает, что необходимо назначить роль в Azure RBAC, используя встроенные или настраиваемые роли, которые предоставляют эти разрешения.

Внимание

Иногда целевая служба может предоставлять разрешения, которые не являются обязательными для всех контекстов. Там, где это возможно, придерживайтесь принципа минимальных привилегий, предоставляя удостоверению лишь самые необходимые привилегии. Например, если приложению требуется только возможность чтения из источника данных, используйте роль, которая имеет разрешение только на чтение. Было бы неуместным назначить роль, которая также разрешает запись в эту службу, так как это разрешение не требуется для операции чтения. Соответственно необходимо еще проверить, что область действия назначенной роли ограничена только теми ресурсами, которые необходимо прочитать.

Вам потребуется создать назначение ролей, которое предоставляет доступ к службе таблиц служба хранилища Azure во время выполнения. Ролей управления, таких как Владелец, недостаточно. В следующей таблице показаны встроенные роли, которые рекомендуется использовать при использовании расширения таблиц Azure для служба хранилища Azure в обычной работе. Приложению могут потребоваться дополнительные разрешения в зависимости от написанного кода.

Тип привязки Примеры встроенных ролей (служба хранилища Azure 1)
Входные привязки Читатель данных таблицы хранилища
Выходные привязки Участник данных таблицы хранилища

1 Если приложение вместо этого подключается к таблицам в Azure Cosmos DB для таблицы, использование удостоверения не поддерживается, а подключение должно использовать строка подключения.

Использование

Использование привязки зависит от версии пакета расширения и модальности C#, используемой в приложении-функции. Это может быть один из следующих вариантов:

Изолированная библиотека классов рабочих процессов, скомпилированная функция C# выполняется в процессе, изолированном от среды выполнения.

Выберите версию, чтобы просмотреть сведения об использовании для режима и версии.

Если требуется, чтобы функция записывала в одну сущность, выходная привязка таблиц Azure может привязаться к следующим типам:

Тип Описание
Сериализуемый тип JSON, реализующий [ITableEntity] Функции пытаются сериализовать обычный тип объекта CLR (POCO) в качестве сущности. Тип должен реализовать [ITableEntity] или иметь строковое свойство и строковое RowKeyPartitionKey свойство.

Если требуется, чтобы функция записывала в несколько сущностей, выходная привязка таблиц Azure может привязаться к следующим типам:

Тип Описание
T[] где T является одним из типов отдельных сущностей Массив, содержащий несколько сущностей. Каждая запись представляет одну сущность.

Для других выходных сценариев создайте и используйте типы из Azure.Data.Tables напрямую.

Существует два варианта вывода строки хранилища таблиц из функции с помощью заметки TableStorageOutput.

Параметры Description
Возвращаемое значение Вследствие применения аннотации к самой функции возвращаемое значение функции сохраняется как строка хранилища таблиц.
Императивное определение Чтобы явно задать значение сообщения, примените заметку к определенному параметру с типом OutputBinding<T>, где T включает свойства PartitionKey и RowKey. Чтобы добавить эти свойства, можно реализовать ITableEntity или наследовать TableEntity.

Задайте выходные данные строки, возвращая значение или используя context.extraOutputs.set()его.

Для записи данных в таблицу используйте командлет Push-OutputBinding, установите для параметров -Name TableBinding и -Value значения, равные строке данных. Дополнительные сведения см. в примере PowerShell.

Существует два варианта для вывода сообщения строки хранилища таблиц из функции.

Параметры Description
Возвращаемое значение задайте для свойства name в файле function.json значение $return. В этой конфигурации возвращаемое значение функции сохраняется как строка хранилища таблиц.
Императивное определение передайте значение методу set параметра, объявленного с типом Out. Значение, переданное в set, сохраняется как строка таблицы.

Подробные сведения об использовании см. в разделе Пример.

Исключения и коды возврата

Привязка Справочные материалы
Таблица Коды ошибок таблицы
Большой двоичный объект, таблица, очередь Коды ошибок хранилища
Большой двоичный объект, таблица, очередь Устранение неполадок

Следующие шаги

Основные понятия триггеров и привязок в Функциях Azure