Руководство разработчика PowerShell для Функций Azure.Azure Functions PowerShell developer guide

Эта статья содержит сведения о том, как вы пишете функции Azure с помощью PowerShell.This article provides details about how you write Azure Functions using PowerShell.

Функция Azure PowerShell (функция) представляется в виде скрипта PowerShell, который выполняется при срабатывании.A PowerShell Azure function (function) is represented as a PowerShell script that executes when triggered. Каждый сценарий функции имеет связанный function.json файл, который определяет, как работает функция, например, как она запускается, а также ее входные и выходные параметры.Each function script has a related function.json file that defines how the function behaves, such as how it's triggered and its input and output parameters. Дополнительные сведения см. в статье о триггерах и привязке.To learn more, see the Triggers and binding article.

Как и другие типы функций, функции скриптов PowerShell принимают параметры, соответствующие именам всех входных привязок, определенных в function.json файле.Like other kinds of functions, PowerShell script functions take in parameters that match the names of all the input bindings defined in the function.json file. TriggerMetadataТакже передается параметр, содержащий дополнительные сведения о триггере, который запустил функцию.A TriggerMetadata parameter is also passed that contains additional information on the trigger that started the function.

В этой статье предполагается, что вы уже прочли руководство для разработчиков по Функциям Azure.This article assumes that you have already read the Azure Functions developer reference. Кроме того, для создания первой функции PowerShell необходимо завершить работу с кратким руководством по функциям PowerShell .You should have also completed the Functions quickstart for PowerShell to create your first PowerShell function.

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

Необходимая структура папок для проекта PowerShell выглядит следующим образом.The required folder structure for a PowerShell project looks like the following. Это значение по умолчанию можно изменить.This default can be changed. Дополнительные сведения см. в разделе о scriptFile ниже.For more information, see the scriptFile section below.

PSFunctionApp
 | - MyFirstFunction
 | | - run.ps1
 | | - function.json
 | - MySecondFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - myFirstHelperModule
 | | | - myFirstHelperModule.psd1
 | | | - myFirstHelperModule.psm1
 | | - mySecondHelperModule
 | | | - mySecondHelperModule.psd1
 | | | - mySecondHelperModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1
 | - profile.ps1
 | - extensions.csproj
 | - bin

В корне проекта есть общий host.json файл, который можно использовать для настройки приложения-функции.At the root of the project, there's a shared host.json file that can be used to configure the function app. У каждой функции есть папка с собственным файлом кода (PS1) и файл конфигурации привязки ( function.json ).Each function has a folder with its own code file (.ps1) and binding configuration file (function.json). Имя function.jsродительского каталога файла всегда является именем функции.The name of the function.json file's parent directory is always the name of your function.

Для определенных привязок требуется наличие extensions.csproj файла.Certain bindings require the presence of an extensions.csproj file. Расширения привязки, необходимые в версии 2. x и более поздних версиях среды выполнения функций, определяются в extensions.csproj файле с фактическими файлами библиотеки в bin папке.Binding extensions, required in version 2.x and later versions of the Functions runtime, are defined in the extensions.csproj file, with the actual library files in the bin folder. При локальной разработке необходимо зарегистрировать расширения привязки.When developing locally, you must register binding extensions. При разработке функций на портале Azure эта регистрация выполняется автоматически.When developing functions in the Azure portal, this registration is done for you.

В приложениях-функциях PowerShell при необходимости можно использовать, profile.ps1 который запускается при запуске приложения-функции (в противном случае — как холодный запуск).In PowerShell Function Apps, you may optionally have a profile.ps1 which runs when a function app starts to run (otherwise know as a cold start. Дополнительные сведения см. в разделе профиль PowerShell.For more information, see PowerShell profile.

Определение скрипта PowerShell как функцииDefining a PowerShell script as a function

По умолчанию среда выполнения Функций ищет функцию в файле run.ps1, где run.ps1 использует тот же родительский каталог, что и соответствующий файл function.json.By default, the Functions runtime looks for your function in run.ps1, where run.ps1 shares the same parent directory as its corresponding function.json.

При выполнении скрипту передается ряд аргументов.Your script is passed a number of arguments on execution. Чтобы обрабатывал эти параметры, добавьте param блок в начало скрипта, как показано в следующем примере:To handle these parameters, add a param block to the top of your script as in the following example:

# $TriggerMetadata is optional here. If you don't need it, you can safely remove it from the param block
param($MyFirstInputBinding, $MySecondInputBinding, $TriggerMetadata)

Тригжерметадата, параметрTriggerMetadata parameter

TriggerMetadataПараметр используется для предоставления дополнительных сведений о триггере.The TriggerMetadata parameter is used to supply additional information about the trigger. Дополнительные метаданные отличаются от привязки к привязке, но все они содержат sys свойство, которое содержит следующие данные:The additional metadata varies from binding to binding but they all contain a sys property that contains the following data:

$TriggerMetadata.sys
СвойствоProperty ОписаниеDescription ТипType
UtcNowUtcNow Когда, в формате UTC, была активирована функцияWhen, in UTC, the function was triggered Дата и времяDateTime
MethodNameMethodName Имя функции, которая была активированаThe name of the Function that was triggered строкаstring
рандгуидRandGuid уникальный идентификатор GUID для этого выполнения функцииa unique guid to this execution of the function строкаstring

Каждый тип триггера имеет другой набор метаданных.Every trigger type has a different set of metadata. Например, $TriggerMetadata для QueueTrigger содержит InsertionTime ,, и, помимо прочего, Id DequeueCount .For example, the $TriggerMetadata for QueueTrigger contains the InsertionTime, Id, DequeueCount, among other things. Дополнительные сведения о метаданных триггера очереди см. в официальной документации по триггерам очереди.For more information on the queue trigger's metadata, go to the official documentation for queue triggers. Ознакомьтесь с документацией по триггерам , с которыми вы работаете, чтобы узнать, что входит в метаданные триггера.Check the documentation on the triggers you're working with to see what comes inside the trigger metadata.

ПривязкиBindings

В PowerShell привязки настраиваются и определяются в function.jsфункции.In PowerShell, bindings are configured and defined in a function's function.json. Функции взаимодействуют с привязками несколькими способами.Functions interact with bindings a number of ways.

Чтение триггера и входных данныхReading trigger and input data

Привязки триггера и ввода считываются как параметры, передаваемые в функцию.Trigger and input bindings are read as parameters passed to your function. Для входных привязок direction задано значение in в function.json.Input bindings have a direction set to in in function.json. nameСвойство, определенное в function.json , является именем параметра в param блоке.The name property defined in function.json is the name of the parameter, in the param block. Так как PowerShell использует именованные параметры для привязки, порядок параметров не имеет значения.Since PowerShell uses named parameters for binding, the order of the parameters doesn't matter. Однако рекомендуется следовать порядку привязок, определенных в function.json .However, it's a best practice to follow the order of the bindings defined in the function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

запись выходных данных;Writing output data

В функциях выходная привязка имеет значение, заданное direction out в function.json.In Functions, an output binding has a direction set to out in the function.json. Запись в выходную привязку можно выполнить с помощью Push-OutputBinding командлета, который доступен для среды выполнения функций.You can write to an output binding by using the Push-OutputBinding cmdlet, which is available to the Functions runtime. Во всех случаях name свойство привязки, определенное в, function.json соответствует Name параметру Push-OutputBinding командлета.In all cases, the name property of the binding as defined in function.json corresponds to the Name parameter of the Push-OutputBinding cmdlet.

Ниже показано, как вызвать Push-OutputBinding в скрипте функции:The following shows how to call Push-OutputBinding in your function script:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

Можно также передать значение для конкретной привязки через конвейер.You can also pass in a value for a specific binding through the pipeline.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding ведет себя по-разному в зависимости от значения, указанного для -Name :Push-OutputBinding behaves differently based on the value specified for -Name:

  • Если указанное имя не может быть разрешено в допустимую выходную привязку, возникает ошибка.When the specified name cannot be resolved to a valid output binding, then an error is thrown.

  • Если выходная привязка принимает коллекцию значений, Push-OutputBinding для отправки нескольких значений можно многократно вызывать несколько раз.When the output binding accepts a collection of values, you can call Push-OutputBinding repeatedly to push multiple values.

  • Если выходная привязка принимает только одноэлементное значение, вызов Push-OutputBinding второго раза вызывает ошибку.When the output binding only accepts a singleton value, calling Push-OutputBinding a second time raises an error.

Синтаксис Push-OutputBindingPush-OutputBinding syntax

Ниже приведены допустимые параметры для вызова Push-OutputBinding .The following are valid parameters for calling Push-OutputBinding:

ИмяName ТипType ПоложениеPosition ОписаниеDescription
-Name СтрокаString 11 Имя выходной привязки, которую необходимо задать.The name of the output binding you want to set.
-Value ОбъектObject 22 Значение выходной привязки, которое необходимо задать, которое принимается из Бивалуе конвейера.The value of the output binding you want to set, which is accepted from the pipeline ByValue.
-Clobber Параметр-переключательSwitchParameter именованнаяNamed Используемых При указании параметра устанавливает значение для заданной выходной привязки.(Optional) When specified, forces the value to be set for a specified output binding.

Также поддерживаются следующие общие параметры:The following common parameters are also supported:

  • Verbose
  • Debug
  • ErrorAction
  • ErrorVariable
  • WarningAction
  • WarningVariable
  • OutBuffer
  • PipelineVariable
  • OutVariable

Дополнительные сведения см. в разделе About общиепараметры.For more information, see About CommonParameters.

Push-OutputBinding пример: HTTP-ответыPush-OutputBinding example: HTTP responses

Триггер HTTP возвращает ответ, используя выходную привязку с именем response .An HTTP trigger returns a response using an output binding named response. В следующем примере выходная привязка response имеет значение "output #1":In the following example, the output binding of response has the value of "output #1":

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #1"
})

Поскольку выходным данным является HTTP, которая принимает только одноэлементное значение, возникает ошибка, когда Push-OutputBinding вызывается второй раз.Because the output is to HTTP, which accepts a singleton value only, an error is thrown when Push-OutputBinding is called a second time.

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #2"
})

Для выходов, которые принимают только одноэлементные значения, можно использовать -Clobber параметр для переопределения старого значения вместо того, чтобы пытаться добавить его в коллекцию.For outputs that only accept singleton values, you can use the -Clobber parameter to override the old value instead of trying to add to a collection. В следующем примере предполагается, что вы уже добавили значение.The following example assumes that you have already added a value. Используя -Clobber , ответ из следующего примера переопределяет существующее значение для возврата значения "output #3":By using -Clobber, the response from the following example overrides the existing value to return a value of "output #3":

PS >Push-OutputBinding -Name response -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "output #3"
}) -Clobber

Push-OutputBinding пример: Выходная привязка очередиPush-OutputBinding example: Queue output binding

Push-OutputBinding используется для отправки данных в выходные привязки, такие как выходная привязка хранилища очередей Azure.Push-OutputBinding is used to send data to output bindings, such as an Azure Queue storage output binding. В следующем примере сообщение, записанное в очередь, имеет значение "Output #1":In the following example, the message written to the queue has a value of "output #1":

PS >Push-OutputBinding -Name outQueue -Value "output #1"

Выходная привязка для очереди хранилища принимает несколько выходных значений.The output binding for a Storage queue accepts multiple output values. В этом случае вызов следующего примера после первой записи в очередь списка с двумя элементами: "Output #1" и "Output #2".In this case, calling the following example after the first writes to the queue a list with two items: "output #1" and "output #2".

PS >Push-OutputBinding -Name outQueue -Value "output #2"

В следующем примере, когда вызывается после двух предыдущих, в выходную коллекцию добавляется еще два значения:The following example, when called after the previous two, adds two more values to the output collection:

PS >Push-OutputBinding -Name outQueue -Value @("output #3", "output #4")

При запись в очередь сообщение содержит следующие четыре значения: "Output #1", "Output #2", "Output #3" и "Output #4".When written to the queue, the message contains these four values: "output #1", "output #2", "output #3", and "output #4".

Командлет Get-OutputBindingGet-OutputBinding cmdlet

Get-OutputBindingС помощью командлета можно получить значения, заданные в данный момент для выходных привязок.You can use the Get-OutputBinding cmdlet to retrieve the values currently set for your output bindings. Этот командлет извлекает хэш-таблицу, содержащую имена выходных привязок с соответствующими значениями.This cmdlet retrieves a hashtable that contains the names of the output bindings with their respective values.

Ниже приведен пример использования Get-OutputBinding для возврата текущих значений привязки.The following is an example of using Get-OutputBinding to return current binding values:

Get-OutputBinding
Name                           Value
----                           -----
MyQueue                        myData
MyOtherQueue                   myData

Get-OutputBinding также содержит параметр с именем -Name , который можно использовать для фильтрации возвращаемой привязки, как показано в следующем примере:Get-OutputBinding also contains a parameter called -Name, which can be used to filter the returned binding, as in the following example:

Get-OutputBinding -Name MyQ*
Name                           Value
----                           -----
MyQueue                        myData

Подстановочные знаки (*) поддерживаются в Get-OutputBinding .Wildcards (*) are supported in Get-OutputBinding.

Ведение журналаLogging

Ведение журнала в функциях PowerShell работает как обычное ведение журнала PowerShell.Logging in PowerShell functions works like regular PowerShell logging. Командлеты ведения журнала можно использовать для записи в каждый выходной поток.You can use the logging cmdlets to write to each output stream. Каждый командлет сопоставляется с уровнем ведения журнала, который используется функциями.Each cmdlet maps to a log level used by Functions.

Уровень ведения журнала функцийFunctions logging level Командлет ведения журналаLogging cmdlet
ОшибкаError Write-Error
ПредупреждениеWarning Write-Warning
ИнформацияInformation Write-Information
Write-Host
Write-Output
ИнформацияInformation Выполняет запись в журнал на уровне информации .Writes to Information level logging.
ОтладкаDebug Write-Debug
ТрассировкаTrace Write-Progress
Write-Verbose

Помимо этих командлетов, все данные, записанные в конвейер, перенаправляются на Information уровень ведения журнала и отображаются с форматированием PowerShell по умолчанию.In addition to these cmdlets, anything written to the pipeline is redirected to the Information log level and displayed with the default PowerShell formatting.

Важно!

Использование Write-Verbose Write-Debug командлетов или не является достаточным для просмотра подробных сведений и ведения журнала на уровне отладки.Using the Write-Verbose or Write-Debug cmdlets is not enough to see verbose and debug level logging. Кроме того, необходимо настроить пороговое значение уровня ведения журнала, которое объявляет, какой уровень журналов вы в действительности интересуют.You must also configure the log level threshold, which declares what level of logs you actually care about. Дополнительные сведения см. в статье Настройка уровня ведения журнала приложения функции.To learn more, see Configure the function app log level.

Настройка уровня ведения журнала приложения функцииConfigure the function app log level

Функции Azure позволяют определить пороговый уровень, чтобы упростить управление способом записи функций в журналы.Azure Functions lets you define the threshold level to make it easy to control the way Functions writes to the logs. Чтобы задать пороговое значение для всех трассировок, записываемых на консоль, используйте logging.logLevel.default свойство в [ host.json файле] [host.jsпо ссылке].To set the threshold for all traces written to the console, use the logging.logLevel.default property in the host.json file. Этот параметр применяется ко всем функциям в приложении-функции.This setting applies to all functions in your function app.

В следующем примере устанавливается пороговое значение для включения подробного ведения журнала для всех функций, но устанавливается пороговое значение включения ведения журнала отладки для функции с именем MyFunction :The following example sets the threshold to enable verbose logging for all functions, but sets the threshold to enable debug logging for a function named MyFunction:

{
    "logging": {
        "logLevel": {
            "Function.MyFunction": "Debug",
            "default": "Trace"
        }
    }
}  

Дополнительные сведения см. в [справочной статье о host.json].For more information, see host.json reference.

Просмотр журналовViewing the logs

Если приложение-функция выполняется в Azure, можно использовать Application Insights для мониторинга.If your Function App is running in Azure, you can use Application Insights to monitor it. Дополнительные сведения о просмотре журналов функций и обращении к ним см. в статье мониторинг Функций Azure.Read monitoring Azure Functions to learn more about viewing and querying function logs.

Если вы используете приложение-функция локально для разработки, ведет журнал по умолчанию в файловой системе.If you're running your Function App locally for development, logs default to the file system. Чтобы просмотреть журналы в консоли, задайте AZURE_FUNCTIONS_ENVIRONMENT для переменной среды значение Development перед запуском приложение-функция.To see the logs in the console, set the AZURE_FUNCTIONS_ENVIRONMENT environment variable to Development before starting the Function App.

Типы триггеров и привязокTriggers and bindings types

Существует ряд триггеров и привязок, которые можно использовать с приложением-функцией.There are a number of triggers and bindings available to you to use with your function app. Полный список триггеров и привязок можно найти здесь.The full list of triggers and bindings can be found here.

Все триггеры и привязки представлены в коде как несколько реальных типов данных:All triggers and bindings are represented in code as a few real data types:

  • Хэш-таблицыHashtable
  • строкаstring
  • byte[]byte[]
  • INTint
  • doubledouble
  • хттпрекуестконтекстHttpRequestContext
  • хттпреспонсеконтекстHttpResponseContext

Первые пять типов в этом списке являются стандартными типами .NET.The first five types in this list are standard .NET types. Последние два используются только триггером HttpTrigger.The last two are used only by the HttpTrigger trigger.

Каждый параметр привязки в функциях должен иметь один из этих типов.Each binding parameter in your functions must be one of these types.

Триггеры и привязки HTTPHTTP triggers and bindings

Триггеры HTTP и webhook, а также привязки вывода HTTP используют объекты запроса и ответа для обмена сообщениями HTTP.HTTP and webhook triggers and HTTP output bindings use request and response objects to represent the HTTP messaging.

Объект запросаRequest object

Объект запроса, переданный в скрипт, имеет тип HttpRequestContext , который имеет следующие свойства:The request object that's passed into the script is of the type HttpRequestContext, which has the following properties:

СвойствоProperty ОписаниеDescription ТипType
Body Объект, содержащий текст запроса.An object that contains the body of the request. Body сериализуется в лучший тип на основе данных.Body is serialized into the best type based on the data. Например, если данные являются JSON, они передаются в виде хэш-таблицы.For example, if the data is JSON, it's passed in as a hashtable. Если данные являются строкой, они передаются в виде строки.If the data is a string, it's passed in as a string. objectobject
Headers Словарь, содержащий заголовки запроса.A dictionary that contains the request headers. Строка<словаря, строка>*Dictionary<string,string>*
Method Метод HTTP, используемый для запроса.The HTTP method of the request. строкаstring
Params Объект, содержащий параметры маршрутизации запроса.An object that contains the routing parameters of the request. Строка<словаря, строка>*Dictionary<string,string>*
Query Объект, содержащий параметры запроса.An object that contains the query parameters. Строка<словаря, строка>*Dictionary<string,string>*
Url URL-адрес запроса.The URL of the request. строкаstring

* Во всех Dictionary<string,string> ключах регистр не учитывается.* All Dictionary<string,string> keys are case-insensitive.

Объект ответаResponse object

Объект ответа, который необходимо отправить обратно, имеет тип HttpResponseContext , который имеет следующие свойства:The response object that you should send back is of the type HttpResponseContext, which has the following properties:

СвойствоProperty ОписаниеDescription ТипType
Body Объект, содержащий текст ответа.An object that contains the body of the response. objectobject
ContentType Короткий рукой для установки типа содержимого для ответа.A short hand for setting the content type for the response. строкаstring
Headers Объект, содержащий заголовок ответа.An object that contains the response headers. Словарь или хэш-таблицаDictionary or Hashtable
StatusCode Код состояния HTTP ответа.The HTTP status code of the response. строка или целое числоstring or int

Доступ к запросу и ответуAccessing the request and response

При работе с триггерами HTTP доступ к HTTP-запросу можно получить так же, как и с любой другой входной привязкой.When you work with HTTP triggers, you can access the HTTP request the same way you would with any other input binding. Он находится в param блоке.It's in the param block.

Используйте HttpResponseContext объект для возврата ответа, как показано ниже:Use an HttpResponseContext object to return a response, as shown in the following:

function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "anonymous"
    },
    {
      "type": "http",
      "direction": "out"
    }
  ]
}

run.ps1

param($req, $TriggerMetadata)

$name = $req.Query.Name

Push-OutputBinding -Name res -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "Hello $name!"
})

Результат вызова этой функции будет следующим:The result of invoking this function would be:

PS > irm http://localhost:5001?Name=Functions
Hello Functions!

Приведение типов для триггеров и привязокType-casting for triggers and bindings

Для некоторых привязок, таких как привязка больших двоичных объектов, можно указать тип параметра.For certain bindings like the blob binding, you're able to specify the type of the parameter.

Например, чтобы данные из хранилища BLOB-объектов передавались в виде строки, добавьте следующий тип к моему param блоку:For example, to have data from Blob storage supplied as a string, add the following type cast to my param block:

param([string] $myBlob)

Профиль PowerShellPowerShell profile

В PowerShell есть понятие профиля PowerShell.In PowerShell, there's the concept of a PowerShell profile. Если вы не знакомы с профилями PowerShell, см. раздел About Profiles.If you're not familiar with PowerShell profiles, see About profiles.

В функциях PowerShell скрипт профиля выполняется один раз для каждого экземпляра рабочего процесса PowerShell в приложении при первом развертывании и после его бездействия (холодный запуск.In PowerShell Functions, the profile script is executed once per PowerShell worker instance in the app when first deployed and after being idled (cold start. Если параметр Concurrency включен с помощью значения псворкеринпрокконкурренциуппербаунд , скрипт профиля выполняется для каждого создаваемого пространства выполнения.When concurrency is enabled by setting the PSWorkerInProcConcurrencyUpperBound value, the profile script is run for each runspace created.

При создании приложения-функции с помощью средств, таких как Visual Studio Code и Azure Functions Core Tools, создается значение по умолчанию profile.ps1 .When you create a function app using tools, such as Visual Studio Code and Azure Functions Core Tools, a default profile.ps1 is created for you. Профиль по умолчанию хранится в репозитории основных средств , который содержит:The default profile is maintained on the Core Tools GitHub repository and contains:

  • Автоматическая проверка подлинности MSI в Azure.Automatic MSI authentication to Azure.
  • Возможность включения Azure PowerShell AzureRM псевдонимов PowerShell при желании.The ability to turn on the Azure PowerShell AzureRM PowerShell aliases if you would like.

Версии PowerShellPowerShell versions

В следующей таблице приведены версии PowerShell, доступные для каждой основной версии среды выполнения функций, и требуемая версия .NET.The following table shows the PowerShell versions available to each major version of the Functions runtime, and the .NET version required:

Версия службы "Функции"Functions version Версия PowerShellPowerShell version Версия .NET.NET version
3. x (рекомендуется)3.x (recommended) PowerShell 7 (рекомендуется)PowerShell 7 (recommended)
PowerShell Core 6PowerShell Core 6
.NET Core 3.1.NET Core 3.1
.NET Core 2.1.NET Core 2.1
2.x2.x PowerShell Core 6PowerShell Core 6 .NET Core 2.2.NET Core 2.2

Текущую версию можно просмотреть, выполнив печать $PSVersionTable из любой функции.You can see the current version by printing $PSVersionTable from any function.

Локальный запуск в определенной версииRunning local on a specific version

При локальном запуске среда выполнения функций Azure по умолчанию использует PowerShell Core 6.When running locally the Azure Functions runtime defaults to using PowerShell Core 6. Чтобы вместо этого использовать PowerShell 7 при локальном запуске, необходимо добавить параметр "FUNCTIONS_WORKER_RUNTIME_VERSION" : "~7" в Values массив в файле local.setting.jsв корневом каталоге проекта.To instead use PowerShell 7 when running locally, you need to add the setting "FUNCTIONS_WORKER_RUNTIME_VERSION" : "~7" to the Values array in the local.setting.json file in the project root. При локальном запуске в PowerShell 7 local.settings.jsв файле выглядит, как в следующем примере:When running locally on PowerShell 7, your local.settings.json file looks like the following example:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "FUNCTIONS_WORKER_RUNTIME": "powershell",
    "FUNCTIONS_WORKER_RUNTIME_VERSION" : "~7"
  }
}

Изменение версии PowerShellChanging the PowerShell version

Приложение функции должно работать на версии 3. x, чтобы иметь возможность выполнить обновление с PowerShell Core 6 до PowerShell 7.Your function app must be running on version 3.x to be able to upgrade from PowerShell Core 6 to PowerShell 7. Чтобы узнать, как это сделать, см. статью Просмотр и обновление текущей версии среды выполнения.To learn how to do this, see View and update the current runtime version.

Чтобы изменить версию PowerShell, используемую приложением функции, выполните следующие действия.Use the following steps to change the PowerShell version used by your function app. Это можно сделать либо в портал Azure, либо с помощью PowerShell.You can do this either in the Azure portal or by using PowerShell.

  1. На портале Azure перейдите к приложению-функции.In the Azure portal, browse to your function app.

  2. В разделе Параметрывыберите Конфигурация.Under Settings, choose Configuration. На вкладке Общие параметры выберите версию PowerShell.In the General settings tab, locate the PowerShell version.

    Выберите версию PowerShell, используемую приложением функции

  3. Выберите нужную версию PowerShell Core и нажмите кнопку сохранить.Choose your desired PowerShell Core version and select Save. При предупреждении о ожидающем перезапуске выберите Continue (продолжить).When warned about the pending restart choose Continue. Приложение функции перезапускается в выбранной версии PowerShell.The function app restarts on the chosen PowerShell version.

После внесения изменений в конфигурацию приложение-функция перезапускается.The function app restarts after the change is made to the configuration.

Управление зависимостямиDependency management

Функции позволяют использовать коллекцию PowerShell для управления зависимостями.Functions lets you leverage PowerShell gallery for managing dependencies. При включенном управлении зависимостями файл requirements.psd1 используется для автоматической загрузки необходимых модулей.With dependency management enabled, the requirements.psd1 file is used to automatically download required modules. Это поведение можно включить, задав managedDependency для свойства значение true в корневом каталоге host.jsдля файла, как показано в следующем примере:You enable this behavior by setting the managedDependency property to true in the root of the host.json file, as in the following example:

{
  "managedDependency": {
          "enabled": true
       }
}

При создании нового проекта функций PowerShell управление зависимостями включается по умолчанию с включенным Az модулем Azure.When you create a new PowerShell functions project, dependency management is enabled by default, with the Azure Az module included. Максимальное число модулей, поддерживаемое в настоящее время, равно 10.The maximum number of modules currently supported is 10. Поддерживаемый синтаксис — MajorNumber .* или точная версия модуля, как показано в следующем requirements.psd1 примере:The supported syntax is MajorNumber.* or exact module version as shown in the following requirements.psd1 example:

@{
    Az = '1.*'
    SqlServer = '21.1.18147'
}

При обновлении файла requirements.psd1 обновленные модули устанавливаются после перезагрузки.When you update the requirements.psd1 file, updated modules are installed after a restart.

Примечание

Управляемым зависимостям требуется доступ к www.powershellgallery.com для скачивания модулей.Managed dependencies requires access to www.powershellgallery.com to download modules. При локальном запуске убедитесь, что среда выполнения может получить доступ к этому URL-адресу, добавив необходимые правила брандмауэра.When running locally, make sure that the runtime can access this URL by adding any required firewall rules.

Примечание

В настоящее время управляемые зависимости не поддерживают модули, требующие от пользователя принятия лицензии, либо путем принятия лицензии в интерактивном режиме, либо путем предоставления -AcceptLicense коммутатора при вызове Install-Module .Managed dependencies currently don't support modules that require the user to accept a license, either by accepting the license interactively, or by providing -AcceptLicense switch when invoking Install-Module.

Следующие параметры приложения можно использовать для изменения способа загрузки и установки управляемых зависимостей.The following application settings can be used to change how the managed dependencies are downloaded and installed. Обновление приложения начинается в пределах MDMaxBackgroundUpgradePeriod , а процесс обновления завершается примерно в MDNewSnapshotCheckPeriod .Your app upgrade starts within MDMaxBackgroundUpgradePeriod, and the upgrade process completes within approximately the MDNewSnapshotCheckPeriod.

Параметр приложение-функцияFunction App setting Значение по умолчаниюDefault value ОписаниеDescription
MDMaxBackgroundUpgradePeriod 7.00:00:00 (7 дней)7.00:00:00 (7 days) Каждый рабочий процесс PowerShell инициирует проверку наличия обновлений модулей на коллекция PowerShell при запуске процесса и каждый MDMaxBackgroundUpgradePeriod после этого.Each PowerShell worker process initiates checking for module upgrades on the PowerShell Gallery on process start and every MDMaxBackgroundUpgradePeriod after that. Если в коллекция PowerShell доступна новая версия модуля, она устанавливается в файловую систему и становится доступной для рабочих ролей PowerShell.When a new module version is available in the PowerShell Gallery, it's installed to the file system and made available to PowerShell workers. Уменьшение этого значения позволяет приложению-функции получать более новые версии модулей быстрее, но также увеличивает использование ресурсов приложения (сетевой ввод-вывод, ЦП, хранилище).Decreasing this value lets your function app get newer module versions sooner, but it also increases the app resource usage (network I/O, CPU, storage). Увеличение этого значения приводит к уменьшению использования ресурсов приложением, но может также задержать доставку новых версий модуля в приложение.Increasing this value decreases the app's resource usage, but it may also delay delivering new module versions to your app.
MDNewSnapshotCheckPeriod 01:00:00 (1 час)01:00:00 (1 hour) После установки новых версий модулей в файловой системе необходимо перезапустить каждый рабочий процесс PowerShell.After new module versions are installed to the file system, every PowerShell worker process must be restarted. Перезапуск рабочих ролей PowerShell влияет на доступность приложения, так как он может прерывать текущее выполнение функции.Restarting PowerShell workers affects your app availability as it can interrupt current function execution. До тех пор пока все рабочие процессы PowerShell не будут перезапущены, вызовы функций могут использовать либо старые, либо новые версии модулей.Until all PowerShell worker processes are restarted, function invocations may use either the old or the new module versions. Перезапуск всех рабочих ролей PowerShell завершен в MDNewSnapshotCheckPeriod .Restarting all PowerShell workers complete within MDNewSnapshotCheckPeriod. Увеличение этого значения снижает частоту прерываний, но также может увеличить период времени, в течение которого вызовы функций используют старую или новую версию модуля недетерминированно.Increasing this value decreases the frequency of interruptions, but may also increase the period of time when function invocations use either the old or the new module versions non-deterministically.
MDMinBackgroundUpgradePeriod 1.00:00:00 (1 день)1.00:00:00 (1 day) Чтобы избежать чрезмерного обновления модулей при частых перезапусках рабочих ролей, проверка обновления модулей не выполняется, когда любой рабочий процесс уже инициировал эту проверку в последней MDMinBackgroundUpgradePeriod .To avoid excessive module upgrades on frequent Worker restarts, checking for module upgrades isn't performed when any worker has already initiated that check in the last MDMinBackgroundUpgradePeriod.

Использование собственных пользовательских модулей немного отличается от того, как это можно сделать обычным образом.Leveraging your own custom modules is a little different than how you would do it normally.

На локальном компьютере модуль устанавливается в одну из глобально доступных папок в $env:PSModulePath .On your local computer, the module gets installed in one of the globally available folders in your $env:PSModulePath. При работе в Azure у вас нет доступа к модулям, установленным на вашем компьютере.When running in Azure, you don't have access to the modules installed on your machine. Это означает, что объект $env:PSModulePath для приложения-функции PowerShell отличается от $env:PSModulePath в регулярном скрипте PowerShell.This means that the $env:PSModulePath for a PowerShell function app differs from $env:PSModulePath in a regular PowerShell script.

В функциях PSModulePath содержит два пути:In Functions, PSModulePath contains two paths:

  • ModulesПапка, которая находится в корне приложения-функции.A Modules folder that exists at the root of your function app.
  • Путь к Modules папке, управляемой рабочим работником языка PowerShell.A path to a Modules folder that is controlled by the PowerShell language worker.

Папка уровня приложения-функции ModulesFunction app-level Modules folder

Чтобы использовать пользовательские модули, можно разместить модули, от которых зависят функции, в Modules папке.To use custom modules, you can place modules on which your functions depend in a Modules folder. Из этой папки модули автоматически становятся доступными для среды выполнения функций.From this folder, modules are automatically available to the functions runtime. Все функции в приложении функции могут использовать эти модули.Any function in the function app can use these modules.

Примечание

Модули, указанные в файле requirements.psd1, автоматически загружаются и включаются в путь, поэтому их не нужно включать в папку Modules.Modules specified in the requirements.psd1 file are automatically downloaded and included in the path so you don't need to include them in the modules folder. Они хранятся локально в $env:LOCALAPPDATA/AzureFunctions папке и в /data/ManagedDependencies папке при запуске в облаке.These are stored locally in the $env:LOCALAPPDATA/AzureFunctions folder and in the /data/ManagedDependencies folder when run in the cloud.

Чтобы воспользоваться функцией пользовательского модуля, создайте Modules папку в корне приложения-функции.To take advantage of the custom module feature, create a Modules folder in the root of your function app. Скопируйте модули, которые вы хотите использовать в функциях, в это расположение.Copy the modules you want to use in your functions to this location.

mkdir ./Modules
Copy-Item -Path /mymodules/mycustommodule -Destination ./Modules -Recurse

В Modules папке приложение-функция должно иметь следующую структуру папок:With a Modules folder, your function app should have the following folder structure:

PSFunctionApp
 | - MyFunction
 | | - run.ps1
 | | - function.json
 | - Modules
 | | - MyCustomModule
 | | - MyOtherCustomModule
 | | - MySpecialModule.psm1
 | - local.settings.json
 | - host.json
 | - requirements.psd1

При запуске приложения-функции языковой рабочий процесс PowerShell добавляет эту папку в, Modules $env:PSModulePath чтобы вы могли полагаться на автозагрузку модуля точно так же, как в обычном сценарии PowerShell.When you start your function app, the PowerShell language worker adds this Modules folder to the $env:PSModulePath so that you can rely on module autoloading just as you would in a regular PowerShell script.

Папка уровня рабочей роли языка ModulesLanguage worker level Modules folder

Рабочие роли языка PowerShell обычно используют несколько модулей.Several modules are commonly used by the PowerShell language worker. Эти модули определяются в последней должности PSModulePath .These modules are defined in the last position of PSModulePath.

Текущий список модулей выглядит следующим образом:The current list of modules is as follows:

  • Microsoft. PowerShell. Archive: модуль, используемый для работы с архивами, например .zip , .nupkg и другими.Microsoft.PowerShell.Archive: module used for working with archives, like .zip, .nupkg, and others.
  • Среаджоб: реализация API-интерфейсов задания PowerShell на основе потока.ThreadJob: A thread-based implementation of the PowerShell job APIs.

По умолчанию функции используют самые последние версии этих модулей.By default, Functions uses the most recent version of these modules. Чтобы использовать конкретную версию модуля, вставьте эту конкретную версию в Modules папку приложения-функции.To use a specific module version, put that specific version in the Modules folder of your function app.

Переменные средыEnvironment variables

В Функциях параметры приложения, такие как строки подключения службы, доступны в виде переменных среды во время выполнения.In Functions, app settings, such as service connection strings, are exposed as environment variables during execution. Доступ к этим параметрам можно получить с помощью $env:NAME_OF_ENV_VAR , как показано в следующем примере:You can access these settings using $env:NAME_OF_ENV_VAR, as shown in the following example:

param($myTimer)

Write-Host "PowerShell timer trigger function ran! $(Get-Date)"
Write-Host $env:AzureWebJobsStorage
Write-Host $env:WEBSITE_SITE_NAME

Существует несколько способов для добавления, обновления и удаления параметров приложения-функции.There are several ways that you can add, update, and delete function app settings:

При локальном запуске приложения параметры считываются из файла проекта local.settings.json.When running locally, app settings are read from the local.settings.json project file.

ПараллелизмConcurrency

По умолчанию среда выполнения PowerShell для функций может обрабатывать только один вызов функции за раз.By default, the Functions PowerShell runtime can only process one invocation of a function at a time. Однако этот уровень параллелизма может быть недостаточно в следующих ситуациях:However, this concurrency level might not be sufficient in the following situations:

  • При одновременной обработке большого количества вызовов одновременно.When you're trying to handle a large number of invocations at the same time.
  • При наличии функций, которые вызывают другие функции в одном и том же приложении функции.When you have functions that invoke other functions inside the same function app.

Существует несколько моделей параллелизма, которые можно исследовать в зависимости от типа рабочей нагрузки.There are a few concurrency models that you could explore depending on the type of workload:

  • Увеличить FUNCTIONS_WORKER_PROCESS_COUNT .Increase FUNCTIONS_WORKER_PROCESS_COUNT. Это позволяет обрабатывать вызовы функций в нескольких процессах в одном экземпляре, что приводит к определенным издержкам ЦП и памяти.This allows handling function invocations in multiple processes within the same instance, which introduces certain CPU and memory overhead. Как правило, функции, связанные с вводом-выводом, не повлияют на эту нагрузку.In general, I/O-bound functions will not suffer from this overhead. Для функций, зависящих от процессора, влияние может быть значительным.For CPU-bound functions, the impact may be significant.

  • Увеличьте PSWorkerInProcConcurrencyUpperBound значение параметра приложения.Increase the PSWorkerInProcConcurrencyUpperBound app setting value. Это позволяет создавать несколько пространств выполнения в рамках одного процесса, что значительно сокращает нагрузку на ЦП и память.This allows creating multiple runspaces within the same process, which significantly reduces CPU and memory overhead.

Эти переменные среды задаются в параметрах приложения для приложения функции.You set these environment variables in the app settings of your function app.

В зависимости от варианта использования Устойчивые функции может значительно повысить масштабируемость.Depending on your use case, Durable Functions may significantly improve scalability. Дополнительные сведения см. в разделе шаблоны приложений устойчивые функции.To learn more, see Durable Functions application patterns.

Примечание

Вы можете получить сообщение "запросы помещаются в очередь из-за отсутствия доступных пространств выполнения". Обратите внимание, что это не ошибка.You might get "requests are being queued due to no available runspaces" warnings, please note that this is not an error. Сообщение говорит о том, что запросы помещаются в очередь и будут обработаны после завершения предыдущих запросов.The message is telling you that requests are being queued and they will be handled when the previous requests are completed.

Рекомендации по использованию параллелизмаConsiderations for using concurrency

По умолчанию PowerShell является отдельным потоковым языком сценариев.PowerShell is a single threaded scripting language by default. Однако параллелизм можно добавить с помощью нескольких пространств выполнения PowerShell в одном процессе.However, concurrency can be added by using multiple PowerShell runspaces in the same process. Объем созданных пространств выполнения будет соответствовать PSWorkerInProcConcurrencyUpperBound параметру приложения.The amount of runspaces created will match the PSWorkerInProcConcurrencyUpperBound application setting. На пропускную способность влияет объем ресурсов ЦП и памяти, доступный в выбранном плане.The throughput will be impacted by the amount of CPU and memory available in the selected plan.

Azure PowerShell использует некоторые контексты и состояния уровня процесса , чтобы помочь сэкономить от чрезмерного ввода.Azure PowerShell uses some process-level contexts and state to help save you from excess typing. Однако при включении параллелизма в приложении функции и вызове действий, изменяющих состояние, могут возникнуть состояния гонки.However, if you turn on concurrency in your function app and invoke actions that change state, you could end up with race conditions. Эти состояния гонки трудно отлаживать, поскольку один вызов зависит от определенного состояния, а другой вызов изменил состояние.These race conditions are difficult to debug because one invocation relies on a certain state and the other invocation changed the state.

Во время параллелизма Azure PowerShell, так как некоторые операции могут занимать значительное количество времени.There's immense value in concurrency with Azure PowerShell, since some operations can take a considerable amount of time. Однако следует соблюдать осторожность.However, you must proceed with caution. Если вы считаете, что столкнулись с состоянием гонки, задайте для параметра приложения Псворкеринпрокконкурренциуппербаунд значение 1 и вместо этого используйте изоляцию уровня языкового рабочего процесса для параллелизма.If you suspect that you're experiencing a race condition, set the PSWorkerInProcConcurrencyUpperBound app setting to 1 and instead use language worker process level isolation for concurrency.

Настройка функции scriptFileConfigure function scriptFile

По умолчанию функция PowerShell выполняется из run.ps1 файла, который использует тот же родительский каталог, что и соответствующий function.json .By default, a PowerShell function is executed from run.ps1, a file that shares the same parent directory as its corresponding function.json.

scriptFileСвойство в function.json можно использовать для получения структуры папок, которая выглядит, как в следующем примере:The scriptFile property in the function.json can be used to get a folder structure that looks like the following example:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.ps1

В этом случае function.json для myFunction включает scriptFile свойство, ссылающееся на файл с экспортированной функцией для выполнения.In this case, the function.json for myFunction includes a scriptFile property referencing the file with the exported function to run.

{
  "scriptFile": "../lib/PSFunction.ps1",
  "bindings": [
    // ...
  ]
}

Использование модулей PowerShell с помощью настройки точки входаUse PowerShell modules by configuring an entryPoint

В этой статье показаны функции PowerShell в файле сценария по умолчанию, run.ps1 созданном шаблонами.This article has shown PowerShell functions in the default run.ps1 script file generated by the templates. Однако можно также включить функции в модули PowerShell.However, you can also include your functions in PowerShell modules. Вы можете ссылаться на код конкретной функции в модуле, используя scriptFile entryPoint поля и в function.jsв файле конфигурации.You can reference your specific function code in the module by using the scriptFile and entryPoint fields in the function.json` configuration file.

В этом случае entryPoint — это имя функции или командлета в модуле PowerShell, на который ссылается scriptFile .In this case, entryPoint is the name of a function or cmdlet in the PowerShell module referenced in scriptFile.

Рассмотрим следующую структуру папок:Consider the following folder structure:

FunctionApp
 | - host.json
 | - myFunction
 | | - function.json
 | - lib
 | | - PSFunction.psm1

Где PSFunction.psm1 содержит:Where PSFunction.psm1 contains:

function Invoke-PSTestFunc {
    param($InputBinding, $TriggerMetadata)

    Push-OutputBinding -Name OutputBinding -Value "output"
}

Export-ModuleMember -Function "Invoke-PSTestFunc"

В этом примере конфигурация myFunction включает scriptFile свойство, которое ссылается на PSFunction.psm1 модуль PowerShell в другой папке.In this example, the configuration for myFunction includes a scriptFile property that references PSFunction.psm1, which is a PowerShell module in another folder. entryPointСвойство ссылается на Invoke-PSTestFunc функцию, которая является точкой входа в модуле.The entryPoint property references the Invoke-PSTestFunc function, which is the entry point in the module.

{
  "scriptFile": "../lib/PSFunction.psm1",
  "entryPoint": "Invoke-PSTestFunc",
  "bindings": [
    // ...
  ]
}

В этой конфигурации объект Invoke-PSTestFunc выполняется точно так же, как и run.ps1 .With this configuration, the Invoke-PSTestFunc gets executed exactly as a run.ps1 would.

Рекомендации по функциям PowerShellConsiderations for PowerShell functions

При работе с функциями PowerShell учитывайте рекомендации в следующих разделах.When you work with PowerShell functions, be aware of the considerations in the following sections.

Холодный запускCold Start

При разработке функций Azure в модели размещения, не поддерживающей сервер, холодный запуск — это реальность.When developing Azure Functions in the serverless hosting model, cold starts are a reality. Холодный запуск — это период времени, который требуется для запуска приложения-функции для обработки запроса.Cold start refers to period of time it takes for your function app to start running to process a request. Холодный запуск чаще всего происходит в плане потребления, так как приложение-функция завершает работу в периоды бездействия.Cold start happens more frequently in the Consumption plan because your function app gets shut down during periods of inactivity.

Используйте модули пакета вместо Install-ModuleBundle modules instead of using Install-Module

Сценарий выполняется при каждом вызове.Your script is run on every invocation. Избегайте использования Install-Module в скрипте.Avoid using Install-Module in your script. Вместо этого используйте Save-Module перед публикацией, чтобы функция не могла тратить время на загрузку модуля.Instead use Save-Module before publishing so that your function doesn't have to waste time downloading the module. Если холодный запуск влияет на ваши функции, рассмотрите возможность развертывания приложения-функции в плане службы приложений со значением Always on или в плане Premium.If cold starts are impacting your functions, consider deploying your function app to an App Service plan set to always on or to a Premium plan.

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

Дополнительные сведения см. в следующих ресурсах:For more information, see the following resources: