Guia para programadores do PowerShell das Funções do Azure

Este artigo fornece detalhes sobre como você escreve o Azure Functions usando o PowerShell.

Uma função (função) do PowerShell Azure é representada como um script do PowerShell que é executado quando acionado. Cada script de função tem um arquivo relacionado function.json que define como a função se comporta, como ela é acionada e seus parâmetros de entrada e saída. Para saber mais, consulte o artigo Gatilhos e vinculação.

Como outros tipos de funções, as function.json funções de script do PowerShell recebem parâmetros que correspondem aos nomes de todas as ligações de entrada definidas no arquivo. Também é passado um TriggerMetadata parâmetro que contém informações adicionais sobre o gatilho que iniciou a função.

Este artigo pressupõe que você já tenha lido a referência do desenvolvedor do Azure Functions. Você também deve ter concluído o início rápido do Functions para o PowerShell para criar sua primeira função do PowerShell.

Estrutura de pastas

A estrutura de pastas necessária para um projeto do PowerShell tem a seguinte aparência. Esse padrão pode ser alterado. Para obter mais informações, consulte a seção scriptFile abaixo.

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

Na raiz do projeto, há um arquivo compartilhado host.json que pode ser usado para configurar o aplicativo de função. Cada função tem uma pasta com seu próprio arquivo de código (.ps1) e arquivo de configuração de vinculação (function.json). O nome do diretório pai do arquivo function.json é sempre o nome da sua função.

Certas associações requerem a presença de um extensions.csproj arquivo. As extensões de ligação, necessárias na versão 2.x e versões posteriores do tempo de execução do Functions, são definidas no extensions.csproj arquivo, com os arquivos de biblioteca reais na bin pasta. Ao desenvolver localmente, você deve registrar extensões de vinculação. Ao desenvolver funções no portal do Azure, esse registro é feito para você.

Nos Aplicativos de Função do PowerShell, você pode, opcionalmente, ter um profile.ps1 que é executado quando um aplicativo de função começa a ser executado (caso contrário, conhecido como início a frio). Para obter mais informações, consulte Perfil do PowerShell.

Definindo um script do PowerShell como uma função

Por padrão, o tempo de execução do Functions procura sua função no run.ps1, onde run.ps1 compartilha o mesmo diretório pai que seu correspondente function.json.

Seu script é passado uma série de argumentos na execução. Para manipular esses parâmetros, adicione um param bloco à parte superior do script, como no exemplo a seguir:

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

Parâmetro TriggerMetadata

O TriggerMetadata parâmetro é usado para fornecer informações adicionais sobre o gatilho. Os metadados adicionais variam de associação para ligação, mas todos eles contêm uma propriedade que contém os sys seguintes dados:

$TriggerMetadata.sys

Property	Descrição	Type
UtcNow	Quando, em UTC, a função foi acionada	DateTime
MethodName	O nome da função que foi acionada	string
RandGuid	Um GUID único para esta execução da função	string

Cada tipo de gatilho tem um conjunto diferente de metadados. Por exemplo, o $TriggerMetadata for QueueTrigger contém o InsertionTime, Id, , DequeueCountentre outras coisas. Para obter mais informações sobre os metadados do gatilho de fila, vá para a documentação oficial dos gatilhos de fila. Verifique a documentação sobre os gatilhos com os quais você está trabalhando para ver o que vem dentro dos metadados do gatilho.

Enlaces

No PowerShell, as associações são configuradas e definidas no function.json de uma função. As funções interagem com ligações de várias maneiras.

Leitura de dados de gatilho e de entrada

As ligações de gatilho e entrada são lidas como parâmetros passados para sua função. As ligações de entrada têm um direction definido como in em function.json. A name propriedade definida em function.json é o nome do parâmetro, no param bloco . Como o PowerShell usa parâmetros nomeados para vinculação, a ordem dos parâmetros não importa. No entanto, é uma prática recomendada seguir a ordem das ligações definidas no function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Gravando dados de saída

Em Funções, uma ligação de saída tem um direction conjunto como out no function.json. Você pode gravar em uma associação de saída usando o Push-OutputBinding cmdlet, que está disponível para o tempo de execução do Functions. Em todos os casos, a name propriedade da associação, conforme definida em function.json , corresponde ao Name parâmetro do Push-OutputBinding cmdlet.

A seguir mostra como chamar Push-OutputBinding seu script de função:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

Você também pode passar um valor para uma ligação específica através do pipeline.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding comporta-se de forma diferente com base no valor especificado para -Name:

• Quando o nome especificado não pode ser resolvido para uma ligação de saída válida, então um erro é lançado.

• Quando a associação de saída aceita uma coleção de valores, você pode chamar Push-OutputBinding repetidamente para enviar vários valores.

• Quando a ligação de saída só aceita um valor singleton, chamar Push-OutputBinding uma segunda vez gera um erro.

Sintaxe Push-OutputBinding

Os seguintes parâmetros são válidos para chamar Push-OutputBinding:

Nome	Tipo	Position	Description
-Name	String	1	O nome da associação de saída que você deseja definir.
-Value	Object	2	O valor da associação de saída que você deseja definir, que é aceito do pipeline ByValue.
-Clobber	ParâmetroSwitch	Nomeado	(Opcional) Quando especificado, força o valor a ser definido para uma ligação de saída especificada.

Os seguintes parâmetros comuns também são suportados:

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

Para obter mais informações, consulte Sobre CommonParameters.

Exemplo de Push-OutputBinding: respostas HTTP

Um gatilho HTTP retorna uma resposta usando uma ligação de saída chamada response. No exemplo a seguir, a ligação de saída de response tem o valor de "output #1":

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

Como a saída é para HTTP, que aceita apenas um valor singleton, um erro é lançado quando Push-OutputBinding é chamado uma segunda vez.

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

Para saídas que aceitam apenas valores singleton, você pode usar o -Clobber parâmetro para substituir o valor antigo em vez de tentar adicionar a uma coleção. O exemplo a seguir pressupõe que você já tenha adicionado um valor. -ClobberUsando , a resposta do exemplo a seguir substitui o valor existente para retornar um valor de "saída #3":

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

Exemplo de Push-OutputBinding: Vinculação de saída de fila

Push-OutputBindingé usado para enviar dados para associações de saída, como uma associação de saída de armazenamento de fila do Azure. No exemplo a seguir, a mensagem gravada na fila tem um valor de "saída #1":

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

A associação de saída para uma fila de armazenamento aceita vários valores de saída. Nesse caso, chamar o exemplo a seguir após o primeiro grava na fila uma lista com dois itens: "output #1" e "output #2".

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

O exemplo a seguir, quando chamado após os dois anteriores, adiciona mais dois valores à coleção de saída:

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

Quando gravada na fila, a mensagem contém estes quatro valores: "output #1", "output #2", "output #3" e "output #4".

Cmdlet Get-OutputBinding

Você pode usar o Get-OutputBinding cmdlet para recuperar os valores atualmente definidos para suas associações de saída. Este cmdlet obtém uma tabela hash que contém os nomes dos enlaces de saída com os valores.

Segue-se um exemplo de utilização Get-OutputBinding para devolver valores de ligação atuais:

Get-OutputBinding

Name                           Value
----                           -----
MyQueue                        myData
MyOtherQueue                   myData

Get-OutputBinding também contém um parâmetro chamado -Name, que pode ser usado para filtrar a associação retornada, como no exemplo a seguir:

Get-OutputBinding -Name MyQ*

Name                           Value
----                           -----
MyQueue                        myData

Curingas (*) são suportados em Get-OutputBinding.

Registo

O registro em log nas funções do PowerShell funciona como o log regular do PowerShell. Você pode usar os cmdlets de log para gravar em cada fluxo de saída. Cada cmdlet mapeia para um nível de log usado pelo Functions.

Nível de registo de funções	Cmdlet de registro em log
Erro	Write-Error
Aviso	Write-Warning
Informação	Write-Information Write-Host Write-Output Grava no nível de Information log.
Depurar	Write-Debug
Rastreio	Write-Progress Write-Verbose

Além desses cmdlets, qualquer coisa gravada no pipeline é redirecionada para o nível de Information log e exibida com a formatação padrão do PowerShell.

Importante

Usar os cmdlets ou Write-Debug não é suficiente para ver o Write-Verbose registro detalhado e de nível de depuração. Você também deve configurar o limite de nível de log, que declara o nível de logs que realmente lhe interessa. Para saber mais, consulte Configurar o nível de log do aplicativo de função.

Configurar o nível de log do aplicativo de função

O Azure Functions permite definir o nível de limite para facilitar o controle da maneira como o Functions grava nos logs. Para definir o limite para todos os rastreamentos gravados no console, use a logging.logLevel.defaulthost.json propriedade no arquivo. Esta definição aplica-se a todas as funções na sua aplicação de funções.

O exemplo a seguir define o limite para habilitar o log detalhado para todas as funções, mas define o limite para habilitar o log de depuração para uma função chamada MyFunction:

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

Para obter mais informações, consulte host.json referência.

Visualizando os logs

Se seu Aplicativo de Função estiver sendo executado no Azure, você poderá usar o Application Insights para monitorá-lo. Leia o monitoramento do Azure Functions para saber mais sobre como exibir e consultar logs de funções.

Se você estiver executando seu aplicativo de função localmente para desenvolvimento, registra o padrão no sistema de arquivos. Para ver os logs no console, defina a AZURE_FUNCTIONS_ENVIRONMENT variável de ambiente como Development antes de iniciar o aplicativo de função.

Tipos de gatilhos e ligações

Há uma série de gatilhos e associações disponíveis para você usar com seu aplicativo de função. A lista completa de gatilhos e ligações pode ser encontrada aqui.

Todos os gatilhos e ligações são representados no código como alguns tipos de dados reais:

• Hashtable
• string
• byte[]
• número inteiro
• duplo
• HttpRequestContext
• HttpResponseContext

Os cinco primeiros tipos nesta lista são tipos .NET padrão. Os dois últimos são usados apenas pelo gatilho HttpTrigger.

Cada parâmetro de vinculação em suas funções deve ser um desses tipos.

Gatilhos e ligações HTTP

Os gatilhos HTTP e webhook e as ligações de saída HTTP usam objetos de solicitação e resposta para representar as mensagens HTTP.

Objeto de solicitação

O objeto de solicitação que é passado para o script é do tipo HttpRequestContext, que tem as seguintes propriedades:

Property	Descrição	Type
Body	Um objeto que contém o corpo da solicitação. Body é serializado no melhor tipo com base nos dados. Por exemplo, se os dados forem JSON, serão transmitidos como uma tabela hash. Se os dados forem uma cadeia de caracteres, eles serão passados como uma cadeia de caracteres.	objeto
Headers	Um dicionário que contém os cabeçalhos de solicitação.	Cadeia de dicionário<, string>*
Method	O método HTTP da solicitação.	string
Params	Um objeto que contém os parâmetros de roteamento da solicitação.	Cadeia de dicionário<, string>*
Query	Um objeto que contém os parâmetros de consulta.	Cadeia de dicionário<, string>*
Url	O URL do pedido.	string

^* Todas as chaves não diferenciam maiúsculas Dictionary<string,string> de minúsculas.

Objeto de resposta

O objeto de resposta que você deve enviar de volta é do tipo HttpResponseContext, que tem as seguintes propriedades:

Property	Descrição	Type
Body	Um objeto que contém o corpo da resposta.	objeto
ContentType	Uma pequena mão para definir o tipo de conteúdo para a resposta.	string
Headers	Um objeto que contém os cabeçalhos de resposta.	Dicionário ou Tabela Hash
StatusCode	O código de status HTTP da resposta.	string ou int

Acesso ao pedido e à resposta

Quando você trabalha com gatilhos HTTP, você pode acessar a solicitação HTTP da mesma forma que faria com qualquer outra ligação de entrada. Está no param bloco.

Use um HttpResponseContext objeto para retornar uma resposta, conforme mostrado a seguir:

function.json

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

run.ps1

param($req, $TriggerMetadata)

$name = $req.Query.Name

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

O resultado da invocação desta função seria:

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

Type-casting para gatilhos e ligações

Para determinadas associações, como a ligação blob, você pode especificar o tipo do parâmetro.

Por exemplo, para que os dados do armazenamento de Blob sejam fornecidos como uma cadeia de caracteres, adicione o seguinte tipo de conversão ao meu param bloco:

param([string] $myBlob)

Perfil do PowerShell

No PowerShell, há o conceito de um perfil do PowerShell. Se você não estiver familiarizado com perfis do PowerShell, consulte Sobre perfis.

No PowerShell Functions, o script de perfil é executado uma vez por instância de trabalho do PowerShell no aplicativo quando implantado pela primeira vez e depois de ser ocioso (início a frio. Quando a simultaneidade é habilitada definindo o valor PSWorkerInProcConcurrencyUpperBound , o script de perfil é executado para cada espaço de execução criado.

Quando você cria um aplicativo de função usando ferramentas, como o Visual Studio Code e as Ferramentas Principais do Azure Functions, um padrão profile.ps1 é criado para você. O perfil padrão é mantido no repositório GitHub das Ferramentas Principais e contém:

• Autenticação MSI automática no Azure.
• A capacidade de ativar os aliases do PowerShell do Azure PowerShell AzureRM , se desejar.

Versões do PowerShell

A tabela a seguir mostra as versões do PowerShell disponíveis para cada versão principal do tempo de execução do Functions e a versão .NET necessária:

Versão das funções	Versão do PowerShell	Versão .NET
4.x	PowerShell 7.2	.NET 6

Você pode ver a versão atual imprimindo $PSVersionTable a partir de qualquer função.

Para saber mais sobre a política de suporte de tempo de execução do Azure Functions, consulte este artigo

Executando local em uma versão específica

O suporte para o PowerShell 7.0 no Azure Functions terminou em 3 de dezembro de 2022. Para usar o Values PowerShell 7.2 ao executar localmente, você precisa adicionar a configuração "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.2" à matriz no arquivo local.setting.json na raiz do projeto. Quando executado localmente no PowerShell 7.2, seu arquivo de local.settings.json se parece com o exemplo a seguir:

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

Nota

No PowerShell Functions, o valor "~7" para FUNCTIONS_WORKER_RUNTIME_VERSION refere-se a "7.0.x". Não atualizamos automaticamente os aplicativos da Função PowerShell que têm "~7" para "7.2". No futuro, para os Aplicativos de Função do PowerShell, exigiremos que os aplicativos especifiquem a versão principal e secundária que desejam segmentar. Por isso, é necessário mencionar "7.2" se você quiser atingir "7.2.x"

Alterando a versão do PowerShell

O suporte para o PowerShell 7.0 no Azure Functions terminou em 3 de dezembro de 2022. Para atualizar seu Aplicativo de Função para o PowerShell 7.2, verifique se o valor de FUNCTIONS_EXTENSION_VERSION está definido como ~4. Para saber como fazer isso, consulte Exibir e atualizar a versão atual do tempo de execução.

Use as etapas a seguir para alterar a versão do PowerShell usada pelo seu aplicativo de função. Você pode fazer isso no portal do Azure ou usando o PowerShell.

Portal

1. No portal do Azure, navegue até seu aplicativo de função.

2. Em Configurações, escolha Configuração. Na guia Configurações gerais, localize a versão do PowerShell.

   

3. Escolha a versão desejada do PowerShell Core e selecione Salvar. Quando avisado sobre a reinicialização pendente, escolha Continuar. O aplicativo de função é reiniciado na versão escolhida do PowerShell.

PowerShell

Execute o seguinte script para alterar a versão do PowerShell:

Set-AzResource -ResourceId "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Web/sites/<FUNCTION_APP>/config/web" -Properties @{  powerShellVersion  = '<VERSION>' } -Force -UsePatchSemantics

Substitua <SUBSCRIPTION_ID>, <RESOURCE_GROUP>e <FUNCTION_APP> pela ID da sua assinatura do Azure, o nome do seu grupo de recursos e aplicativo de função, respectivamente. Além disso, substitua <VERSION> por 7.2. Pode verificar o valor atualizado da definição powerShellVersion nas Properties da tabela hash devolvida.

O aplicativo de função é reiniciado depois que a alteração é feita na configuração.

Gestão de dependências

O Functions permite que você aproveite a galeria do PowerShell para gerenciar dependências. Com o gerenciamento de dependência habilitado, o arquivo requirements.psd1 é usado para baixar automaticamente os módulos necessários. Você habilita esse comportamento definindo a managedDependency propriedade como true na raiz do arquivo host.json, como no exemplo a seguir:

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

Quando você cria um novo projeto de funções do PowerShell, o gerenciamento de dependência é habilitado por padrão, com o módulo do Azure Az incluído. O número máximo de módulos suportados atualmente é 10. A sintaxe suportada é MajorNumber.* ou a versão exata do módulo, conforme mostrado no seguinte exemplo requirements.psd1:

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

Quando você atualiza o arquivo requirements.psd1, os módulos atualizados são instalados após uma reinicialização.

Versões específicas de destino

Você pode querer direcionar uma versão específica de um módulo em seu arquivo requirements.psd1. Por exemplo, se você quisesse usar uma versão mais antiga do Az.Accounts do que a do módulo Az incluído, você precisaria direcionar uma versão específica, conforme mostrado no exemplo a seguir:

@{
	'Az.Accounts' = '1.9.5'
}

Nesse caso, você também precisa adicionar uma instrução import à parte superior do arquivo profile.ps1, que se parece com o exemplo a seguir:

Import-Module Az.Accounts -RequiredVersion '1.9.5'

Desta forma, a versão mais antiga do módulo Az.Account é carregada primeiro quando a função é iniciada.

Considerações sobre gerenciamento de dependência

As seguintes considerações se aplicam ao usar o gerenciamento de dependência:

• Dependências gerenciadas requer acesso para https://www.powershellgallery.com baixar módulos. Ao executar localmente, certifique-se de que o tempo de execução pode acessar essa URL adicionando quaisquer regras de firewall necessárias.

• Atualmente, as dependências gerenciadas não suportam módulos que exigem que o usuário aceite uma licença, seja aceitando a licença interativamente ou fornecendo -AcceptLicense switch ao invocar Install-Module.

Configurações do aplicativo de gerenciamento de dependência

As seguintes configurações de aplicativo podem ser usadas para alterar como as dependências gerenciadas são baixadas e instaladas.

Configuração do aplicativo de função	Valor predefinido	Description
MDMaxBackgroundUpgradePeriod	7.00:00:00 (sete dias)	Controla o período de atualização em segundo plano para aplicativos de função do PowerShell. Para saber mais, consulte MDMaxBackgroundUpgradePeriod.
MDNewSnapshotCheckPeriod	01:00:00 (uma hora)	Especifica a frequência com que cada trabalhador do PowerShell verifica se as atualizações de dependência gerenciadas foram instaladas. Para saber mais, consulte MDNewSnapshotCheckPeriod.
MDMinBackgroundUpgradePeriod	1.00:00:00 (um dia)	O período de tempo após uma verificação de atualização anterior antes de outra verificação de atualização ser iniciada. Para saber mais, consulte MDMinBackgroundUpgradePeriod.

Essencialmente, a atualização do seu aplicativo começa no MDMaxBackgroundUpgradePeriod, e o processo de atualização é concluído dentro de aproximadamente o MDNewSnapshotCheckPeriod.

Módulos personalizados

Aproveitar seus próprios módulos personalizados no Azure Functions difere de como você faria isso normalmente para o PowerShell.

No computador local, o módulo é instalado em uma das pastas disponíveis globalmente no .$env:PSModulePath Ao executar no Azure, você não tem acesso aos módulos instalados em sua máquina. Isso significa que o $env:PSModulePath para um aplicativo de função do PowerShell difere de um script regular do $env:PSModulePath PowerShell.

Em Funções, PSModulePath contém dois caminhos:

• Uma Modules pasta que existe na raiz do seu aplicativo de função.
• Um caminho para uma Modules pasta que é controlada pelo operador de idioma do PowerShell.

Pasta de módulos de nível de aplicativo de função

Para usar módulos personalizados, você pode colocar módulos nos quais suas funções dependem em uma Modules pasta. A partir desta pasta, os módulos ficam automaticamente disponíveis para o tempo de execução das funções. Qualquer função no aplicativo de função pode usar esses módulos.

Nota

Os módulos especificados no arquivo requirements.psd1 são baixados automaticamente e incluídos no caminho para que você não precise incluí-los na pasta modules. Estes são armazenados localmente na $env:LOCALAPPDATA/AzureFunctions pasta e na /data/ManagedDependencies pasta quando executados na nuvem.

Para aproveitar o recurso de módulo personalizado, crie uma Modules pasta na raiz do seu aplicativo de função. Copie os módulos que você deseja usar em suas funções para este local.

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

Com uma Modules pasta, seu aplicativo de função deve ter a seguinte estrutura de pastas:

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

Quando você inicia seu aplicativo de função, o operador de linguagem do PowerShell adiciona essa Modules pasta ao para que você possa confiar no carregamento automático do $env:PSModulePath módulo da mesma forma que faria em um script normal do PowerShell.

Pasta de módulos de nível de trabalhador de idioma

Vários módulos são comumente usados pelo trabalhador de linguagem do PowerShell. Estes módulos são definidos na última posição de PSModulePath.

A lista atual de módulos é a seguinte:

• Microsoft.PowerShell.Archive: módulo usado para trabalhar com arquivos, como .zip, .nupkge outros.
• ThreadJob: uma implementação baseada em threads das APIs de trabalho do PowerShell.

Por padrão, o Functions usa a versão mais recente desses módulos. Para usar uma versão específica do Modules módulo, coloque essa versão específica na pasta do seu aplicativo de função.

Variáveis de ambiente

Em Funções, as configurações do aplicativo, como cadeias de conexão de serviço, são expostas como variáveis de ambiente durante a execução. Você pode acessar essas configurações usando $env:NAME_OF_ENV_VARo , conforme mostrado no exemplo a seguir:

param($myTimer)

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

Há várias maneiras de adicionar, atualizar e excluir as configurações do aplicativo de função:

• No portal do Azure.
• Usando a CLI do Azure.
• Usando o Azure PowerShell.

As alterações nas configurações do aplicativo de função exigem que seu aplicativo de função seja reiniciado.

Quando executado localmente, as configurações do aplicativo são lidas a partir do arquivo de projeto local.settings.json .

Simultaneidade

Por padrão, o tempo de execução do Functions PowerShell só pode processar uma invocação de uma função de cada vez. No entanto, esse nível de simultaneidade pode não ser suficiente nas seguintes situações:

• Quando você está tentando lidar com um grande número de invocações ao mesmo tempo.
• Quando você tem funções que invocam outras funções dentro do mesmo aplicativo de função.

Existem alguns modelos de simultaneidade que você pode explorar dependendo do tipo de carga de trabalho:

• Aumentar FUNCTIONS_WORKER_PROCESS_COUNT. Isso permite manipular invocações de função em vários processos dentro da mesma instância, o que introduz determinada sobrecarga de CPU e memória. Em geral, as funções ligadas a E/S não sofrerão com essa sobrecarga. Para funções ligadas à CPU, o impacto pode ser significativo.

• Aumente o valor da configuração do PSWorkerInProcConcurrencyUpperBound aplicativo. Isso permite a criação de vários espaços de execução dentro do mesmo processo, o que reduz significativamente a sobrecarga de CPU e memória.

Você define essas variáveis de ambiente nas configurações do aplicativo de função.

Dependendo do seu caso de uso, as funções duráveis podem melhorar significativamente a escalabilidade. Para saber mais, consulte Padrões de aplicativo Durable Functions.

Nota

Você pode receber avisos de "solicitações estão sendo enfileiradas devido a não haver espaços de execução disponíveis", observe que isso não é um erro. A mensagem informa que as solicitações estão sendo enfileiradas e serão tratadas quando as solicitações anteriores forem concluídas.

Considerações sobre o uso da simultaneidade

O PowerShell é uma linguagem de script single_threaded por padrão. No entanto, a simultaneidade pode ser adicionada usando vários espaços de execução do PowerShell no mesmo processo. O número de espaços de execução criados e, portanto, o número de threads simultâneos por trabalhador, é limitado pela configuração do PSWorkerInProcConcurrencyUpperBound aplicativo. Por padrão, o número de espaços de execução é definido como 1.000 na versão 4.x do tempo de execução do Functions. Nas versões 3.x e inferiores, o número máximo de espaços de execução é definido como 1. A taxa de transferência será afetada pela quantidade de CPU e memória disponível no plano selecionado.

O Azure PowerShell usa alguns contextos e estados no nível do processo para ajudar a evitar o excesso de digitação. No entanto, se você ativar a simultaneidade em seu aplicativo de função e invocar ações que mudam de estado, você pode acabar com condições de corrida. Essas condições de corrida são difíceis de depurar porque uma invocação depende de um determinado estado e a outra invocação mudou o estado.

Há um imenso valor na simultaneidade com o Azure PowerShell, já que algumas operações podem levar uma quantidade considerável de tempo. No entanto, deve proceder com precaução. Se você suspeitar que está enfrentando uma condição de corrida, defina a configuração do aplicativo PSWorkerInProcConcurrencyUpperBound como 1 e, em vez disso, use o isolamento de nível de processo do trabalhador de idioma para simultaneidade.

Configurar função scriptFile

Por padrão, uma função do PowerShell é executada a partir de run.ps1, um arquivo que compartilha o mesmo diretório pai que seu diretório correspondente function.json.

A scriptFile propriedade no function.json pode ser usada para obter uma estrutura de pastas que se parece com o exemplo a seguir:

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

Nesse caso, o function.json for myFunction inclui uma scriptFile propriedade que faz referência ao arquivo com a função exportada a ser executada.

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

Usar módulos do PowerShell configurando um entryPoint

Este artigo mostrou as funções do PowerShell no arquivo de script padrão run.ps1 gerado pelos modelos. No entanto, você também pode incluir suas funções nos módulos do PowerShell. Você pode fazer referência ao seu código de função específico no módulo usando os scriptFile campos e entryPoint no arquivo de configuração do function.json.

Nesse caso, entryPoint é o nome de uma função ou cmdlet no módulo do PowerShell referenciado em scriptFile.

Considere a seguinte estrutura de pastas:

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

Onde PSFunction.psm1 contém:

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

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

Export-ModuleMember -Function "Invoke-PSTestFunc"

Neste exemplo, a configuração para inclui uma scriptFile propriedade que faz referência PSFunction.psm1a myFunction , que é um módulo do PowerShell em outra pasta. A entryPoint propriedade faz referência à Invoke-PSTestFunc função, que é o ponto de entrada no módulo.

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

Com essa configuração, o Invoke-PSTestFunc é executado exatamente como faria run.ps1 .

Considerações para funções do PowerShell

Ao trabalhar com funções do PowerShell, esteja ciente das considerações nas seções a seguir.

Arranque a frio

Ao desenvolver o Azure Functions no modelo de hospedagem sem servidor, os arranques a frio são uma realidade. Início a frio refere-se ao período de tempo que leva para que seu aplicativo de função comece a ser executado para processar uma solicitação. O arranque a frio acontece com mais frequência no plano de Consumo porque a sua aplicação funcional é encerrada durante os períodos de inatividade.

Agrupar módulos em vez de usar o Install-Module

Seu script é executado em cada invocação. Evite usar Install-Module em seu script. Em vez disso, use Save-Module antes de publicar para que sua função não tenha que perder tempo baixando o módulo. Se os arranques a frio estiverem a afetar as suas funções, considere implementar a sua aplicação funcional num plano do Serviço de Aplicação definido como sempre ativado ou num plano Premium.

Próximos passos

Para obter mais informações, consulte os seguintes recursos:

• Best Practices for Azure Functions (Melhores Práticas para as Funções do Azure)
• Referência para programadores das Funções do Azure
• Gatilhos e associações do Azure Functions