Compartilhar via

Guia do desenvolvedor do PowerShell do Azure Functions

  • Artigo

Veja neste artigo detalhes de como escrever no Azure Functions usando o PowerShell.

Uma função do Azure PowerShell é representada como um script do PowerShell executado quando disparado. Cada script de função tem um arquivo function.json relacionado que define como a função se comporta, por exemplo, como é disparada e seus parâmetros de entrada e saída. Para saber mais, confira o artigo Gatilhos e associação.

Assim como outros tipos de funções, as funções de script do PowerShell assumem parâmetros que correspondem aos nomes de todas as associações de entrada definidas no arquivo function.json. Um parâmetro TriggerMetadata também é transmitido e 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. Ele também pressupõe que você concluiu o Início rápido de funções para o PowerShell para criar sua primeira função no PowerShell.

Estrutura de pastas

A estrutura de pastas necessária para um projeto do PowerShell é semelhante à mostrada a seguir. Este padrão pode ser alterado. Para mais informações, consulte a seção scriptFile.

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 host.json compartilhado que pode ser usado para configurar o aplicativo de funções. Cada função tem uma pasta com o próprio arquivo de código (.ps1) e o arquivo de configuração de associação (function.json). O nome do diretório pai do arquivo function.json é sempre o nome da sua função.

Determinadas associações exigem a presença de um arquivo extensions.csproj. As extensões de associação necessárias na versão 2.x e posteriores do runtime do Functions são definidas no arquivo extensions.csproj, com os arquivos de biblioteca reais na pasta bin. Ao desenvolver localmente, você precisa registrar as extensões de associação. Ao desenvolver funções no portal do Azure, esse registro é feito por você.

Em aplicativos de funções do PowerShell, existe a opção de ter um profile.ps1 que é executado quando um aplicativo de funções começa a ser executado (também conhecido como inicialização a frio). Para saber mais, confira Perfil do PowerShell.

Definir um script do PowerShell como função

Por padrão, o runtime de Funções procura sua função em run.ps1, onde run.ps1 compartilha o mesmo diretório pai que o function.json correspondente.

Seu script é recebe vários argumentos na execução. Para lidar com esses parâmetros, adicione um bloco param à parte superior do seu script, como no seguinte exemplo:

# $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 parâmetro TriggerMetadata é usado para fornecer informações adicionais sobre o gatilho. Estes metadados variam entre as associações, mas todos contêm uma propriedade sys com os seguintes dados:

$TriggerMetadata.sys
Propriedade Descrição Type
UtcNow Quando a função foi disparada em UTC Datetime
MethodName O nome da função que foi disparada string
RandGuid um GUID exclusivo para esta execução da função string

Cada tipo de gatilho tem um conjunto diferente de metadados. Por exemplo, $TriggerMetadata para QueueTrigger contém InsertionTime, Id, DequeueCount, entre outros. Para saber mais sobre os metadados do gatilho da fila, acesse a documentação oficial dos gatilhos de fila. Verifique a documentação sobre gatilhos para ver o que acontece nos metadados de gatilho.

Associações

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

Gatilho de leitura e dados de entrada

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

param($MyFirstInputBinding, $MySecondInputBinding)

Gravar dados de saída

No Functions, uma associação de saída tem um direction definido como out em function.json. É possível gravar em uma associação de saída usando o cmdlet Push-OutputBinding, que está disponível para o runtime do Functions. Em todos os casos, a propriedade name da associação, conforme definido em function.json, corresponde ao parâmetro Name do cmdlet Push-OutputBinding.

Veja no exemplo abaixo como chamar Push-OutputBinding no script da função:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

Também é possível passar um valor para uma associação específica por meio do pipeline.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

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

  • Quando o nome especificado não puder ser resolvido para uma associação de saída válida, um erro será gerado.

  • Quando a associação de saída aceita uma coleção de valores, chame Push-OutputBinding repetidamente para efetuar push de vários valores.

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

Sintaxe Push-OutputBinding

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

Nome Tipo Posição Descrição
-Name String 1 O nome da associação de saída que você quer definir.
-Value Objeto 2 O valor da associação de saída que você quer definir, que é aceita no pipeline ByValue.
-Clobber SwitchParameter nomeado (Opcional) Quando especificado, força o valor a ser definido para uma associação de saída especificada.

Estes parâmetros comuns também são compatíveis:

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

Para saber mais, confira Sobre CommonParameters.

Exemplo de Push-OutputBinding: respostas HTTP

Um gatilho HTTP retorna uma resposta usando uma associação de saída denominada response. No seguinte exemplo, a associação de saída de response tem o valor de "saída 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 é gerado quando Push-OutputBinding é chamado pela segunda vez.

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

Para saídas que aceitam só valores singleton, use o parâmetro -Clobber para substituir o valor antigo em vez de tentar adicionar a uma coleção. O exemplo a seguir pressupõe que você já adicionou um valor. Usando -Clobber, a resposta do seguinte exemplo 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: associaçã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 do Armazenamento de Filas do Azure. No seguinte exemplo, 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 do Armazenamento aceita vários valores de saída. Nesse caso, chamar o exemplo a seguir após o primeiro grava na fila em uma lista com dois itens: "saída 1" e "saída 2".

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

O seguinte exemplo, 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: "saída 1", "saída 2", "saída 3" e "saída 4".

Cmdlet Get-OutputBinding

Use o cmdlet Get-OutputBinding para recuperar os valores definidos atualmente para as associações de saída. Esse cmdlet recupera uma tabela de hash que contém os nomes das associações de saída com seus respectivos valores.

Veja abaixo um exemplo de como usar Get-OutputBinding para retornar os valores de associaçã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 seguinte exemplo:

Get-OutputBinding -Name MyQ*

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

Caracteres curinga (*) são compatíveis com Get-OutputBinding.

Log

O registro em log funciona normalmente nas funções do PowerShell. Use os cmdlets de registro em log para gravar em cada fluxo de saída. Cada cmdlet é mapeado em um nível de registro usado pelo Functions.

Nível de registros em log do Functions Cmdlet de registro em log
Erro Write-Error
Aviso Write-Warning
Informações do Write-Information
Write-Host
Write-Output
Grava no nível de log Information.
Depurar Write-Debug
Trace Write-Progress
Write-Verbose

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

Importante

Usar os cmdlets Write-Verbose ou Write-Debug não é suficiente para ver o registro em log detalhado e no nível de depuração. É preciso configurar o limite do nível de registro em log, que declara o nível de registros que realmente importa. Para saber mais, confira Configurar o nível de registro em log do aplicativo de funções.

Configurar o nível de registro em log do aplicativo de funções

O Azure Functions permite definir o nível de limite para facilitar o controle da maneira como o Functions grava os registros. Para definir o limite para todos os rastreamentos gravados no console, use a propriedade logging.logLevel.default no host.jsonarquivo. Essa configuração se aplica a todas as funções em seu aplicativo de função.

O exemplo seguinte define o limite para habilitar o registro detalhado de todas as funções, mas também para habilitar o registro em log de depuração de uma função chamada MyFunction:

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

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

Ver os registros

Se o aplicativo de funções estiver em execução no Azure, use o Application Insights para monitorá-lo. Leia Monitorado o Azure Functions para saber mais sobre como exibir e consultar logs de função.

Se o aplicativo de funções estiver em execução no local para desenvolvimento, os registros terão como padrão o sistema de arquivos. Para ver os registros no console, defina a variável de ambiente AZURE_FUNCTIONS_ENVIRONMENT como Development antes de iniciar o aplicativo de funções.

Tipos de gatilhos e associações

Há vários gatilhos e associações disponíveis para usar com o aplicativo de funções. A lista completa de gatilhos e associações pode ser encontrada aqui.

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

  • Hashtable
  • string
  • byte[]
  • INT
  • double
  • HttpRequestContext
  • HttpResponseContext

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

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

Gatilhos e associações HTTP

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

Objeto da solicitação

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

Propriedade 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, ele será passado como uma tabela de hash. Se os dados forem uma cadeia de caracteres, serão passados como uma cadeia de caracteres. objeto
Headers Um dicionário que contém os cabeçalhos de solicitação. <Cadeia de caracteres,cadeia de caracteres>* de dicionário
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 caracteres,cadeia de caracteres>* de dicionário
Query Um objeto que contém os parâmetros da consulta. <Cadeia de caracteres,cadeia de caracteres>* de dicionário
Url A URL da solicitação. string

* Nenhuma das teclas Dictionary<string,string> diferenciam maiúsculas e minúsculas.

Objeto de resposta

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

Propriedade Descrição Type
Body Um objeto que contém o corpo da resposta. objeto
ContentType Um atalho para configurar o tipo de conteúdo da resposta. string
Headers Um objeto que contém os cabeçalhos da resposta. Dicionário ou tabela de hash
StatusCode O código de status HTTP da resposta. cadeia de caracteres ou inteiro

Acessar a solicitação e a resposta

Ao trabalhar com gatilhos HTTP, você pode acessar a solicitação HTTP do mesmo jeito que faria com qualquer outra associação de entrada. Ela fica no bloco param.

Use um objeto HttpResponseContext para retornar uma resposta, conforme mostrado no exemplo abaixo:

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 dessa função seria:

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

Conversão de tipo para gatilhos e associações

Em determinadas associações, como a associação de blobs, é possível especificar o tipo do parâmetro.

Por exemplo, para fornecer dados do Armazenamento de Blobs como uma cadeia de caracteres, adicione a seguinte conversão de tipo ao bloco param:

param([string] $myBlob)

Perfil do PowerShell

No PowerShell, há o conceito de perfil do PowerShell. Se você não conhece os perfis do PowerShell, confira Sobre os perfis.

Nas funções do PowerShell, o script do perfil é executado uma vez por instância de trabalho do PowerShell na primeira implantação do aplicativo e após ele ficar ocioso (inicialização a frio). Quando a simultaneidade é habilitada por meio da definição do valor PSWorkerInProcConcurrencyUpperBound, o script do perfil é executado para cada runspace criado.

Ao criar um aplicativo de funções usando ferramentas como o Visual Studio Code e o Azure Functions Core Tools, um profile.ps1 padrão é criado para você. O perfil padrão é mantido no repositório GitHub do Core Tools e contém:

  • Autenticação automática de MSI para o Azure.
  • Capacidade de ativar os aliases AzureRM do Azure PowerShell se você quiser.

Versões do PowerShell

Veja na seguinte tabela as versões do PowerShell disponíveis para cada versão principal do runtime do Functions e a versão do .NET exigida:

Versão do Functions Versão do PowerShell Versão do .NET
4.x PowerShell 7.4 .NET 8
4.x PowerShell 7.2 (fim do suporte) .NET 6

Veja a versão atual imprimindo $PSVersionTable em qualquer função.

Para saber mais sobre a política de suporte do Azure Functions Runtime, veja esteartigo

Observação

O suporte para o PowerShell 7.2 no Azure Functions terminou em 8 de novembro de 2024. Talvez seja necessário resolver algumas alterações significativas ao atualizar suas funções do PowerShell 7.2 para serem executadas no PowerShell 7.4. Siga este guia de migração para atualizar para o PowerShell 7.4.

Execução local em uma versão específica

Ao executar as funções do PowerShell localmente, é preciso adicionar a configuração "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4" à matriz Values no arquivo local.setting.json na raiz do projeto. Ao executar localmente no PowerShell 7.4, seu arquivo local.settings.json é semelhante ao seguinte exemplo:

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

Observação

No PowerShell Functions, o valor "~7" para FUNCTIONS_WORKER_RUNTIME_VERSION refere-se a "7.0.x". Não atualizamos automaticamente os aplicativos de funções do PowerShell que têm "~7" para "7.4". Daqui para frente, para Aplicativos de Funções do PowerShell, exigiremos que os aplicativos especifiquem a versão principal e secundária que eles desejam direcionar. Portanto, será necessário mencionar "7.4" se você quiser direcionar "7.4.x"

Alterar a versão do PowerShell

Leve essas considerações em conta antes de migrar seu aplicativo de funções do PowerShell para o PowerShell 7.4:

  • Como a migração pode introduzir alterações significativas em seu aplicativo, examine este guia de migração antes de atualizar seu aplicativo para o PowerShell 7.4.

  • Verifique se o aplicativo de funções está em execução na versão mais recente do runtime do Functions no Azure, que é a versão 4.x. Para obter mais informações, confira Exibir e atualizar a versão atual do runtime.

Siga estas etapas para alterar a versão do PowerShell usada pelo seu aplicativo de funções. Você pode executar essa operação no portal do Azure ou usando o PowerShell.

  1. No portal do Azure, navegue até o aplicativo de funções.

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

    image

  3. Escolha a versão do PowerShell Core desejada e clique em Salvar. Clique em Continuar quando a mensagem de reinicialização pendente for exibida. O aplicativo de funções é reiniciado na versão escolhida do PowerShell.

Observação

O suporte do Azure Functions para o PowerShell 7.4 está em GA (disponibilidade geral). Você pode ver o PowerShell 7.4 ainda indicado como versão prévia no portal do Azure, mas isso será atualizado em breve para refletir o status de GA.

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

Gerenciamento de dependência

O gerenciamento de módulos no Azure Functions escritos no PowerShell pode ser abordado de duas maneiras: usando o recurso de Dependências Gerenciadas ou incluindo os módulos diretamente no conteúdo do aplicativo. Cada método tem suas próprias vantagens e escolher o certo depende de suas necessidades específicas.

Escolhendo a abordagem certa de gerenciamento de módulo

Por que usar o recurso de Dependências Gerenciadas?

  • Instalação inicial simplificada: manipula automaticamente a instalação do módulo com base no arquivo requirements.psd1.
  • Atualizações automáticas: os módulos são atualizados automaticamente, incluindo correções de segurança, sem a necessidade de intervenção manual.

Por que incluir módulos no conteúdo do aplicativo?

  • Sem dependência da Galeria do PowerShell: os módulos são agrupados com seu aplicativo, eliminando dependências externas.
  • Mais controle: evita o risco de regressões causadas por atualizações automáticas, fornecendo controle total sobre quais versões do módulo são usadas.
  • Compatibilidade: funciona no Consumo Flexível e é recomendado para outras SKUs do Linux.

Recurso de Dependências Gerenciadas

O recurso de Dependências Gerenciadas permite que o Azure Functions baixe e gerencie automaticamente os módulos do PowerShell especificados no arquivo requirements.psd1. Esse recurso é habilitado por padrão em novos aplicativos de funções do PowerShell.

Configuração de requirements.psd1

Para usar Dependências Gerenciadas no Azure Functions com o PowerShell, você precisa configurar um arquivo requirements.psd1. Esse arquivo especifica os módulos necessários para sua função e o Azure Functions baixa e atualiza esses módulos automaticamente para garantir que seu ambiente permaneça atualizado.

Veja como instalar e configurar o arquivo de requirements.psd1:

  1. Crie um arquivo requirements.psd1 no diretório raiz da função do Azure se ainda não existir.
  2. Defina os módulos e suas versões em uma estrutura de dados do PowerShell.

Exemplo de arquivo requirements.psd1:

@{
    'Az' = '9.*'  # Specifies the Az module and will use the latest version with major version 9
}

Incluindo módulos no conteúdo do aplicativo

Para obter mais controle sobre as versões do módulo e para evitar dependências de recursos externos, você pode incluir módulos diretamente no conteúdo do aplicativo de funções.

Para incluir módulos personalizados:

  1. Crie uma pasta Modules na raiz do aplicativo de funções.

    mkdir ./Modules

  2. Copie módulos para a pasta Modules usando um dos seguintes métodos:

    • Se os módulos já estiverem disponíveis localmente:

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

    • Como usar Save-Module para recuperar da Galeria do PowerShell:

      Save-Module -Name MyCustomModule -Path ./Modules

    • Como usar Save-PSResource do módulo PSResourceGet:

      Save-PSResource -Name MyCustomModule -Path ./Modules

Seu aplicativo de funções deve ter a seguinte estrutura:

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

Quando você inicia o aplicativo de funções, o trabalho de linguagem do PowerShell adiciona a pasta Modules a $env:PSModulePath para que você use o carregamento automático de módulo do mesmo jeito que faria em um script normal do PowerShell.

Solução de problemas de dependências gerenciadas

Como habilitar dependências gerenciadas

Para que as Dependências Gerenciadas funcionem, o recurso deve ser habilitado no host.json:

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

Versões específicas de destino

Ao direcionar versões específicas do módulo, é importante seguir as duas etapas a seguir para garantir que a versão correta do módulo seja carregada:

  1. : Especifique a versão de módulo em requirements.psd1:

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

  2. Adicione uma instrução de importação a profile.ps1:

    Import-Module Az.Accounts -RequiredVersion '1.9.5'

Seguir estas etapas garante que a versão especificada seja carregada quando sua função for iniciada.

Definir configurações específicas do intervalo de Dependência Gerenciada

Você pode configurar como as Dependências Gerenciadas são baixadas e instaladas usando as seguintes configurações de aplicativo:

Configuração Valor Padrão Descrição
MDMaxBackgroundUpgradePeriod 7.00:00:00 (sete dias) Controla o período de atualização em segundo plano para aplicativos de funções do PowerShell.
MDNewSnapshotCheckPeriod 01:00:00 (uma hora) Especifica a frequência com que o trabalho do PowerShell verifica se há atualizações.
MDMinBackgroundUpgradePeriod 1.00:00:00 (um dia) Tempo mínimo entre verificações de atualização.

Considerações sobre o gerenciamento de dependência

  • Acesso à Internet: as Dependências Gerenciadas exigem acesso ao https://www.powershellgallery.com para baixar módulos. Verifique se o ambiente permite esse acesso, incluindo a modificação de regras de firewall/VNet conforme necessário.
  • Aceitação da Licença: Dependências Gerenciadas não dá suporte a módulos que exigem aceitação da licença.
  • Plano de Consumo Flexível: o recurso de Dependências Gerenciadas não tem suporte no plano de Consumo Flexível. Em vez disso, use módulos personalizados.
  • Locais do Módulo: no computador local, os módulos geralmente são instalados em uma das pastas disponíveis globalmente no seu $env:PSModulePath. Ao ser executado no Azure, o $env:PSModulePath de um aplicativo de funções do PowerShell difere de $env:PSModulePath em um script regular do PowerShell e conterá a pasta Modules carregada com o conteúdo do aplicativo e um local separado gerenciado por Dependências Gerenciadas.

Variáveis de ambiente

Em funções, configurações do aplicativo, como conexão de serviço cadeias de caracteres, são expostas como variáveis de ambiente durante a execução. Acesse essas configurações usando $env:NAME_OF_ENV_VAR, conforme mostrado no exemplo seguinte:

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 configurações do aplicativo de funções:

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

Ao executar localmente, as configurações do aplicativo são lidos a partir de Settings arquivo de projeto.

Simultaneidade

Por padrão, o runtime das Funções do PowerShell só pode processar uma invocação de uma função por vez. No entanto, o nível de simultaneidade pode não ser suficiente nestas situações:

  • Quando você tenta lidar com muitas invocações ao mesmo tempo.
  • Quando você tem funções que invocam outras funções dentro do mesmo aplicativo de funções.

Existem alguns modelos de simultaneidade que você pode usar de acordo com o tipo de carga de trabalho:

  • Aumentar FUNCTIONS_WORKER_PROCESS_COUNT. O aumento dessa configuração permite processar invocações de função em vários processos com a mesma instância, o que gera certa sobrecarga de CPU e memória. Em geral, as funções associadas a E/S não são afetadas por essa sobrecarga. Para funções associadas à CPU, o impacto pode ser significativo.

  • Aumentar o valor PSWorkerInProcConcurrencyUpperBound de configuração do aplicativo. O aumento dessa configuração permite criar vários runspaces dentro do mesmo processo, o que reduz significativamente a sobrecarga de CPU e memória.

Defina essas variáveis de ambiente nas configurações do aplicativo de funções.

Dependendo do seu caso de uso, o Durable Functions pode aprimorar significativamente a escalabilidade. Para saber mais, confira Padrões de aplicativo do Durable Functions.

Observação

Talvez você receba avisos de "solicitações estão sendo colocadas na fila porque não há runspaces disponíveis". Isso não é um erro. A mensagem está informando que as solicitações estão sendo colocadas na fila e serão processadas 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 runspaces do PowerShell no mesmo processo. O número de runspaces criados e, portanto, o número de threads simultâneos por trabalho, é limitada pela configuração do aplicativo PSWorkerInProcConcurrencyUpperBound. Por padrão, o número de runspaces é definido como 1.000 na versão 4.x do runtime do Functions. Nas versões 3.x e inferiores, o número máximo de runspaces é definido como 1. A taxa de transferência do aplicativo de funções é afetada pela quantidade de CPU e memória disponíveis no plano selecionado.

O Azure PowerShell usa alguns contextos de nível de processo e um estado para ajudar você a evitar a digitação de excesso de tipos. No entanto, se você ativar a simultaneidade no aplicativo de funções e invocar ações que alteram o estado, poderá 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 alterou o estado.

Há um grande valor na simultaneidade com o Azure PowerShell, já que algumas operações podem levar um tempo considerável. No entanto, você deve continuar com cautela. Caso suspeite que está experimentando uma condição de corrida, defina a configuração de aplicativo PSWorkerInProcConcurrencyUpperBound como 1 e use o isolamento de nível do processo de trabalho de linguagem para simultaneidade.

Configurar a função scriptfile

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

A propriedade scriptFile em function.json pode ser usada para obter uma estrutura de pastas semelhante a este exemplo:

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

Nesse caso, o function.json de myFunction tem uma propriedade scriptFile 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

As funções do PowerShell neste artigo são exibidas no arquivo de script run.ps1 padrão gerado pelos modelos. No entanto, também é possível incluir suas funções nos módulos do PowerShell. É possível referenciar seu código de função específico no módulo usando os campos scriptFile e entryPoint no arquivo de configuração 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

Em que 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 de myFunction inclui uma propriedade scriptFile que faz referência a PSFunction.psm1, que é um módulo do PowerShell em outra pasta. A propriedade entryPoint faz referência à função Invoke-PSTestFunc, 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 run.ps1.

Considerações sobre as funções do PowerShell

Ao trabalhar com as funções do PowerShell, lembre-se das considerações nas seções a seguir.

Inicialização a frio

No desenvolvimento do Azure Functions no modelo de hospedagem sem servidor, as inicializações a frio são uma realidade. Inicialização a frio é o tempo que leva para um aplicativo de funções iniciar a execução para processar uma solicitação. Ela acontece com mais frequência no plano de consumo porque o aplicativo de funções é desligado durante períodos de inatividade.

Evite usar Install-Module

A execução de Install-Module em seu script de função em cada invocação pode causar problemas de desempenho. Em vez disso, use Save-Module ou Save-PSResource antes de publicar seu aplicativo de funções para agrupar os módulos necessários.

Para obter mais informações, consulte a seção Gerenciamento de Dependência.

Próximas etapas

Para saber mais, consulte os recursos a seguir: