Настройка подключений к удаленным службам в Функции Azure

Эта статья является основным справочником о том, как Функции Azure подключается к удалёным сервисам. Он предоставляет конкретные рекомендации по типу соединения и методу аутентификации.

Important

Используйте управляемые идентификаторы с Microsoft Entra ID, когда это возможно. Этот метод аутентификации устраняет секреты и обеспечивает высочайшую защиту.

Категории подключений

Подключения Функции Azure делятся на следующие основные категории:

  • Требуемый хост: Соединения, которые должен выполнять хост Functions, такие как хранение и мониторинг.
  • Привязки: Соединения, которыми хост управляет для ваших триггеров и привязок.
  • Клиентский SDK: соединения, которые вы создаёте и управляете в собственном функциональном коде.

Совет

Functions также поддерживает управляемые коннекторы (в предварительном просмотре), которые позволяют подключаться к сервисам вроде Office 365, Teams и SharePoint с встроенным OAuth и вебхуком через пространство имён Connector. Для получения дополнительной информации см. раздел Use connectors in Функции Azure.

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

  • AzureWebJobsStorage: Functions использует эту учётную запись хранения по умолчанию для обеспечения основной функциональности, такой как координация выполнения таймерных триггеров в режиме singleton и использование в качестве хранилища по умолчанию для ключей доступа к функциям. Хосту требуется это подключение к поддерживаемой учётной записи хранения. Ваше приложение не может запуститься без этой настройки соединения. Для получения дополнительной информации см. раздел Соображения хранения для Функции Azure.

  • APPLICATIONINSIGHTS_CONNECTION_STRING: Также необходимо настроить хост так, чтобы он записывал журналы в экземпляр Application Insights.

  • WEBSITE_AZUREFILESCONNECTIONSTRING: Используется только приложениями, работающими в плане Consumption или плане Elastic Premium. Определяет аккаунт хранилища, содержащий общий доступ Файлы Azure, поддерживающий пакет развертывания для вашего приложения.

Методы аутентификации

Important

По возможности используйте управляемые идентификаторы для своих соединений. Такой подход полностью устраняет секреты. Если целевой сервис не поддерживает аутентификацию Microsoft Entra ID, используйте Azure Key Vault для централизованного управления секретами. Используйте общие секреты напрямую в настройках приложения только в крайнем случае.

Functions поддерживает следующие методы аутентификации при подключении к удалёным сервисам:

Метод аутентификации Security Когда использовать
управляемые идентичности Самый высокий Сервис Target поддерживает Microsoft Entra ID. Нет секретов для управления.
Хранилище ключей Azure Высокий Сервис не поддерживает управляемые личности, или нужно централизованное управление секретами с ротацией.
Общий секрет Низко Устаревшее значение по умолчанию. Как можно скорее переходите на управляемые идентичности или Key Vault.

Выберите предпочитаемый метод аутентификации в начале статьи , чтобы увидеть подробные рекомендации по конфигурации.

Определите соединения

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

Окружающая среда Где хранятся настройки
Azure Настройки приложения (зашифрованы в состоянии покоя)
Локальная разработка local.settings.json (опционально зашифрован)

В обеих средах настройки отображаются в вашем коде как переменные среды. Конкретные настройки зависят как от типа соединения , так и от выбранного вами способа аутентификации .

Когда вы используете аутентификацию Microsoft Entra для подключения к сервису Azure, конкретные настройки приложения зависят от подключённого сервиса и от того, используете ли вы системную или пользовательскую идентификацию для аутентификации соединения.

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

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

  • В приложении, размещённом на Functions, соединения на основе идентичности используют управляемую идентичность. Системная идентификация, которая специфична для вашего приложения, используется по умолчанию. Однако идентификаторы, назначенные пользователями, которые также требуют свойств *__credential and *__clientID , более гибки и рекомендуются.

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

  • Подключения на основе идентичности поддерживаются только в версиях 4.x и более поздних версиях Functions. Если вы используете устаревшее C# приложение на версии 1.x Functions, сначала нужно перейти на версию 4.x.

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

Поддержка AzureWebJobsStorage управляемых идентичностей зависит от плана хостинга:

План размещения MI для хранилища хоста Требование Файлы Azure Recommendation
Использование Flex Полная поддержка Нет (без Файлы Azure) Рекомендуется при MI
Выделенный (Служба приложений) Полная поддержка Нет (нет динамического масштабирования) Полный MI, обходные пути не нужны
Потребление BLOB-объекты, очереди, таблицы Key Vault или удалить Файлы Azure Сохранить WEBSITE_AZUREFILESCONNECTIONSTRING в Key Vault
Elastic Premium BLOB-объекты, очереди, таблицы Key Vault или удалить Файлы Azure Сохранить WEBSITE_AZUREFILESCONNECTIONSTRING в Key Vault

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

  • Для тарифов Consumption и Premium реализуйте один из следующих обходных путей для Файлы Azure:

    • Храните в Key Vault только WEBSITE_AZUREFILESCONNECTIONSTRING строку подключения — это следующий по уровню безопасности вариант.
    • Создайте приложение Consumption или Premium, которое работает без Файлы Azure. При работе без Файлы Azure это влияет на производительность. Дополнительные сведения см. в разделе Создание приложения без Файлы Azure.

  • Для правильной работы этих триггеров требуется AzureWebJobsStorage:

    • Хранилище BLOB-объектов Azure (Азур Блоб Сторадж)
    • Центры событий Azure
    • Устойчивые функции (по умолчанию)
    • Timer

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

  • AzureWebJobsStorage сохраняет артефакты развертывания при серверной (удалённой) сборке в плане Linux Consumption. В этом случае необходимо развернуть и запустить приложение из внешнего пакета развертывания.

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

Эти конкретные настройки приложения определяют подключения на основе удостоверений как к AzureWebJobsStorage, так и к APPLICATIONINSIGHTS_CONNECTION_STRING:

Setting Description
AzureWebJobsStorage__blobServiceUri URI для Хранилище BLOB-объектов в учетной записи хранения по умолчанию. Требуется для суверенных облаков или пользовательского DNS для хранения, например: https://mystorageaccount.blob.contoso.com. HTTPS является обязательным.
AzureWebJobsStorage__queueServiceUri URI для хранилища очереди в учетной записи хранения по умолчанию. Требуется для суверенных облаков или пользовательского DNS для хранения, например: https://mystorageaccount.queue.contoso.com. HTTPS является обязательным.
AzureWebJobsStorage__tableServiceUri URI для хранения таблиц в учетной записи хранения по умолчанию. Требуется для суверенных облаков или пользовательского DNS для хранения, например: https://mystorageaccount.table.contoso.com. HTTPS является обязательным.
AzureWebJobsStorage__credential Установите значение managedidentity для использования аутентификации с использованием управляемой идентификации. Управляемая идентичность должна быть доступна в хостинговой среде.
AzureWebJobsStorage__clientId или
AzureWebJobsStorage__managedIdentityResourceId		 Возвращает конкретную пользовательскую идентичность, используемую для получения токена доступа для управляемой аутентификации. Когда ни то, ни другое не установлено, используется системно назначенная идентичность приложения.
APPLICATIONINSIGHTS_AUTHENTICATION_STRING Обеспечивает подключение к Application Insights с помощью аутентификации Microsoft Entra. Установите либо Authorization=AAD (системно-назначаемое), либо ClientId=<YOUR_CLIENT_ID>;Authorization=AAD (пользовательское назначение).

Поскольку значение двойного подчеркивания (__) интерпретируется во время выполнения как двоеточие (:), серия настроек интерпретируется как свойства объекта AzureWebJobsStorage . Например, рассмотрим следующие AzureWebJobsStorage настройки соединения:

  • AzureWebJobsStorage__blobServiceUri=https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net
  • AzureWebJobsStorage__queueServiceUri=https://<STORAGE_ACCOUNT_NAME>.queue.core.windows.net
  • AzureWebJobsStorage__tableServiceUri=https://<STORAGE_ACCOUNT_NAME>.table.core.windows.net
  • AzureWebJobsStorage__credential=managedidentity
  • AzureWebJobsStorage__clientId=<MY_USER_ASSIGNED_IDENTITY_ID>

Во время выполнения хост интерпретирует эти настройки как сложные AzureWebJobsStorage настройки.

"AzureWebJobsStorage":
{
    "blobServiceUri": "https://<STORAGE_ACCOUNT_NAME>.blob.core.windows.net",
    "queueServiceUri": "https://<STORAGE_ACCOUNT_NAME>.queue.core.windows.net",
    "tableServiceUri": "https://<STORAGE_ACCOUNT_NAME>.table.core.windows.net",
    "credential": "managedidentity",
    "clientId": "<MY_USER_ASSIGNED_IDENTITY_ID>"
}

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

Предоставление разрешений на идентификацию

Когда вы используете управляемые идентичности с аутентификацией Microsoft Entra ID, необходимо специально назначать права на идентичность, используемую вашим приложением при подключении к удалённому сервису. Самый простой способ предоставить наименьшие права для вашего приложения — назначать встроенные роли.

Имейте в виду эти рекомендации при предоставлении разрешений RBAC на идентификацию вашего приложения:

  • По возможности придерживайтесь принципа наименьших привилегий , предоставляя идентичности только минимальные необходимые привилегии. Например, если приложению нужно читать только из источника данных, используйте роль, которая даёт разрешение только на чтение, но не на запись данных.
  • Не используйте широкие встроенные роли, такие как Owner, даже просто чтобы приложение работало.
  • После создания или изменения назначения роли может пройти до 10 минут, прежде чем изменения вступят в силу. В это время ваша функция может получать ошибки авторизации (403), даже если роль назначена правильно. Если сразу после создания назначения роли возникают ошибки, подождите несколько минут и повторите попытку.
  • Когда для нескольких соединений требуется права на один сервис, используйте роль, которая является минимальным набором разрешений для всех соединений к этому сервису.
  • Некоторые привязки требуют более широких разрешений в вашей учетной записи хранилища, чем те, что требуется для AzureWebJobsStorage подключения.
  • Чтобы получить доступ к ключам в Key Vault с помощью управляемых идентичностей, назначьте своё приложение на роль пользователя Key Vault Secrets. Вы также можете использовать политику доступа Key Vault, чтобы назначить управляемой идентичности разрешение Get для секретов. Для получения дополнительной информации см. раздел «Предоставить личность в вашем приложении доступ к вашему хранилищу ключей».
  • В этой статье рассматриваются только встроенные роли, предоставляющие минимальные разрешения. В зависимости от требований вашего приложения вам может потребоваться создать собственные пользовательские роли.

Разрешения, которые вам нужны, зависят от типа соединения:

  • AzureWebJobsStorage: Роль Storage Blob Data Owner предоставляет минимально необходимые разрешения для учетной записи хранения для требуемого хостом подключения AzureWebJobsStorage. Эта роль обеспечивает уровень доступа к хранилищу, необходимый хосту Functions, при этом следуя принципу наименьших привилегий.

    Для некоторых типов проблем функции могут запускать диагностические события, чтобы помочь вам их устранить, даже если приложение не может запуститься. Также необходимо добавить роль Storage Table Data Contributor, которая предоставляет доступ к хранилищу таблиц, в котором сохраняются эти диагностические события. Без этих дополнительных разрешений вы можете увидеть предупреждения в логах о невозможности записать эти события.

    Для некоторых других привязок может потребоваться использовать несколько более широкую роль. В столбце Host-required storage таблицы на вкладке Bindings перечислены эти требования к ролям.

  • APPLICATIONINSIGHTS_AUTHENTICATION_STRING: Роль Monitoring Metrics Publisher предоставляет минимальные разрешения, необходимые хосту для подключения к Application Insights для логирования.

Примечание.

При использовании APPLICATIONINSIGHTS_AUTHENTICATION_STRING для подключения к Application Insights с помощью проверки подлинности Microsoft Entra необходимо также отключить локальную проверку подлинности для Application Insights. Эта конфигурация требует аутентификации Microsoft Entra для интеграции данных телеметрии в ваше рабочее пространство.

Примечание.

Используйте Key Vault только для соединений, которые в настоящее время не поддерживают Microsoft Entra ID с управляемыми идентичностями Azure.

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

Когда вы используете Key Vault, создайте настройки приложения для соединения, используя ссылку на Key Vault вместо самого секрета. Для получения дополнительной информации смотрите настройки приложения Source на Key Vault.

Имейте в виду следующие моменты при поддержании связей в Key Vault:

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

  • Вы можете использовать Key Vault для хранения настроек для управляемых идентификационных соединений. Если ваше приложение использует Key Vault, ссылки должны использовать разделитель ключей : или /, например Storage1:blobServiceUri. Когда вы используете стандартный разделитель параметров приложения __, не удаётся правильно разрешить ссылочные имена.

Вы можете настроить параметр AzureWebJobsStorage так, чтобы возвращать ссылку на Key Vault, содержащую строку подключения, вместо того чтобы возвращать саму строку подключения. Чтобы узнать, как это сделать, см. раздел Использование ссылок на Key Vault в качестве параметров приложения.

Файлы Azure в настоящее время не поддерживает управляемые идентификационные соединения. Из-за этого ограничения используйте Key Vault для защиты настройкиWEBSITE_AZUREFILESCONNECTIONSTRING, которая необходима для динамического масштабирования как в тарифах Consumption, так и в Premium. План Flex Consumption также является динамическим планом, который не использует Файлы Azure и полностью поддерживает управляемые идентификационные соединения.

Предостережение

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

Минимизируйте потенциальные риски утраты или скомпрометации секретов, используя управляемые идентичности с аутентификацией Microsoft Entra ID. Если удалённый сервис не поддерживает управляемые идентичности, по крайней мере используйте Azure Key Vault, который более надёжно сохраняет общие секреты.

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

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

Управление клиентскими соединениями SDK

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

Повторное использование экземпляров клиентов

Следуйте следующим рекомендациям при использовании сервис-специфического клиента в приложении Функции Azure:

  • Не создавайте нового клиента с каждым вызовом функций.
  • Создайте единый клиент, который будет повторно использоваться при каждом вызове функции.
  • Рассмотрим возможность создания одного общего клиента в вспомогательном классе, если разные функции используют один и тот же сервис.

Рекомендуемый подход зависит от вашего языка:

Используйте инъекцию зависимостей для регистрации одиночных или ограниченных клиентов.

См. примеры клиентского кода для полных паттернов на каждом языке.

Ограничения на количество подключений в плане Consumption

Примечание.

Описанные в этом разделе жёсткие ограничения на количество подключений применяются только к устаревшему плану Consumption. План Flex Consumption не работает в той же изолированной среде и на него не распространяются эти ограничения. Тем не менее, повторное использование клиентов по-прежнему рекомендуется во всех планах для оптимальной производительности.

В устаревшем плане Consumption приложения-функции выполняются в среде песочницы, которая ограничивает число исходящих подключений: 600 активных (1 200 всего) для каждого экземпляра. Когда вы достигаете этого предела, хост Functions записывает следующее сообщение в логи: Host thresholds exceeded: Connections. Дополнительные сведения см. в статье Ограничения служб функций.

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

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

Примеры кода клиента

В этом разделе даются рекомендации по созданию и использованию клиентов из вашего кода функции.

HTTP-запросы

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

using Microsoft.Azure.Functions.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;

[assembly: FunctionsStartup(typeof(MyNamespace.Startup))]

namespace MyNamespace;

public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        builder.Services.AddHttpClient();
    }
}

Затем введите IHttpClientFactory или HttpClient в ваш класс функций:

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

namespace MyNamespace;

public class MyFunction(HttpClient httpClient, ILogger<MyFunction> logger)
{
    [Function("MyFunction")]
    public async Task Run([TimerTrigger("0 */5 * * * *")] TimerInfo timer)
    {
        var response = await httpClient.GetAsync("https://example.com");
        logger.LogInformation("Response status: {Status}", response.StatusCode);
    }
}

Azure Cosmos DB clients

Зарегистрируйте CosmosClient как синглтон при запуске приложения, чтобы все функции использовали одно общее соединение. Документация Azure Cosmos DB рекомендует использовать singleton client на весь срок службы вашего приложения.

using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Functions.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection;

[assembly: FunctionsStartup(typeof(MyNamespace.Startup))]

namespace MyNamespace;

public class Startup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        builder.Services.AddSingleton(_ =>
        {
            var connectionString = Environment.GetEnvironmentVariable("CosmosDBConnection");
            return new CosmosClient(connectionString);
        });
    }
}

Затем введите CosmosClient в свой класс функций:

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

namespace MyNamespace;

public class MyCosmosFunction(CosmosClient cosmosClient, ILogger<MyCosmosFunction> logger)
{
    private readonly Container _container = cosmosClient.GetContainer("mydb", "mycontainer");

    [Function("MyCosmosFunction")]
    public async Task Run([TimerTrigger("0 */5 * * * *")] TimerInfo timer)
    {
        var item = new { id = "myId", partitionKey = "myPartitionKey", data = "example" };
        await _container.UpsertItemAsync(item, new PartitionKey("myPartitionKey"));
        logger.LogInformation("Item upserted");
    }
}

Подключения SqlClient

Код функции может использовать поставщика данных .NET Framework для SQL Server (SqlClient) для подключения к реляционной базе данных SQL. Этот провайдер также является базовым поставщиком фреймворков данных, основанных на ADO.NET, таких как Entity Framework. В отличие от соединений HttpClient и DocumentClient ADO.NET осуществляет объединение подключений в пул по умолчанию. Тем не менее, стоит оптимизировать подключения к базе данных, потому что вы по-прежнему можете остаться без подключений. Дополнительные сведения см. в разделе Объединение подключений в пул в SQL Server (ADO.NET).

Совет

Некоторые платформы данных, такие как Entity Framework, обычно получают строки подключений из раздела файла конфигурации ConnectionStrings. В этом случае необходимо добавить строки подключений базы данных SQL непосредственно в список функциональных настроек приложения Строки подключения и в файл local.settings.json в локальном проекте. Если вы создаёте экземпляр SqlConnection в вашем функциональном коде, храните значение строка подключения в настройках приложения вместе с другими соединениями.

Конфигурация приложений Azure

Конфигурация приложений Azure — это сервис Azure, который можно использовать для централизованного управления настройками приложений. App Configuration поддерживает иерархические пары «ключ — значение» и управление версиями, а также интегрируется с Azure Key Vault для более безопасного хранения секретов и управления ими. Дополнительные сведения см. в статье "Что такое конфигурация приложений Azure"?

Для повышения безопасности ваше функциональное приложение использует управляемые идентификаторы с аутентификацией Microsoft Entra для доступа к настройкам в Магазине приложений. Для получения дополнительной информации см. Использование ссылок на App Configuration для Функции Azure.

Примечание.

При использовании Конфигурация приложений Azure для хранения параметров подключений на основе управляемой идентификации в ссылках должен использоваться разделитель ключей : или / в формате <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace. Когда вы используете стандартный разделитель параметров приложения __, не удаётся правильно разрешить ссылочные имена.

Связанные материалы

  • Last updated on