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

Привязка входных данных Хранилища BLOB-объектов Azure для службы "Функции Azure"

  • Мақала

Привязка входных данных позволяет считывать данные хранилища BLOB-объектов в качестве входных данных в службе "Функции Azure".

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

Внимание

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

Функции Azure поддерживает две модели программирования для Python. Способ определения привязок зависит от выбранной модели программирования.

Модель программирования Python версии 2 позволяет определять привязки с помощью декораторов непосредственно в коде функции Python. Дополнительные сведения см. в руководстве разработчика Python.

Эта статья поддерживает обе модели программирования.

Пример

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

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

Внимание

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

В следующем примере показана функция C#, которая выполняется в изолированном рабочем процессе и использует триггер BLOB-объектов с входными и выходными привязками BLOB-объектов. Эта функция активируется путем создания BLOB-объекта в контейнере test-samples-trigger. Он считывает текстовый файл из контейнера test-samples-input и создает новый текстовый файл в выходном контейнере на основе имени активированного файла.

    public static class BlobFunction
    {
        [Function(nameof(BlobFunction))]
        [BlobOutput("test-samples-output/{name}-output.txt")]
        public static string Run(
            [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
            [BlobInput("test-samples-input/sample1.txt")] string myBlob,
            FunctionContext context)
        {
            var logger = context.GetLogger("BlobFunction");
            logger.LogInformation("Triggered Item = {myTriggerItem}", myTriggerItem);
            logger.LogInformation("Input Item = {myBlob}", myBlob);

            // Blob Output
            return "blob-output content";
        }
    }
}

Этот раздел содержит следующие примеры.

Триггер HTTP, поиск имени BLOB-объекта из строки запроса

В следующем примере показана функция Java, которая использует заметку HttpTrigger для получения параметра, содержащего имя файла в контейнере хранилища BLOB-объектов. После этого заметка BlobInput считывает файл и передает его содержимое в функцию как byte[].

  @FunctionName("getBlobSizeHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage blobSize(
    @HttpTrigger(name = "req", 
      methods = {HttpMethod.GET}, 
      authLevel = AuthorizationLevel.ANONYMOUS) 
    HttpRequestMessage<Optional<String>> request,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{Query.file}") 
    byte[] content,
    final ExecutionContext context) {
      // build HTTP response with size of requested blob
      return request.createResponseBuilder(HttpStatus.OK)
        .body("The size of \"" + request.getQueryParameters().get("file") + "\" is: " + content.length + " bytes")
        .build();
  }

Очередь триггера, получение имени BLOB-объекта из сообщения очереди

В следующем примере показана функция Java, которая использует заметку QueueTrigger для получения сообщения, содержащего имя файла в контейнере хранилища BLOB-объектов. После этого заметка BlobInput считывает файл и передает его содержимое в функцию как byte[].

  @FunctionName("getBlobSize")
  @StorageAccount("Storage_Account_Connection_String")
  public void blobSize(
    @QueueTrigger(
      name = "filename", 
      queueName = "myqueue-items-sample") 
    String filename,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{queueTrigger}") 
    byte[] content,
    final ExecutionContext context) {
      context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
  }

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

В следующем примере показана функция TypeScript, активируемая очередью, которая делает копию большого двоичного объекта. Она активируется сообщением очереди, содержащим имя копируемого большого двоичного объекта. Новый большой двоичный объект получает имя {originalblobname}-Copy.

import { app, input, InvocationContext, output } from '@azure/functions';

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<unknown> {
    return context.extraInputs.get(blobInput);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: storageQueueTrigger1,
});

В следующем примере показана функция JavaScript, активируемая очередью, которая делает копию большого двоичного объекта. Она активируется сообщением очереди, содержащим имя копируемого большого двоичного объекта. Новый большой двоичный объект получает имя {originalblobname}-Copy.

const { app, input, output } = require('@azure/functions');

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: (queueItem, context) => {
        return context.extraInputs.get(blobInput);
    },
});

В следующем примере показана привязка входных данных BLOB-объекта, определенная в файле function.js, которая делает входные данные BLOB-объекта доступными для функции PowerShell.

Ниже приведена конфигурация JSON.

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "source/{name}",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Ниже показан код функции.

# Input bindings are passed in via param block.
param([byte[]] $InputBlob, $TriggerMetadata)

Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"

В этом примере используются типы SDK для прямого доступа к базовому BlobClient объекту, предоставленному входной привязкой хранилища BLOB-объектов:

import logging

import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
@app.route(route="file")
@app.blob_input(
    arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_input(req: func.HttpRequest, client: blob.BlobClient):
    logging.info(
        f"Python blob input function processed blob \n"
        f"Properties: {client.get_blob_properties()}\n"
        f"Blob content head: {client.download_blob().read(size=1)}"
    )
    return "ok"

Примеры использования других типов SDK см. в ContainerClient примерах и StorageStreamDownloader примерах.

Дополнительные сведения, включая включение привязок типов ПАКЕТА SDK в проекте, см. в статье о привязках типов пакета SDK.

Код создает копию большого двоичного объекта.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobOutput1")
@app.route(route="file")
@app.blob_input(arg_name="inputblob",
                path="sample-workitems/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
@app.blob_output(arg_name="outputblob",
                path="newblob/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
def main(req: func.HttpRequest, inputblob: str, outputblob: func.Out[str]):
    logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
    outputblob.set(inputblob)
    return "ok"

Атрибуты

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

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

Параметр Описание
BlobPath Путь к BLOB-объекту.
Соединение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к BLOB-объектам Azure. См. раздел Подключения.

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

Декораторы

Применяется только к модели программирования Python версии 2.

Для функций Python версии 2, определенных с помощью декораторов, для триггеров хранилища BLOB-объектов определяются следующие свойства blob_input blob_output .

Свойство Description
arg_name Имя переменной, представляющей большой двоичный объект в коде функции.
path Путь к большому двоичному объекту для декоратора— это чтение большого blob_input двоичного объекта. blob_output Для декоратора это выходные данные или копия входного большого двоичного объекта.
connection Строка подключения учетной записи хранения.
data_type Для динамически типизированных языков указывает базовый тип данных. Возможные значения: string, binaryили stream. Дополнительные сведения см. в разделе Определения триггеров и привязок.

Сведения о функциях Python, определенных с помощью function.json, см. в разделе "Конфигурация ".

Заметки

Атрибут @BlobInput предоставляет доступ к BLOB-объекту, активировавшему функцию. Если с атрибутом используется массив байтов, задайте для dataType значение binary. Дополнительные сведения см. в примере входных данных.

Настройка

Применяется только к модели программирования Python версии 1.

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

Свойство Description
path Путь к BLOB-объекту.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к BLOB-объектам Azure. См. раздел Подключения.

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

Свойство в function.json Описание
type Должен иметь значениеblob.
direction Должен иметь значениеin. Исключения приведены в этом разделе.
name Имя переменной, представляющей большой двоичный объект в коде функции.
path Путь к BLOB-объекту.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к BLOB-объектам Azure. См. раздел Подключения.
dataType Для динамически типизированных языков указывает базовый тип данных. Возможные значения: string, binaryили stream. Дополнительные сведения см. в разделе Определения триггеров и привязок.

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

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

Типы привязки, поддерживаемые входными данными BLOB-объектов, зависят от версии пакета расширения и модальности C#, используемой в приложении-функции.

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

Тип Описание
string Содержимое большого двоичного объекта в виде строки. Используется, когда содержимое большого двоичного объекта является простым текстом.
byte[] Байты содержимого большого двоичного объекта.
Сериализуемые в JSON типы Если большой двоичный объект содержит данные JSON, функции пытаются десериализировать данные JSON в обычный тип объекта CLR (POCO).
Поток1 Входной поток содержимого большого двоичного объекта.
BlobClient1,
BlockBlobClient1,
PageBlobClient1,
AppendBlobClient1,
BlobBaseClient1		 Клиент, подключенный к большому двоичному объекту. Этот набор типов предлагает большую часть управления для обработки БОЛЬШОго двоичного объекта и может использоваться для записи обратно в него, если подключение имеет достаточно разрешений.

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

Тип Описание
T[] или List<T> где T находится один из типов входных привязок большого двоичного объекта Массив или список нескольких больших двоичных объектов. Каждая запись представляет один большой двоичный объект из контейнера. Вы также можете привязаться к любым интерфейсам, реализованным этими типами, например IEnumerable<T>.
BlobContainerClient1 Клиент, подключенный к контейнеру. Этот тип предоставляет большую часть управления для обработки контейнера и может использоваться для записи в него, если подключение имеет достаточно разрешений.

1 Для использования этих типов необходимо ссылаться на Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 или более поздней версии , а также общие зависимости для привязок типов ПАКЕТА SDK.

Привязку string или Byte[] рекомендуется использовать только в том случае, если BLOB-объект небольшой. Это рекомендуется делать, поскольку в этом случае все содержание BLOB-объекта загружает в память. Для большинства BLOB-объектов необходимо использовать тип Stream или BlobClient. Дополнительные сведения см. в разделе Параллелизм и использование памяти.

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

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

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("BlobTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ....
}

Используемая учетная запись хранения определяется в следующем порядке:

  • Свойство BlobTrigger атрибута Connection.
  • Атрибут StorageAccount, примененный к тому же параметру, что и BlobTrigger.
  • Атрибут StorageAccount, примененный к функции.
  • Атрибут StorageAccount, примененный к классу.
  • Учетная запись хранения по умолчанию для приложения-функции, определенная в параметре приложения AzureWebJobsStorage.

Атрибут @BlobInput предоставляет доступ к BLOB-объекту, активировавшему функцию. Если с атрибутом используется массив байтов, задайте для dataType значение binary. Дополнительные сведения см. в примере входных данных.

Доступ к данным BLOB-объектов с помощью context.extraInputs.get().

Получение доступа к данным BLOB-объекта через параметр string, который соответствует имени, назначенному параметром имени привязки в файле function.js.

Доступ к данным BLOB-объекта с помощью параметра, типизированного как InputStream. Дополнительные сведения см. в примере входных данных.

Функции также поддерживают привязки типов пакета SDK Python для хранилища BLOB-объектов Azure, что позволяет работать с данными BLOB-объектов с помощью следующих базовых типов SDK:

Внимание

Поддержка типов SDK для Python в настоящее время доступна в предварительной версии и поддерживается только для модели программирования Python версии 2. Дополнительные сведения см. в разделе "Типы пакетов SDK" в Python.

Связи

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

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

Connection string

Чтобы получить строку подключения, выполните действия, описанные в разделе Управление ключами доступа к учетной записи хранения. Строка подключения необходима для учетной записи хранения общего назначения, а не учетной записи хранения больших двоичных объектов.

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

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

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

Если вы используете расширение версии 5.x или выше (пакет 3.x или более поздней для стеков языка non-.NET), а не используете строка подключения с секретом, приложение может использовать удостоверение Microsoft Entra. Чтобы использовать удостоверение, вы определяете параметры под общим префиксом, который сопоставляется со connection свойством в конфигурации триггера и привязки.

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

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

1 <CONNECTION_NAME_PREFIX>__blobServiceUri можно использовать в качестве псевдонима. Если триггером BLOB-объекта будет использоваться конфигурация подключения, вместе blobServiceUri должно быть указано queueServiceUri. См. ниже.

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

Свойство Шаблон переменной среды Description Пример значения
Универсальный код ресурса службы BLOB-объектов <CONNECTION_NAME_PREFIX>__blobServiceUri URI плоскости данных службы BLOB-объектов, к которой вы подключаетесь, с помощью схемы HTTPS. https://<storage_account_name>.blob.core.windows.net
Универсальный код ресурса (URI) службы очередей (требуется для триггеров BLOB-объектов2) <CONNECTION_NAME_PREFIX>__queueServiceUri Универсальный код ресурса (URI) плоскости данных службы очередей, использующей схему HTTPS. Это значение требуется только для триггеров BLOB-объектов. https://<storage_account_name>.queue.core.windows.net

2Триггер BLOB-объекта обрабатывает сбой нескольких попыток и записывает подозрительные BLOB-объекты в очередь. В формеserviceUri используется подключение AzureWebJobsStorage. Однако если указать blobServiceUri, в универсальном коде ресурса (URI) службы очередей также должен быть указан queueServiceUri. Рекомендуется использовать службу из той же учетной записи хранения, что и служба BLOB-объектов. Кроме того, необходимо убедиться, что триггер может считывать и записывать сообщения в настроенной службе очередей, назначив роль, например участник данных очереди хранилища.

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

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

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

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

Внимание

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

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

Тип привязки Примеры встроенных ролей
Триггер Владелец данных BLOB-объектов хранилища и участникданных очереди хранилища 1

Дополнительные разрешения также должны быть предоставлены подключению AzureWebJobsStorage.2
Входные привязки читатель данных больших двоичных объектов хранилища.
Выходные привязки владелец данных BLOB-объектов хранилища;

1 Триггер BLOB-объекта обрабатывает сбой при нескольких попытках и записывает подозрительные BLOB-объекты в очередь в учетной записи хранения, указанной в подключении.

2 Подключение AzureWebJobsStorage используется во внутренней логике для BLOB-объектов и очередей, которые обеспечивают работу триггера. Если он настроен на использование подключения на основе удостоверений, он нуждается в дополнительных разрешениях за пределами требования по умолчанию. Необходимые разрешения охватываются ролями владельца данных BLOB-объектов хранилища, участника очередей хранилища и участника учетной записи хранения. Для получения дополнительных сведений см. раздел Подключение к хранилищу узла с помощью удостоверения.

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