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

Привязка выходных данных хранилища 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 и создает новый текстовый файл в выходном контейнере на основе имени активированного файла.

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    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, использование OutputBinding (Java)

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

  @FunctionName("copyBlobHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage copyBlobHttp(
    @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,
    @BlobOutput(
      name = "target", 
      path = "myblob/{Query.file}-CopyViaHttp")
    OutputBinding<String> outputItem,
    final ExecutionContext context) {
      // Save blob to outputItem
      outputItem.setValue(new String(content, StandardCharsets.UTF_8));

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

Триггер очереди, использование возвращаемого значения функции (Java)

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

  @FunctionName("copyBlobQueueTrigger")
  @StorageAccount("Storage_Account_Connection_String")
  @BlobOutput(
    name = "target", 
    path = "myblob/{queueTrigger}-Copy")
  public String copyBlobQueue(
    @QueueTrigger(
      name = "filename", 
      dataType = "string",
      queueName = "myqueue-items") 
    String filename,
    @BlobInput(
      name = "file", 
      path = "samples-workitems/{queueTrigger}") 
    String content,
    final ExecutionContext context) {
      context.getLogger().info("The content of \"" + filename + "\" is: " + content);
      return content;
  }

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

В следующем примере показана функция 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-объекта в качестве выходных данных функции PowerShell.

В файле конфигурации функции (function.json) свойство метаданных trigger используется для указания имени BLOB-объекта в свойствах path.

Примечание.

Чтобы избежать создания бесконечного цикла, убедитесь, что входные и выходные пути различаются.

{
  "bindings": [
    {
      "name": "myInputBlob",
      "path": "data/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in",
      "type": "blobTrigger"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "data/copy/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

Вот полный текст кода PowerShell:

# Input bindings are passed in via param block.
param([byte[]] $myInputBlob, $TriggerMetadata)
Write-Host "PowerShell Blob trigger function Processed blob Name: $($TriggerMetadata.Name)"
Push-OutputBinding -Name myOutputBlob -Value $myInputBlob

В следующем примере показаны входные и выходные привязки больших двоичных объектов. Пример зависит от того, используется ли модель программирования Python версии 1 или версии 2.

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

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#.

Конструктор BlobOutputAttribute принимает следующие параметры:

Параметр Описание
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 Строка подключения учетной записи хранения.
dataType Для динамически типизированных языков указывает базовый тип данных. Возможные значения: string, binaryили stream. Дополнительные сведения см. в разделе Определения триггеров и привязок.

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

Заметки

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

Настройка

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

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

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

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

Свойство Описание
type Должен иметь значениеblob.
direction Нужно задать значение out для выходной привязки. Исключения приведены в этом разделе.
name Имя переменной, представляющей большой двоичный объект в коде функции. Задайте значение $return, ссылающееся на возвращаемое значение функции.
path Путь к контейнеру BLOB-объектов.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к BLOB-объектам Azure. См. раздел Подключения.

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

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

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

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

Тип Описание
string Содержимое большого двоичного объекта в виде строки. Используется, когда содержимое большого двоичного объекта является простым текстом.
byte[] Байты содержимого большого двоичного объекта.
Сериализуемые в JSON типы Объект, представляющий содержимое БОЛЬШОго двоичного объекта JSON. Функции пытаются сериализовать обычный тип объекта CLR (POCO) в данные JSON.

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

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

Для других выходных сценариев создайте и используйте blobClient или BlobContainerClient с другими типами из Azure.Storage.Blobs напрямую. Пример использования внедрения зависимостей для создания типа клиента из пакета SDK Azure см. в статье "Регистрация клиентов Azure".

Привязку 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.

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

Доступ к данным большого двоичного объекта путем возврата значения напрямую или с помощью context.extraOutputs.set().

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

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

  • Строки — как func.Out[str]
  • Потоки — как func.Out[func.InputStream]

Дополнительные сведения см. в примере выходных данных.

Связи

Это 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-объектов хранилища, участника очередей хранилища и участника учетной записи хранения. Для получения дополнительных сведений см. раздел Подключение к хранилищу узла с помощью удостоверения.

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

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

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