Руководство разработчиков Функций Azure

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

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

Код функции

Ключевым элементом решения "Функции Azure" является функция . Функция состоит из двух важных частей: ваш код, написан на разных языках, и файл конфигурации function.json. Для компилируемых языков этот файл создается автоматически из заметки к вашему коду. Для сценарных языков вы должны предоставить файл конфигурации самостоятельно.

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

{
    "disabled":false,
    "bindings":[
        // ... bindings here
        {
            "type": "bindingType",
            "direction": "in",
            "name": "myParamName",
            // ... more depending on binding
        }
    ]
}

Дополнительные сведения см. в разделе Основные понятия триггеров и привязок в Функциях Azure.

В свойстве bindings указываются свойства триггеров и привязок. Каждая привязка имеет ряд общих параметров и некоторые параметры, характерные для данного типа привязки. Для каждой привязки требуются указанные ниже параметры.

Свойство Значения Type Комментарии
тип Имя привязки.

Например, queueTrigger.
строка
direction in, out строка Указывает, служит ли привязка для получения данных в функции или для отправки их из функции.
name Идентификатор функции.

Например, myQueue.
строка Имя, используемое для связанных данных в функции. Для C# это имя аргумента, а для JavaScript — ключ в списке ключей и значений.

Приложение-функция

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

Примечание

Все функции в приложении-функции должны использовать один язык. Это не было обязательным в предыдущих версиях среды выполнения "Функции Azure".

Структура папок

Код всех функций приложения-функции хранится в корневой папке проекта, содержащей файл конфигурации главного узла. Файл host.json содержит конфигурацию среды выполнения. Он находится в корневой папке приложения-функции. Папка bin содержит пакеты и другие файлы библиотек, необходимые для работы приложения-функции. Структура папок, необходимая для приложения-функции, зависит от языка:

В версии 2.x и более поздних среды выполнения Функций Azure все функции в приложении-функции следует создавать на одном языке.

Выше приведена структура папки по умолчанию (рекомендуемая) для приложения-функции. Если вы желаете изменить расположение файла кода функции, измените раздел scriptFile в файле function.json. Мы рекомендуем развертывать проект в приложение-функцию в Azure путем развертывания пакета. Вы также можете использовать имеющиеся средства, такие как непрерывная интеграция и развертывание и Azure DevOps.

Примечание

Если вы развертываете пакет вручную, убедитесь, что развертываете файл host.json и папки функций непосредственно в папку wwwroot. Не включайте папку wwwroot в развертывания. В противном случае вы получите папки wwwroot\wwwroot.

Использование локальных инструментов и публикация

Приложения-функции можно разрабатывать и публиковать с помощью различных средств, включая Visual Studio, Visual Studio Code, IntelliJ, Eclipse и Azure Functions Core Tools. Дополнительные сведения см. в статье Как программировать и тестировать Функции Azure в локальной среде.

Редактирование функций на портале Azure

Редактор функций на портале Azure позволяет обновлять файл function.json и файл кода для функции непосредственно на портале. Рекомендуется использовать его только для небольших изменений или для подтверждения концепции. Наиболее оптимальным способом является использование локального средства разработки, например, VS Code.

Параллельное выполнение

Если однопотоковая среда выполнения функций не успевает обрабатывать активируемые события, она может вызывать функцию несколько раз в параллельном режиме. Если для приложения-функции используется план потребления, это приложение может автоматически развертываться. Каждый экземпляр приложения-функции, как при использовании плана потребления, так и при использовании обычного плана размещения службы приложений, может обрабатывать несколько параллельных вызовов функции с помощью нескольких потоков. Максимальное количество одновременных вызовов функции в каждом экземпляре приложения-функции зависит от типа триггера и ресурсов, используемых функциями в приложении-функции.

Управление версиями среды выполнения Функций

Версию среды выполнения Функций можно настроить с помощью параметра приложения FUNCTIONS_EXTENSION_VERSION. Например, значение "~3" указывает на то, что приложение-функция будет использовать 3.x в качестве основного номера версии. При выпуске приложения-функции обновляются до версии с новым дополнительным номером. Дополнительные сведения, в том числе инструкции по просмотру точной версии приложения-функции см. в статье Выбор целевых версий среды выполнения Функций Azure.

Репозитории

Код функций Azure имеет вид открытого исходного кода и хранится в репозиториях GitHub:

Привязки

В таблице ниже приведены все поддерживаемые привязки.

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

Тип 1.x 2.x и выше1 Триггер Входные данные Выходные данные
Хранилище BLOB-объектов
Azure Cosmos DB
Dapr3
Сетка событий
Центры событий
HTTP и веб-перехватчики
Центр Интернета вещей
Kafka2
Мобильные приложения
Центры уведомлений
Хранилище очередей
RabbitMQ2
SendGrid
Служебная шина
SignalR
Хранилище таблиц
Таймер
Twilio

1 Начиная со среды выполнения версии 2.х, все привязки, кроме HTTP и Timer, должны быть зарегистрированы. Ознакомьтесь с разделом Регистрация расширений привязки.

2 Триггеры не поддерживаются в плане потребления. Требуются триггеры, управляемые средой выполнения.

3 Поддерживается только в Kubernetes, IoT Edge и других автономных режимах.

Проблемы с ошибками, поступающими от привязок? См. документацию по кодам ошибок Функций Azure.

Соединения

Проект функции ссылается на сведения о подключении по имени от поставщика конфигурации. Он не принимает напрямую сведения о подключении, позволяя изменять их в разных средах. Например, определение триггера может включать в себя свойство connection. Это может указывать на строку подключения, но строку подключения нельзя задать непосредственно в function.json. Вместо этого следует задать для connection имя переменной среды, содержащей строку подключения.

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

Значения подключений

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

Однако имя соединения также может ссылаться на коллекцию нескольких элементов конфигурации, что полезно для настройки подключений на основе удостоверений. Переменные среды можно представить как коллекцию с помощью общего префикса, заканчивающегося двойными символами подчеркивания __. На эту группу можно ссылаться, задав имя подключения для этого префикса.

Например, connection свойство для определения триггера большого двоичного объекта Azure может иметь значение "Storage1". При условии отсутствия ни одного строкового значения, настроенного переменной среды с именем "Storage1", переменная среды с именем Storage1__blobServiceUri может использоваться для информирования blobServiceUri Свойства о соединении. Свойства подключения у всех служб различны. См. документацию по компоненту, использующему подключение.

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

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

Подключения на основе удостоверений поддерживаются следующими компонентами:

Источник подключения Поддерживаемые планы Подробнее
Триггеры и привязки BLOB-объектов Azure — Предварительная версия Все Расширение 5.0.0-beta1 или более поздняя версия
Триггеры и привязки очередей Azure — Предварительная версия Все Расширение 5.0.0-beta1 или более поздняя версия
Триггеры и привязки концентраторов событий Azure — Предварительная версия Все Расширение 5.0.0-beta1 или более поздняя версия
триггеры и привязки Azure служебная шина — предварительная версия Все Расширение 5.0.0-бета или более поздняя версия
триггеры и привязки Azure Cosmos DB — предварительная версия Эластичные Premium Версия расширения 4.0.0-preview1: или более поздняя
Хранилище, требуемое для узла ("AzureWebJobsStorage") — Предварительная версия Все Подключение к хранилищу узла с помощью удостоверения

Примечание

Подключения на основе удостоверений не поддерживаются для Устойчивых функций.

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

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

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

Важно!

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

Выберите вкладку ниже, чтобы узнать о разрешениях для каждого компонента:

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

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

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

Общие свойства для подключений на основе удостоверений

Подключение на основе удостоверений для службы Azure принимает следующие общие свойства, где <CONNECTION_NAME_PREFIX> — это значение connection свойства в триггере или определении привязки:

Свойство Шаблон переменной среды Описание
Учетные данные маркера <CONNECTION_NAME_PREFIX>__credential Определяет, как должен быть получен маркер для соединения. Рекомендуется использовать только с назначаемым пользователем удостоверением, если для него задается значение "managedidentity". Это допустимо только при размещении в службе Функций Azure.
Идентификатор клиента <CONNECTION_NAME_PREFIX>__clientId Если для параметра credential задано значение "managedidentity", это свойство обозначает назначаемое пользователем удостоверение, которое будет использоваться при получении маркера. Свойство принимает идентификатор клиента, соответствующий назначаемому пользователем удостоверению, которое назначено приложению. По умолчанию для приложения будет использоваться удостоверение, назначаемое системой. Это свойство используется по-разному в локальных сценариях разработки, когда credential не задается.

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

Локальная разработка с использованием подключений на основе удостоверений

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

  • локальный кэш, совместно используемый приложениями Майкрософт;
  • контекст текущего пользователя в Visual Studio;
  • контекст текущего пользователя в Visual Studio Code;
  • контекст текущего пользователя в Azure CLI.

Если ни один из этих вариантов не будет успешным, будет возникать ошибка.

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

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

Свойство Шаблон переменной среды Описание
Tenant ID <CONNECTION_NAME_PREFIX>__tenantId Идентификатор клиента (каталога) Azure Active Directory.
Идентификатор клиента <CONNECTION_NAME_PREFIX>__clientId Идентификатор клиента (приложения) для регистрации приложения в клиенте.
Секрет клиента <CONNECTION_NAME_PREFIX>__clientSecret Секрет клиента, созданный для регистрации приложения.

Ниже приведен пример свойств, local.settings.json необходимых для подключения на основе удостоверений к BLOB-объектам Azure.

{
  "IsEncrypted": false,
  "Values": {
    "<CONNECTION_NAME_PREFIX>__blobServiceUri": "<blobServiceUri>",
    "<CONNECTION_NAME_PREFIX>__queueServiceUri": "<queueServiceUri>",
    "<CONNECTION_NAME_PREFIX>__tenantId": "<tenantId>",
    "<CONNECTION_NAME_PREFIX>__clientId": "<clientId>",
    "<CONNECTION_NAME_PREFIX>__clientSecret": "<clientSecret>"
  }
}

Подключение к хранилищу узла с удостоверением (Предварительная версия)

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

Внимание!

Другие компоненты в функциях используют "AzureWebJobsStorage" для поведения по умолчанию. Не следует перемещать его в подключение на основе удостоверений, если используются более старые версии расширений, которые не поддерживают этот тип подключения, включая триггеры и привязки для больших двоичных объектов и концентраторов событий Azure. Аналогичным образом AzureWebJobsStorage используется для артефактов развертывания при использовании сборки на стороне сервера в Linux, а если это необходимо, необходимо выполнить развертывание с помощью внешнего пакета развертывания.

Кроме того, некоторые приложения повторно используют "AzureWebJobsStorage" для других подключений к хранилищу в своих триггерах, привязках и (или) коде функции. Убедитесь, что все варианты использования "AzureWebJobsStorage" могут использовать формат подключения на основе удостоверений, прежде чем изменять это соединение из строки подключения.

Чтобы использовать подключение на основе удостоверений для "AzureWebJobsStorage", настройте следующие параметры приложения:

Параметр Описание Пример значения
AzureWebJobsStorage__blobServiceUri URI плоскости данных для службы BLOB-объектов учетной записи хранения. <storage_account_name>. blob.core.windows.net
AzureWebJobsStorage__queueServiceUri URI плоскости данных службы очередей учетной записи хранения. <storage_account_name>. queue.core.windows.net

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

Если вы используете учетную запись хранения, использующую суффикс DNS по умолчанию и имя службы для глобального Azure, https://<accountName>.blob/queue/file/table.core.windows.net то в следующем формате вместо него можно задать AzureWebJobsStorage__accountName имя вашей учетной записи хранения. Конечные точки большого двоичного объекта и очереди будут выводиться для этой учетной записи. Это не будет работать, если учетная запись хранения находится в независимых облаке или в ней есть пользовательская служба DNS.

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

Создание отчетов о проблемах

Элемент Описание Ссылка
Параметры выполнения Сервер сценариев, триггеры и привязки, языковая поддержка Сообщить о проблеме
Шаблоны Проблемы с кодом при использовании шаблона создания Сообщить о проблеме
Портал Проблемы с пользовательским интерфейсом или при работе с ним Сообщить о проблеме

Дальнейшие действия

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