Бөлісу құралы:


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

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

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

Внимание

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

Пример

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

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

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

Следующий класс 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; }
}

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

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

Следующая функция, вызываемая очередью, возвращает первые 5 сущностей как IEnumerable<T> со значением ключа секции, заданного в качестве сообщения очереди.

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

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

В следующем примере показана функция, активируемая HTTP, которая возвращает список объектов лиц в указанной секции в хранилище таблиц. В этом примере ключ секции извлекается из маршрута HTTP, а tableName и connection — из параметров функции.

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

Заметка TableInput также может извлекать привязки из текста запроса в формате JSON, как показано в следующем примере.

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

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

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

В следующем примере показана входная привязка таблицы, использующая триггер очереди для чтения одной строки таблицы. Привязка задает partitionKey и a rowKey. Значение rowKey "{queueTrigger}" указывает, что ключ строки получен из строки сообщения очереди.

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

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

В этом примере конфигурация привязки указывает явное значение для partitionKey таблицы и использует выражение для передачи в rowKey. Выражение rowKey, {queueTrigger}, указывает, что ключ строки получен из строки сообщения очереди.

Конфигурация привязки в 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 в run.ps1:

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

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

В этом примере конфигурация привязки указывает явное значение для partitionKey таблицы и использует выражение для передачи в rowKey. Выражение rowKey указывает, {id} что ключ строки поступает из части {id} маршрута в запросе.

Конфигурация привязки в файле 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
}

Код Python в файле __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}")

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


Атрибуты

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

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

Свойство атрибута Description
TableName Название таблицы.
PartitionKey Необязательно. Ключ раздела сущности таблицы, которую нужно считать.
RowKey Необязательно. Ключ строки сущности таблицы, которую нужно считать.
Take Необязательно. Максимальное количество считываемых сущностей в IEnumerable<T>. Не может использоваться с RowKey.
Фильтр Необязательно. Выражение фильтра OData для сущностей, считываемых в IEnumerable<T>. Не может использоваться с RowKey.
Соединение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к службе таблицы. См. раздел Подключения.

Заметки

В библиотеке среды выполнения функций Java используйте заметку @TableInput для параметров, значения которых будут поступать из Хранилища таблиц. Эта заметка может использоваться с собственными типами Java, объектами POJO или значениями, допускающими значения NULL, используя Optional<T>. Эта заметка поддерживает следующие элементы:

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

Настройка

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

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

Настройка

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

Свойство в function.json Описание
type Должен иметь значениеtable. Это свойство задается автоматически при создании привязки на портале Azure.
direction Должен иметь значениеin. Это свойство задается автоматически при создании привязки на портале Azure.
name Имя переменной, представляющей таблицу или сущность в коде функции.
tableName Название таблицы.
partitionKey Необязательно. Ключ раздела сущности таблицы, которую нужно считать.
rowKey Необязательно. Ключ строки сущности таблицы, которую нужно считать. Не может использоваться с take или filter.
take Необязательно. Максимальное количество возвращаемых сущностей. Не может использоваться с rowKey.
filter Необязательно. Выражение фильтра OData для сущностей, возвращаемых из таблицы. Не может использоваться с 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 "AzureWebJobsStorage", см. статью "Подключение к хранилищу с удостоверением". Для всех других подключений требуются следующие свойства в расширении:

Свойство Шаблон переменной среды 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 или иметь строковое свойство и строковое RowKey PartitionKey свойство.
TableEntity1 Сущность в виде типа словаря.

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

Тип Описание
IEnumerable<T> где T реализуется ITableEntity Перечисление сущностей, возвращаемых запросом. Каждая запись представляет одну сущность. Тип T должен реализовать ITableEntity или иметь строковое свойство и строковое RowKey PartitionKey свойство.
TableClient1 Клиент, подключенный к таблице. Это обеспечивает большую часть управления для обработки таблицы и может использоваться для записи в нее, если подключение имеет достаточно разрешений.

1 Для использования этих типов необходимо ссылаться на Microsoft.Azure.Functions.Worker.Extensions.Tables 1.2.0 или более поздней версии , а также общие зависимости для привязок типов SDK.

Атрибут TableInput предоставляет доступ к строке таблицы, которая активировала функцию.

Получение входных данных строки с помощью context.extraInputs.get().

Данные передаются во входной параметр в соответствии с определением ключа name в файле function.json. Определение partitionKey и rowKey позволяет выполнять фильтрацию по конкретным записям.

Данные таблицы передаются в функцию в виде строки JSON. Отмените сериализацию сообщения, вызвав json.loads, как показано в примере входных данных.

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

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