Запуск основных инструментов службы "Функции Azure"

Средства Azure Functions Core Tools позволяют разрабатывать и тестировать функции на локальном компьютере из командной строки или в терминале. Локальные функции можно подключать к действующим службам Azure, а отладку функций можно выполнять на локальном компьютере с помощью полной среды выполнения службы "Функции Azure". Также есть возможность развернуть приложение-функцию в подписке Azure.

Примечание

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

Разработка функций на локальном компьютере и их публикация в Azure с помощью Core Tools включает следующие основные действия:

Предварительные требования

Конкретные предварительные требования для Core Tools зависят от функций, которые планируется использовать:

Публикация: Core Tools сейчас используют Azure CLI или Azure PowerShell для проверки подлинности учетной записи Azure. Это означает, что вам нужно установить одно из этих средств для поддержки публикации в Azure из Azure Functions Core Tools.

Установка расширений: Чтобы вручную установить расширения с помощью Core Tools, необходимо установить пакет SDK для .NET Core 3.1. Служба Core Tools используется пакет SDK для .NET Core для установки расширений из NuGet. Вам не требуется знание .NET для использования расширений функций Azure.

Версии Core Tools

Есть четыре версии основных инструментов службы Azure Functions Core Tools. Используемая версия зависит от локальной среды разработки, выбора языка и требуемого уровня поддержки.

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

Поддерживает версию 4.x среды выполнения Функций. Эта версия работает в ОС Windows, macOS и Linux, а также и использует диспетчеры пакетов для конкретных платформ или диспетчер npm для установки. Это рекомендуемая версия среды выполнения Функций и основных средств.

На каждом компьютере можно установить только одну версию Core Tools. Если не указано иное, все примеры в этой статье применимы к версии 3.x.

Установка основных инструментов Функций Azure

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

Начиная с версии 2.x, Core Tools работает в Windows, macOS и Linux.

Следующая процедура устанавливает Core Tools версии v4.x с помощью установщика Windows (MSI). Дополнительные сведения о других установщиках на основе пакетов, см. в файле readme для Core Tools.

Скачайте и запустите установщик Core Tools для используемой версии Windows:

Изменение версии основных инструментов

При переходе на другую версию Core Tools следует использовать тот же диспетчер пакетов, что и исходная установка для перехода на другую версию пакета. Например, если вы установили Core Tools версии 2.x с помощью npm, выполните следующую команду для обновления до версии 3.x:

npm install -g azure-functions-core-tools@3 --unsafe-perm true

Если вы использовали установщик Windows (MSI) для установки Core Tools на Windows, перед установкой другой версии следует удалить старую версию из области "Добавление и удаление программ".

Создание локального проекта службы "Функции"

Каталог проекта функций содержит следующие файлы и папки для любого языка:

Имя файла Описание
host.json Дополнительные сведения см. в справке по файлу host.json.
local.settings.json Параметры, используемые инструментами Core Tools при локальном запуске, включая параметры приложения. Подробнее см. в разделе о локальных параметрах.
.gitignore Предотвращает случайную публикацию файла local.settings.json в репозитории Git. Подробнее см. в разделе о локальных параметрах.
.vscode\extensions.json Файл параметров, используемый при открытии папки проекта в Visual Studio Code.

Дополнительные сведения о папке проекта службы "Функции Azure" см. в Руководстве для разработчиков по Функциям Azure.

В окне терминала или из командной строки выполните следующую команду, чтобы создать проект и локальный репозиторий Git:

func init MyFunctionProj

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

Ниже приведены рекомендации относительно инициализации проекта.

  • Если вы не укажете в команде параметр --worker-runtime, вам будет предложено выбрать язык. Дополнительные сведения см. в справочнике по функции init.

  • Если имя проекта не указано, выполняется инициализация текущей папки.

  • Если вы планируете опубликовать проект в настраиваемом контейнере Linux, используйте параметр --docker, чтобы убедиться, что для проекта создан Dockerfile. Дополнительные сведения см. в статье Создание функции в Linux с помощью пользовательского образа.

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

  • Core Tools позволяет создавать проекты приложений-функций для среды выполнения .NET как внутрипроцессные , так и изолированные проекты библиотеки классов C# (CSPROJ). Эти проекты, которые можно использовать с Visual Studio или Visual Studio Code, компилируются во время отладки и при публикации в Azure.

  • Если вы хотите работать локально с файлами скриптов C# (CSX), используйте параметр --csx. Это те же файлы, которые вы получаете при создании функций на портале Azure и при использовании инструментов Core Tools версии 1.x. Дополнительные сведения см. в справочнике по функции init.

Регистрация расширений

Начиная с версии 2.x среды выполнения триггеров и привязок функций реализуются как пакеты расширения .NET (NuGet). Для скомпилированных проектов C# достаточно просто добавить ссылки на пакеты расширений NuGet для конкретных триггеров и привязок. Для привязок HTTP и триггеров таймера расширения не требуются.

Чтобы оптимизировать процесс разработки проектов не на C #, в Функциях можно добавлять ссылки на пакеты расширений с поддержкой управления версиями в файле host.json проекта. Пакеты расширений делают все расширения доступными для вашего приложения и исключают возможность возникновения проблем совместимости пакетов между расширениями. Пакеты расширений также избавляют от необходимости устанавливать пакет SDK для .NET Core 3.1.x и работать с файлом extensions.csproj.

Пакеты расширений рекомендуется использовать в проектах функций, не являющихся скомпилированными проектами на C#, а также в скриптах C#. Для таких проектов параметр пакета расширений создается в файле host.json во время инициализации. Если пакеты не включены, необходимо обновить файл host.json проекта.

Самый простой способ установить расширения привязки — включить пакеты расширений. При этом автоматически устанавливается набор стандартных пакетов расширений.

Чтобы включить пакеты расширений, откройте файл host.json и обновите его содержимое так, чтобы оно соответствовало следующему коду:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[2.*, 3.0.0)"
    }
}

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

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

Локальные параметры

При запуске в приложении-функции в Azure параметры для функций безопасно хранятся в параметрах приложения. Во время локальной разработки эти параметры добавляются в объект Values в файле local.settings.json. Файл local.settings.json также хранит параметры, используемые локальными средствами разработки.

Так как файл local.settings.json может содержать секреты, например строки подключения, его не следует хранить в удаленном репозитории. Дополнительные сведения о локальных параметрах см. в разделе Файл локальных параметров.

По умолчанию эти параметры не переносятся автоматически при публикации проекта в Azure. При публикации используйте параметр --publish-local-settings, позволяющий добавить эти настройки в приложение-функцию в Azure. Значения из раздела ConnectionStrings никогда не публикуются.

Эти значения параметров приложения-функции также могут считываться в коде как переменные среды. Дополнительные сведения см. в разделе о переменных среды в этих справочниках для определенного языка:

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

Отсутствует значение AzureWebJobsStorage в local.settings.json. This is required for all triggers other than HTTP. You can run 'func azure functionapp fetch-app-settings <functionAppName>' or specify a connection string in local.settings.json (Оно требуется для всех триггеров, отличных от HTTP. Выполните команду func azure functionapp fetch-app-settings <имя_приложения_функции> или укажите строку подключения в файле local.settings.json).

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

Даже при использовании эмулятора хранения Azurite для разработки может потребоваться запустить локально с фактическим подключением к хранилищу. Если ваша учетная запись хранения создана, действительную строку подключения к хранилищу можно получить одним из следующих способов:

  1. На портале Azure найдите и выберите Учетные записи хранения.

    На портале Azure выберите

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

    Копирование строки подключения с портала Microsoft Azure

Создание функции

Чтобы создать функцию в существующем проекте, выполните следующую команду:

func new

В версии 3.x/2.x при запуске func new вам будет предложено выбрать шаблон на языке по умолчанию для приложения-функции. Далее вам будет предложено выбрать имя функции. В версии 1.x также предлагается выбрать язык.

Вы также можете указать имя функции и шаблон в команде func new. В примере ниже используется параметр --template для создания триггера HTTP с именем MyHttpTrigger.

func new --template "Http Trigger" --name MyHttpTrigger

В этом примере создается триггер Хранилища очередей с именем MyQueueTrigger:

func new --template "Azure Queue Storage Trigger" --name MyQueueTrigger

Дополнительные сведения см. в описании команды func new.

Запуск функций в локальной среде

Чтобы запустить проект Функций, необходимо запустить узел Функций из корневого каталога проекта. Узел включает триггеры для всех функций в проекте. Команда start запуска зависит от языка проекта.

func start

Примечание

Вместо этого версия 1.x среды выполнения Функций требует func host start. Дополнительные сведения см. в Справочных материалах по Azure Functions Core Tools.

При запуске узла службы "Функции" выводится URL-адрес функций, активируемых по HTTP, как в следующем примере:

Found the following functions:
Host.Functions.MyHttpTrigger

Job host started
Http Function MyHttpTrigger: http://localhost:7071/api/MyHttpTrigger

Важно!

При запуске в локальной среде авторизация для конечных точек HTTP не требуется. Это означает, что все локальные HTTP-запросы будут обрабатываться как authLevel = "anonymous". Дополнительные сведения см. в статье о привязке HTTP.

Передача тестовых данных в функцию

Чтобы протестировать функции в локальной среде, запустите узел службы "Функции" и вызовите конечные точки на локальном сервере, используя HTTP-запросы. Вызываемая конечная точка зависит от типа функции.

Примечание

В примерах в этой статье используется инструмент cURL для отправки HTTP-запросов из терминала или командной строки. Вы можете использовать любой инструмент для отправки HTTP-запросов к локальному серверу. Средство cURL доступно по умолчанию во всех системах на основе Linux и в Windows 10 сборки 17063 и выше. В более старых версиях Windows необходимо сначала скачать и установить средство cURL.

Дополнительные сведения о тестировании функций см. в статье Методика тестирования кода с помощью Функций Azure.

Функции, активируемые по протоколу HTTP или с помощью веб-перехватчика

Вызовите следующую конечную точку, чтобы запустить в локальной среде функции, активируемые по протоколу HTTP или с помощью веб-перехватчика.

http://localhost:{port}/api/{function_name}

Используйте то же имя сервера и порт, прослушиваемый узлом службы "Функции". Их можно найти в выходных данных, полученных при запуске узла службы "Функции". Этот URL-адрес можно вызвать с помощью любого метода HTTP с поддержкой триггера.

Следующая команда cURL активирует функцию быстрого запуска MyHttpTrigger из запроса GET с параметром name, который передается в строке запроса.

curl --get http://localhost:7071/api/MyHttpTrigger?name=Azure%20Rocks

В следующем примере представлена та же функция, вызываемая из запроса POST с передачей параметра name в тексте запроса:

curl --request POST http://localhost:7071/api/MyHttpTrigger --data '{"name":"Azure Rocks"}'

Запросы GET можно выполнять из браузера, передавая данные в строке запроса. Для всех остальных методов HTTP необходимо использовать cURL, Fiddler, Postman или аналогичный инструмент тестирования HTTP, поддерживающий запросы POST.

Функции, не активируемые по протоколу HTTP

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

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

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

Вызовите следующую конечную точку администрирования, чтобы активировать функции, отличные от HTTP:

http://localhost:{port}/admin/functions/{function_name}

Чтобы передать тестовые данные в конечную точку администрирования функции, укажите данные в тексте запроса POST. Текст сообщения должен иметь следующий формат JSON:

{
    "input": "<trigger_input>"
}

Значение <trigger_input> содержит данные в формате, ожидаемом функцией. В следующем примере представлен запрос POST к функции QueueTriggerJS. В этом случае входные данные представляют собой строку, соответствующую сообщению, которое нужно найти в очереди.

curl --request POST -H "Content-Type:application/json" --data '{"input":"sample queue data"}' http://localhost:7071/admin/functions/QueueTrigger

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

Публикация в Azure

Azure Functions Core Tools поддерживает два типа развертывания:

Тип развертывания Команда Описание
Файлы проекта func azure functionapp publish Развертывает файлы проекта функции непосредственно в приложении-функции с помощью ZIP-развертывания.
Кластер Kubernetes func kubernetes deploy Развертывает приложение-функцию Linux в качестве настраиваемого контейнера Docker в кластере Kubernetes.

Перед публикацией

Важно!

Для публикации в Azure из Core Tools необходимо установить Azure CLI или Azure PowerShell в локальной среде.

Папка проекта может содержать файлы и каталоги для конкретного языка, которые не должны публиковаться. Такие исключения перечисляются в файле .funcignore в корневой папке проекта.

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

Сведения о том, как создать приложение-функцию из командной строки или окна терминала с помощью Azure CLI или Azure PowerShell, см. в статье Создание приложения-функции для выполнения без сервера.

Важно!

При создании приложения-функции на портале Azure по умолчанию используется версия 3.x среды выполнения Функций. Чтобы в приложении-функции использовалась среда выполнения версии 1.x, следуйте инструкциям, приведенным в разделе Создание приложений 1.x. Изменить версию среды выполнения для приложения-функции, в котором уже есть функции, невозможно.

Развертывание файлов проекта

Чтобы опубликовать локальный код в виде приложения-функции в Azure, используйте команду publish:

func azure functionapp publish <FunctionAppName>

К этому типу развертывания относятся следующие соображения:

  • При публикации перезаписываются существующие файлы в приложении-функции.

  • Используйте параметр --publish-local-settings для автоматического создания параметров приложения в приложении-функции на основе значений из файла local.settings.json.

  • Для скомпилированных проектов выполняется удаленная сборка. Это можно контролировать с помощью параметра --no-build.

  • Проект развертывается для запуска из пакета развертывания. Чтобы отключить этот рекомендуемый режим развертывания, используйте параметр --nozip.

  • Java использует Maven для публикации локального проекта в Azure. Вместо этого используйте для публикации в Azure следующую команду: mvn azure-functions:deploy. Ресурсы Azure создаются во время первоначального развертывания.

  • При попытке публикации в <FunctionAppName> возникает ошибка, если это приложение-функция не существует в вашей подписке.

Кластер Kubernetes

Функции также позволяют определить проект функций для запуска в контейнере Docker. С помощью параметра --docker для func init создайте файл Dockerfile для своего языка. Этот файл затем используется при создании контейнера для развертывания. Сведения о публикации пользовательского контейнера в Azure без Kubernetes см. в статье Создание функции в Linux с помощью пользовательского контейнера.

Инструменты Core Tools можно использовать для развертывания проекта в виде пользовательского образа контейнера в кластере Kubernetes.

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

func kubernetes deploy --name <DEPLOYMENT_NAME> --registry <REGISTRY_USERNAME> 

Дополнительные сведения см. в разделе Развертывание приложения-функции в Kubernetes.

Установка расширений

Если использовать пакеты расширений нельзя, вы можете с помощью Azure Functions Core Tools локально установить конкретные пакеты расширений, необходимые для вашего проекта.

Важно!

Явным образом устанавливать расширения в приложении-функции, использующем пакеты расширений, нельзя. Перед выполнением явной установки расширений нужно удалить раздел extensionBundle из файла host.json.

Ниже описаны некоторые причины, по которым может потребоваться установка расширений вручную:

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

При явной установке расширений файл проекта .NET с именем extensions.csproj добавляется в корневую папку проекта. Этот файл определяет набор пакетов NuGet, необходимых для ваших функций. Несмотря на то, что в этом файле можно работать со ссылками на пакеты NuGet, Core Tools позволяют устанавливать расширения, не прибегая к редактированию этого файла проекта C# вручную.

Существует несколько способов использования Core Tools для установки необходимых расширений в локальный проект.

Установка всех расширений

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

func extensions install

Эта команда считывает файл function.json для определения необходимых пакетов, а затем устанавливает их и перестраивает проект расширений (extensions.csproj). Затем добавляются все новые привязки в текущей версии, но существующие привязки не обновляются. Используйте параметр --force, чтобы обновить существующие привязки до последней версии при установке новых пакетов. Дополнительные сведения см. в разделе о команде func extensions install.

Если приложение-функция использует привязки или пакеты NuGet, которые не распознаются Core Tools, конкретное расширение нужно установить вручную.

Установка конкретного расширения

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

func extensions install --package Microsoft.Azure.WebJobs.Extensions.Storage --version 5.0.0

Эту команду можно использовать для установки любого совместимого пакета NuGet. Дополнительные сведения см. в описании команды func extensions install.

Мониторинг функций

Рекомендуемый способ наблюдения за выполнением этой функции — интеграция с Azure Application Insights. Вы также можете выполнять потоковую передачу журналов выполнения на локальный компьютер. Дополнительные сведения см. в статье Мониторинг Функций Azure.

Интеграция с Application Insights

Интеграция с Application Insights должна быть включена, когда вы создаете приложение-функцию в Azure. Если по какой-либо причине приложение-функция не подключено к экземпляру Application Insights, это легко исправить на портале Azure. Дополнительные сведения см. в разделе Включение интеграции с Application Insights.

Включение потоковой передачи журналов

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

Встроенная потоковая передача журналов

Команда func azure functionapp logstream позволяет получать журналы потоковой передачи конкретного приложения-функции, работающего в Azure, как показано в следующем примере.

func azure functionapp logstream <FunctionAppName>

Примечание

Встроенная потоковая передача журналов пока что не поддерживается в Core Tools для приложений-функций, выполняемых в Linux в рамках плана "Потребление". Чтобы просматривать журналы почти в реальном времени, для таких планов размещения необходимо использовать Live Metrics Stream.

Динамический поток метрик

Вы можете просмотреть журналы Live Metrics Stream для своего приложения-функции в новом окне браузера. Для этого включите параметр --browser, как показано в следующем примере:

func azure functionapp logstream <FunctionAppName> --browser

Для этого типа журналов потоковой передачи нужно включить для приложения функции интеграцию с Application Insights.

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

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