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

  • Статья
  • Чтение занимает 19 мин

Некоторые из Функций 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 ✔ ✔ ✔ ✔ ✔
Azure SQL (предварительная версия)2 ✔ ✔ ✔ ✔
Dapr3 ✔ ✔ ✔ ✔
Сетка событий ✔ ✔ ✔ ✔
Центры событий ✔ ✔ ✔ ✔
HTTP и веб-перехватчики ✔ ✔ ✔ ✔
Центр Интернета вещей ✔ ✔ ✔
Kafka2 ✔ ✔ ✔
Мобильные приложения ✔ ✔ ✔
Центры уведомлений ✔ ✔
Хранилище очередей ✔ ✔ ✔ ✔
RabbitMQ2 ✔ ✔ ✔
SendGrid ✔ ✔ ✔
Служебная шина ✔ ✔ ✔ ✔
SignalR ✔ ✔ ✔ ✔
Хранилище таблиц ✔ ✔ ✔ ✔
Таймер ✔ ✔ ✔
Twilio ✔ ✔ ✔

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

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

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

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

Соединения

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

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

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

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

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

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

Примечание

При использовании Конфигурации приложений Azure или Key Vault для предоставления параметров подключений Управляемого удостоверения имена параметров должны использовать допустимый разделитель ключей, например : или /, вместо __, чтобы обеспечить правильное разрешение имен.

Например, Storage1:blobServiceUri.

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

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

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

Источник подключения Поддерживаемые планы Подробнее
Триггеры и привязки BLOB-объектов Azure Все Расширение BLOB-объектов Azure версии 5.0.0 или более поздней
Пакет расширений 3.3.0 или более поздней версии
Триггеры и привязки очередей Azure Все Расширение очередей Azure версии 5.0.0 или более поздней
Пакет расширений 3.3.0 или более поздней версии
Таблицы Azure (при использовании службы хранилища Azure) Все Расширение Таблиц Azure версии 1.0.0 или более поздней;
Пакет расширений 3.3.0 или более поздней версии
Триггеры и привязки центров событий Azure Все Центры событий Azure расширения версии 5.0.0 или более поздней
Пакет расширений 3.3.0 или более поздней версии
Триггеры и привязки служебной шины Azure Все Служебная шина Azure расширения версии 5.0.0 или более поздней
Пакет расширений 3.3.0 или более поздней версии
Триггеры и привязки Azure Cosmos DB Все Расширение Azure Cosmos DB версии 4.0.0 или более поздней
Пакет расширений 4.0.2 или более поздней версии
Поставщик хранилища для Устойчивых функций (служба хранилища Azure) — предварительная версия Все Устойчивые функции расширения версии 2.7.0 или более поздней
Пакет расширений 3.3.0 или более поздней версии
Хранилище, требуемое для узла (AzureWebJobsStorage) — предварительная версия Все Подключение к хранилищу узла с помощью удостоверения

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

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

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

Важно!

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

Для локальной разработки с подключениями на основе удостоверений требуются обновленные версии Azure Functions Core Tools. Текущую установленную версию можно узнать с помощью команды func -v. Для функций версии 3 используйте версию 3.0.3904 или более позднюю. Для функций версии 4 используйте версию 4.0.3904 или более позднюю.

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

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

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

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

В некоторых случаях может потребоваться указать другое удостоверение. Вы можете добавить свойства конфигурации для подключения, которое указывает на альтернативное удостоверение на основе идентификатора клиента и секрета клиента для субъекта-службы 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. Их не следует переводить на использование подключений на основе удостоверений, если вы используете более старые версии расширений, которые не поддерживают данный тип подключения, включая триггеры и привязки для BLOB-объектов Azure, центры событий и устойчивые функции. Аналогичным образом для артефактов развертывания используется AzureWebJobsStorage, когда используется серверная сборка в потреблении Linux и, если вы включите этот параметр, вам потребуется выполнить развертывание с помощью внешнего пакета развертывания.

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

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

Параметр Описание Пример значения
AzureWebJobsStorage__blobServiceUri Универсальный код ресурса (URI) плоскости данных службы BLOB-объектов учетной записи хранения, использующей схему HTTPS. https://<storage_account_name>.blob.core.windows.net
AzureWebJobsStorage__queueServiceUri Универсальный код ресурса (URI) плоскости данных службы очередей учетной записи хранения, использующей схему HTTPS. https://<storage_account_name>.queue.core.windows.net
AzureWebJobsStorage__tableServiceUri Универсальный код ресурса (URI) плоскости данных службы таблиц учетной записи хранения, использующей схему HTTPS. https://<storage_account_name>.table.core.windows.net

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

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

Параметр Описание Пример значения
AzureWebJobsStorage__accountName Имя учетной записи хранения, допустимо только в том случае, если учетная запись не находится в национальном облаке и не имеет пользовательскую DNS. Этот синтаксис предназначен исключительно для "AzureWebJobsStorage" и не может использоваться для других подключений на основе удостоверений. <storage_account_name>

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

Расширение Необходимые роли Описание
Без расширения (только узел) владелец данных BLOB-объектов хранилища; Используется для общей координации, хранилище ключей по умолчанию
BLOB-объекты Azure (только триггер) Все из:
Участник учетной записи хранения,
Владелец данных BLOB-объектов хранилища,
Участник для данных очереди хранилища		 Триггер BLOB-объектов использует очереди Azure во внутренней структуре и записывает команды для BLOB-объектов. Для них используется атрибут AzureWebJobsStorage независимо от подключения, настроенного для триггера.
Центры событий Azure (только триггер) (без изменения требований по умолчанию)
владелец данных BLOB-объектов хранилища;		 Контрольные точки сохраняются в BLOB-объектах с помощью подключения AzureWebJobsStorage.
Триггер таймера (без изменения требований по умолчанию)
владелец данных BLOB-объектов хранилища;		 Чтобы обеспечить одно выполнение для каждого события, блокировки берутся их BLOB-объектов с помощью подключения AzureWebJobsStorage.
Устойчивые функции Все из:
Участник для данных BLOB-объектов хранилища,
Участник для данных очереди хранилища,
Участник данных таблицы хранилища		 Устойчивые функции использует BLOB-объекты, очереди и таблицы для координации функций действий и поддержания состояния оркестрации. По умолчанию для всех этих подключений используется подключение AzureWebJobsStorage, но в конфигурации расширения Устойчивые функции можно указать другое подключение.

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

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

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

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