Guida per sviluppatori PowerShell per Funzioni di Azure

Questo articolo fornisce informazioni dettagliate sul modo in cui si scrive Funzioni di Azure usando PowerShell.

Una funzione di Azure di PowerShell (funzione) è rappresentata come script di PowerShell che viene eseguito quando viene attivato. Ogni script di funzione ha un file correlato function.json che definisce il comportamento della funzione, ad esempio il modo in cui viene attivato e i relativi parametri di input e output. Per altre informazioni, vedere l'articolo Trigger e binding.

Come altri tipi di funzioni, le funzioni script di PowerShell accettano parametri che corrispondono ai nomi di tutte le associazioni di input definite nel function.json file. Viene passato anche un TriggerMetadata parametro che contiene informazioni aggiuntive sul trigger che ha avviato la funzione.

Questo articolo presuppone che siano già state lette le informazioni di riferimento per sviluppatori su Funzioni di Azure. È necessario anche completare l'avvio rapido funzioni per PowerShell per creare la prima funzione di PowerShell.

Struttura di cartelle

La struttura di cartelle necessaria per un progetto di PowerShell è simile alla seguente. Questa impostazione predefinita non può essere modificata. Per altre informazioni, vedere la sezione scriptFile di seguito.

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

Nella radice del progetto è disponibile un file condiviso host.json che può essere usato per configurare l'app per le funzioni. Ogni funzione ha una cartella con il proprio file di codice (.ps1) e il file di configurazione di associazione (function.json). Il nome della directory padre del file function.json è sempre il nome della funzione.

Alcune associazioni richiedono la presenza di un extensions.csproj file. Le estensioni di associazione, necessarie nella versione 2.x e versioni successive del runtime di Funzioni, sono definite nel extensions.csproj file, con i file di libreria effettivi nella bin cartella. Quando si sviluppa una funzione in locale, è necessario registrare le estensioni di associazione. Quando si sviluppano funzioni nel portale di Azure, la registrazione viene eseguita automaticamente.

In App per le funzioni di PowerShell, è possibile avere facoltativamente un profile.ps1 oggetto che viene eseguito quando un'app per le funzioni inizia a essere eseguita (in caso contrario, nota come avvio a freddo). Per altre informazioni, vedere Profilo di PowerShell.

Definizione di uno script di PowerShell come funzione

Per impostazione predefinita, il runtime di Funzioni cerca la funzione in run.ps1, dove run.ps1 condivide la stessa directory padre del file function.json corrispondente.

Lo script viene passato un numero di argomenti sull'esecuzione. Per gestire questi parametri, aggiungere un param blocco all'inizio dello script come nell'esempio seguente:

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

Parametro TriggerMetadata

Il TriggerMetadata parametro viene usato per fornire informazioni aggiuntive sul trigger. I metadati aggiuntivi variano dal binding all'associazione, ma contengono tutte una sys proprietà contenente i dati seguenti:

$TriggerMetadata.sys
Proprietà Descrizione Type
UtcNow Quando, in FORMATO UTC, la funzione è stata attivata Datetime
MethodName Nome della funzione attivata string
RandGuid guid univoco per questa esecuzione della funzione string

Ogni tipo di trigger ha un set diverso di metadati. Ad esempio, l'oggetto $TriggerMetadata per QueueTrigger contiene , InsertionTime, DequeueCountId, tra le altre cose. Per altre informazioni sui metadati del trigger della coda, passare alla documentazione ufficiale per i trigger di coda. Controllare la documentazione sui trigger con cui si sta lavorando per visualizzare le informazioni all'interno dei metadati del trigger.

Associazioni

In PowerShell le associazioni sono configurate e definite nella funzione.json di una funzione. Le funzioni interagiscono con le associazioni in molti modi.

Lettura dei dati di trigger e di input

I trigger e le associazioni di input vengono letti come parametri passati alla funzione. Le associazioni di input hanno un direction set su in in function.json. La name proprietà definita in function.json è il nome del parametro, nel param blocco. Poiché PowerShell usa parametri denominati per l'associazione, l'ordine dei parametri non è importante. Tuttavia, è consigliabile seguire l'ordine delle associazioni definite in function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Scrittura dei dati di output

In Funzioni un'associazione di output ha un direction set su out nella funzione.json. È possibile scrivere in un'associazione di output usando il cmdlet, disponibile per il Push-OutputBinding runtime di Funzioni. In tutti i casi, la name proprietà dell'associazione come definita in function.json corrisponde al Name parametro del Push-OutputBinding cmdlet.

Di seguito viene illustrato come chiamare Push-OutputBinding nello script della funzione:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

È anche possibile passare un valore per un'associazione specifica tramite la pipeline.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding si comporta in modo diverso in base al valore specificato per -Name:

  • Quando il nome specificato non può essere risolto in un'associazione di output valida, viene generato un errore.

  • Quando l'associazione di output accetta una raccolta di valori, è possibile chiamare Push-OutputBinding ripetutamente per eseguire il push di più valori.

  • Quando l'associazione di output accetta solo un valore singleton, la chiamata Push-OutputBinding a una seconda volta genera un errore.

sintassi Push-OutputBinding

Di seguito sono riportati parametri validi per la chiamata Push-OutputBinding:

Nome Tipo Posizione Descrizione
-Name string 1 Nome dell'associazione di output da impostare.
-Value Oggetto 2 Valore dell'associazione di output che si vuole impostare, che viene accettato dalla pipeline ByValue.
-Clobber SwitchParameter denominata (Facoltativo) Se specificato, forza l'impostazione del valore per un'associazione di output specificata.

Sono supportati anche i seguenti parametri comuni:

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

Per altre informazioni, vedere Informazioni su CommonParameters.

Push-OutputBinding esempio: risposte HTTP

Un trigger HTTP restituisce una risposta usando un'associazione di output denominata response. Nell'esempio seguente l'associazione di output di response ha il valore "output #1":

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

Poiché l'output è http, che accetta solo un valore singleton, viene generato un errore quando Push-OutputBinding viene chiamato una seconda volta.

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

Per gli output che accettano solo valori singleton, è possibile usare il parametro per eseguire l'override del -Clobber valore precedente anziché provare ad aggiungere a una raccolta. Nell'esempio seguente si presuppone che sia già stato aggiunto un valore. Usando -Clobber, la risposta dell'esempio seguente esegue l'override del valore esistente per restituire un valore di "output #3":

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

Push-OutputBinding esempio: Associazione di output della coda

Push-OutputBinding viene usato per inviare dati alle associazioni di output, ad esempio un'associazione di output dell'archiviazione code di Azure. Nell'esempio seguente il messaggio scritto nella coda ha un valore "output #1":

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

L'associazione di output per una coda di Archiviazione accetta più valori di output. In questo caso, chiamando l'esempio seguente dopo la prima scrittura nella coda un elenco con due elementi: "output #1" e "output #2".

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

L'esempio seguente, quando viene chiamato dopo i due precedenti, aggiunge due altri valori alla raccolta di output:

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

Quando scritto nella coda, il messaggio contiene questi quattro valori: "output #1", "output #2", "output #3" e "output #4".

cmdlet Get-OutputBinding

È possibile usare il Get-OutputBinding cmdlet per recuperare i valori attualmente impostati per le associazioni di output. Questo cmdlet recupera una tabella hash che contiene i nomi delle associazioni di output con i rispettivi valori.

Di seguito è riportato un esempio di uso Get-OutputBinding per restituire i valori di associazione correnti:

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

Get-OutputBinding contiene anche un parametro denominato -Name, che può essere usato per filtrare l'associazione restituita, come nell'esempio seguente:

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

I caratteri jolly (*) sono supportati in Get-OutputBinding.

Registrazione

La registrazione nelle funzioni di PowerShell funziona come la registrazione regolare di PowerShell. È possibile usare i cmdlet di registrazione per scrivere in ogni flusso di output. Ogni cmdlet esegue il mapping a un livello di log usato da Funzioni.

Livello di registrazione delle funzioni Cmdlet di registrazione
Errore Write-Error
Avviso Write-Warning
Informazioni Write-Information
Write-Host
Write-Output
Scrive nella registrazione a livello di informazioni .
Debug Write-Debug
Trace Write-Progress
Write-Verbose

Oltre a questi cmdlet, qualsiasi cosa scritta nella pipeline viene reindirizzata al Information livello di log e visualizzata con la formattazione predefinita di PowerShell.

Importante

L'uso dei Write-Verbose cmdlet o Write-Debug non è sufficiente per visualizzare la registrazione dettagliata e a livello di debug. È anche necessario configurare la soglia di livello di log, che dichiara il livello di log di cui si è effettivamente preoccupati. Per altre informazioni, vedere Configurare il livello di log dell'app per le funzioni.

Configurare il livello di log dell'app per le funzioni

Funzioni di Azure consente di definire il livello soglia per semplificare il controllo del modo in cui funzioni scrive nei log. Per impostare la soglia per tutte le tracce scritte nella console, usare la logging.logLevel.default proprietà nel host.json file. Questa impostazione si applica a tutte le funzioni dell'app per le funzioni.

Nell'esempio seguente viene impostata la soglia per abilitare la registrazione dettagliata per tutte le funzioni, ma imposta la soglia per abilitare la registrazione di debug per una funzione denominata MyFunction:

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

Per altre informazioni, vedere il riferimento su host.json.

Visualizzazione dei log

Se l'app per le funzioni è in esecuzione in Azure, è possibile usare l'applicazione Insights per monitorarla. Vedere Monitoraggio di Funzioni di Azure per altre informazioni sulla visualizzazione e sull'esecuzione di query su log di funzioni.

Se si esegue l'app per le funzioni in locale per lo sviluppo, i log vengono predefinito nel file system. Per visualizzare i log nella console, impostare la variabile di ambiente su Development prima di avviare l'app AZURE_FUNCTIONS_ENVIRONMENT per le funzioni.

Trigger e tipi di associazioni

Sono disponibili diversi trigger e associazioni da usare con l'app per le funzioni. L'elenco completo dei trigger e delle associazioni è disponibile qui.

Tutti i trigger e le associazioni sono rappresentati nel codice come alcuni tipi di dati reali:

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

I primi cinque tipi di questo elenco sono tipi .NET standard. Gli ultimi due vengono usati solo dal trigger HttpTrigger.

Ogni parametro di associazione nelle funzioni deve essere uno di questi tipi.

Trigger e associazioni HTTP

I trigger e i webhook HTTP e le associazioni di output HTTP usano oggetti di richiesta e risposta per rappresentare la messaggistica HTTP.

Oggetto della richiesta

L'oggetto request passato allo script è del tipo HttpRequestContext, che ha le proprietà seguenti:

Proprietà Descrizione Type
Body Oggetto che contiene il corpo della richiesta. Body viene serializzato nel tipo migliore in base ai dati. Ad esempio, se i dati sono JSON, vengono passati come tabella hash. Se i dati sono una stringa, viene passato come stringa. object
Headers Dizionario che contiene le intestazioni della richiesta. Dizionariostring<, stringa>*
Method Metodo HTTP della richiesta. string
Params Oggetto che contiene i parametri di routing della richiesta. Dizionariostring<, stringa>*
Query Oggetto che contiene i parametri di query della richiesta. Dizionariostring<, stringa>*
Url URL della richiesta. string

* Tutte le Dictionary<string,string> chiavi sono senza distinzione tra maiuscole e minuscole.

Oggetto della risposta

L'oggetto response che è necessario inviare è del tipo HttpResponseContext, che ha le proprietà seguenti:

Proprietà Descrizione Type
Body Oggetto che contiene il corpo della risposta. object
ContentType Breve mano per impostare il tipo di contenuto per la risposta. string
Headers Oggetto che contiene le intestazioni della risposta. Dizionario o Hashtable
StatusCode Codice di stato HTTP della risposta. stringa o numero intero

Accesso a richiesta e risposta

Quando si utilizzano trigger HTTP, è possibile accedere alla richiesta HTTP allo stesso modo con qualsiasi altra associazione di input. È nel param blocco.

Usare un HttpResponseContext oggetto per restituire una risposta, come illustrato nell'esempio seguente:

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!"
})

Il risultato di richiamare questa funzione sarebbe:

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

Cast di tipi per trigger e associazioni

Per determinate associazioni come l'associazione BLOB, è possibile specificare il tipo del parametro.

Ad esempio, per avere dati dall'archiviazione BLOB forniti come stringa, aggiungere il cast del tipo seguente al param blocco:

param([string] $myBlob)

Profilo di PowerShell

In PowerShell è presente il concetto di un profilo di PowerShell. Se non si ha familiarità con i profili di PowerShell, vedere Informazioni sui profili.

In Funzioni di PowerShell lo script del profilo viene eseguito una volta per ogni istanza del ruolo di lavoro di PowerShell nell'app quando viene prima distribuita e dopo essere inattiva (avvio a freddo). Quando la concorrenza è abilitata impostando il valore PSWorkerInProcConcurrencyUpperBound , lo script del profilo viene eseguito per ogni runspace creato.

Quando si crea un'app per le funzioni usando strumenti, ad esempio Visual Studio Code e Funzioni di Azure Core Tools, viene creato un valore predefinitoprofile.ps1. Il profilo predefinito viene mantenuto nel repository GitHub Strumenti di base e contiene:

  • Autenticazione automatica del servizio gestito in Azure.
  • Possibilità di attivare gli alias di PowerShell Azure PowerShell AzureRM se si desidera.

Versioni di PowerShell

La tabella seguente mostra le versioni di PowerShell disponibili per ogni versione principale del runtime di Funzioni e la versione .NET necessaria:

Versione di Funzioni Versione PowerShell Versione di .NET
3.x (scelta consigliata) PowerShell 7 (scelta consigliata)
PowerShell Core 6
.NET Core 3.1
.NET Core 2.1
2.x PowerShell Core 6 .NET Core 2.2

È possibile visualizzare la versione corrente stampando $PSVersionTable da qualsiasi funzione.

Per altre informazioni sui criteri di supporto di Funzioni di Azure runtime, vedere questo articolo

Esecuzione locale in una versione specifica

Quando si esegue localmente il runtime di Funzioni di Azure usa PowerShell Core 6. Per usare invece PowerShell 7 durante l'esecuzione in locale, è necessario aggiungere l'impostazione "FUNCTIONS_WORKER_RUNTIME_VERSION" : "~7" alla Values matrice nel file local.setting.json nella radice del progetto. Quando si esegue localmente in PowerShell 7, il file local.settings.json è simile all'esempio seguente:

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

Modifica della versione di PowerShell

L'app per le funzioni deve essere in esecuzione nella versione 3.x per poter eseguire l'aggiornamento da PowerShell Core 6 a PowerShell 7. Per informazioni su come eseguire questa operazione, vedere Visualizzare e aggiornare la versione di runtime corrente.

Usare la procedura seguente per modificare la versione di PowerShell usata dall'app per le funzioni. È possibile eseguire questa operazione nel portale di Azure o usando PowerShell.

  1. Nel portale di Azure passare all'app per le funzioni.

  2. In Impostazioni scegliere Configurazione. Nella scheda Impostazioni generali individuare la versione di PowerShell.

    Choose the PowerShell version used by the function app

  3. Scegliere la versione di PowerShell Core desiderata e selezionare Salva. Quando viene visualizzato un avviso relativo al riavvio in sospeso, scegliere Continua. L'app per le funzioni viene riavviata nella versione di PowerShell scelta.

L'app per le funzioni viene riavviata dopo aver apportato la modifica alla configurazione.

Gestione delle dipendenze

Funzioni consente di sfruttare PowerShell Gallery per la gestione delle dipendenze. Con la gestione delle dipendenze abilitata, il file requirements.psd1 viene usato per scaricare automaticamente i moduli necessari. Per abilitare questo comportamento, impostare la managedDependency proprietà su true nella radice del file host.json, come nell'esempio seguente:

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

Quando si crea un nuovo progetto di funzioni di PowerShell, la gestione delle dipendenze è abilitata per impostazione predefinita, con il modulo di Azure Az incluso. Il numero massimo di moduli attualmente supportati è 10. La sintassi supportata è MajorNumber.* o la versione esatta del modulo, come illustrato nell'esempio requirements.psd1 seguente:

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

Quando si aggiorna il file requirements.psd1, i moduli aggiornati vengono installati dopo un riavvio.

Versioni specifiche di destinazione

È possibile specificare come destinazione una versione specifica di un modulo nel file requirements.psd1. Ad esempio, se si vuole usare una versione precedente di Az.Accounts rispetto a quella nel modulo Az incluso, è necessario specificare come destinazione una versione specifica, come illustrato nell'esempio seguente:

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

In questo caso, è anche necessario aggiungere un'istruzione import all'inizio del file profile.ps1, simile all'esempio seguente:

Import-Module Az.Accounts -RequiredVersion '1.9.5'

In questo modo, la versione precedente del modulo Az.Account viene caricata per prima quando viene avviata la funzione.

Considerazioni sulla gestione delle dipendenze

Quando si usa la gestione delle dipendenze, si applicano le considerazioni seguenti:

  • Le dipendenze gestite richiedono l'accesso per https://www.powershellgallery.com scaricare i moduli. Durante l'esecuzione in locale, assicurarsi che il runtime possa accedere a questo URL aggiungendo le regole del firewall necessarie.

  • Le dipendenze gestite attualmente non supportano i moduli che richiedono all'utente di accettare una licenza, accettando la licenza in modo interattivo o fornendo -AcceptLicense il passaggio quando si richiama Install-Module.

Impostazioni dell'app di gestione delle dipendenze

Le impostazioni dell'applicazione seguenti possono essere usate per modificare la modalità di download e installazione delle dipendenze gestite.

Impostazione dell'app per le funzioni Valore predefinito Descrizione
MDMaxBackgroundUpgradePeriod 7.00:00:00 (sette giorni) Controlla il periodo di aggiornamento in background per le app per le funzioni di PowerShell. Per altre informazioni, vedere MDMaxBackgroundUpgradePeriod.
MDNewSnapshotCheckPeriod 01:00:00 (un'ora) Specifica la frequenza con cui ogni ruolo di lavoro di PowerShell controlla se sono stati installati gli aggiornamenti delle dipendenze gestite. Per altre informazioni, vedere MDNewSnapshotCheckPeriod.
MDMinBackgroundUpgradePeriod 1.00:00:00 (un giorno) Periodo di tempo dopo un controllo dell'aggiornamento precedente prima dell'avvio di un altro controllo di aggiornamento. Per altre informazioni, vedere MDMinBackgroundUpgradePeriod.

Essenzialmente, l'aggiornamento dell'app viene avviato all'interno di e il processo di aggiornamento viene completato all'interno MDMaxBackgroundUpgradePerioddi circa .MDNewSnapshotCheckPeriod

Moduli personalizzati

L'uso di moduli personalizzati in Funzioni di Azure differisce da come si farebbe normalmente per PowerShell.

Nel computer locale, il modulo viene installato in una delle cartelle disponibili a livello globale in $env:PSModulePath. Quando si esegue in Azure, non si ha accesso ai moduli installati nel computer. Ciò significa che per $env:PSModulePath un'app per le funzioni di PowerShell è diverso da $env:PSModulePath uno script di PowerShell normale.

In Funzioni PSModulePath contiene due percorsi:

  • Modules Cartella presente nella radice dell'app per le funzioni.
  • Percorso di una Modules cartella controllata dal ruolo di lavoro linguistico di PowerShell.

Cartella moduli a livello di app per le funzioni

Per usare moduli personalizzati, è possibile inserire moduli da cui dipendono le funzioni in una Modules cartella. Da questa cartella i moduli sono automaticamente disponibili per il runtime delle funzioni. Qualsiasi funzione nell'app per le funzioni può usare questi moduli.

Nota

I moduli specificati nel file requirements.psd1 vengono scaricati automaticamente e inclusi nel percorso, quindi non è necessario includerli nella cartella modules. Questi vengono archiviati in locale nella $env:LOCALAPPDATA/AzureFunctions cartella e nella /data/ManagedDependencies cartella quando vengono eseguiti nel cloud.

Per sfruttare la funzionalità del modulo personalizzato, creare una Modules cartella nella radice dell'app per le funzioni. Copiare i moduli da usare nelle funzioni in questa posizione.

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

Con una Modules cartella, l'app per le funzioni deve avere la struttura di cartelle seguente:

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

Quando si avvia l'app per le funzioni, il ruolo di lavoro del linguaggio di PowerShell aggiunge questa Modules cartella a $env:PSModulePath in modo che sia possibile basarsi sul caricamento automatico del modulo esattamente come si farebbe con uno script di PowerShell normale.

Cartella moduli a livello di ruolo di lavoro del linguaggio

Diversi moduli vengono comunemente usati dal ruolo di lavoro del linguaggio di PowerShell. Questi moduli sono definiti nell'ultima posizione di PSModulePath.

L'elenco corrente dei moduli è il seguente:

  • Microsoft.PowerShell.Archive: modulo usato per l'uso di archivi, ad esempio .zip, .nupkge altri.
  • ThreadJob: implementazione basata su thread delle API del processo di PowerShell.

Per impostazione predefinita, Funzioni usa la versione più recente di questi moduli. Per usare una versione specifica del modulo, inserire tale versione specifica nella cartella dell'app per le Modules funzioni.

Variabili di ambiente

In Funzioni, le impostazioni dell'app, come le stringhe di connessione al servizio, vengono esposte come variabili di ambiente durante l'esecuzione. È possibile accedere a queste impostazioni usando $env:NAME_OF_ENV_VAR, come illustrato nell'esempio seguente:

param($myTimer)

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

Esistono diversi modi per aggiungere, aggiornare ed eliminare le impostazioni dell'app per le funzioni:

Le modifiche apportate alle impostazioni dell'app per le funzioni richiedono il riavvio dell'app per le funzioni.

Per l'esecuzione in locale, le impostazioni dell'app vengono lette dal file di progetto local.settings.json.

Concorrenza

Per impostazione predefinita, il runtime di PowerShell di Funzioni può elaborare una sola chiamata di una funzione alla volta. Tuttavia, questo livello di concorrenza potrebbe non essere sufficiente nelle situazioni seguenti:

  • Quando si sta tentando di gestire un numero elevato di chiamate contemporaneamente.
  • Quando si dispone di funzioni che richiamano altre funzioni all'interno della stessa app per le funzioni.

Esistono alcuni modelli di concorrenza che è possibile esplorare a seconda del tipo di carico di lavoro:

  • Aumentare FUNCTIONS_WORKER_PROCESS_COUNT. Ciò consente di gestire le chiamate delle funzioni in più processi all'interno della stessa istanza, che introduce un determinato sovraccarico della CPU e della memoria. In generale, le funzioni associate a I/O non soffriranno di questo sovraccarico. Per le funzioni associate alla CPU, l'impatto potrebbe essere significativo.

  • Aumentare il valore dell'impostazione dell'app PSWorkerInProcConcurrencyUpperBound . Ciò consente di creare più runspace all'interno dello stesso processo, che riduce significativamente il sovraccarico della CPU e della memoria.

Queste variabili di ambiente vengono impostate nelle impostazioni dell'app dell'app .

A seconda del caso d'uso, Durable Functions può migliorare significativamente la scalabilità. Per altre informazioni, vedere modelli di applicazione Durable Functions.

Nota

È possibile che le "richieste vengano accodate a causa di avvisi di runspace non disponibili", si noti che non si tratta di un errore. Il messaggio indica che le richieste vengono accodate e verranno gestite al termine delle richieste precedenti.

Considerazioni sull'uso della concorrenza

PowerShell è un singolo linguaggio di scripting threading per impostazione predefinita. È tuttavia possibile aggiungere concorrenza usando più runspace di PowerShell nello stesso processo. La quantità di runspace creati e quindi il numero di thread simultanei per ogni ruolo di lavoro è limitato dall'impostazione dell'applicazione PSWorkerInProcConcurrencyUpperBound . Per impostazione predefinita, il numero di runspace è impostato su 1.000 nella versione 4.x del runtime di Funzioni. Nelle versioni 3.x e successive il numero massimo di runspace è impostato su 1. La velocità effettiva sarà influenzata dalla quantità di CPU e memoria disponibile nel piano selezionato.

Azure PowerShell usa alcuni contesti a livello di processo e stato per salvare l'utente dalla digitazione in eccesso. Tuttavia, se si attiva la concorrenza nell'app per le funzioni e si richiamano azioni che cambiano stato, è possibile terminare con condizioni di gara. Queste condizioni di gara sono difficili da eseguire perché una chiamata si basa su uno stato specifico e l'altra chiamata ha modificato lo stato.

C'è un enorme valore nella concorrenza con Azure PowerShell, poiché alcune operazioni possono richiedere un notevole tempo. Tuttavia, è necessario procedere con cautela. Se si sospetta che si verifichi una condizione di gara, impostare l'impostazione dell'app PSWorkerInProcConcurrencyUpperBound su 1 e usare invece l'isolamento del livello di processo di lavoro del linguaggio per la concorrenza.

Configurare script di funzioneFile

Per impostazione predefinita, una funzione di PowerShell viene eseguita da run.ps1, un file che condivide la stessa directory padre del corrispondente function.json.

La scriptFile proprietà in può essere usata per ottenere una struttura di cartelle simile all'esempio function.json seguente:

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

In questo caso, l'oggetto function.json for myFunction include una scriptFile proprietà che fa riferimento al file con la funzione esportata da eseguire.

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

Usare i moduli di PowerShell configurando un entryPoint

Questo articolo ha illustrato le funzioni di PowerShell nel file di script predefinito run.ps1 generato dai modelli. Tuttavia, è anche possibile includere le funzioni nei moduli di PowerShell. È possibile fare riferimento al codice di funzione specifico nel modulo usando i scriptFile campi e entryPoint nel file di configurazione function.json.

In questo caso, entryPoint è il nome di una funzione o di un cmdlet nel modulo di PowerShell a cui si fa riferimento in scriptFile.

Prendere in considerazione la struttura di cartelle seguente:

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

Dove PSFunction.psm1 contiene:

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

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

Export-ModuleMember -Function "Invoke-PSTestFunc"

In questo esempio la configurazione per myFunction include una proprietà che fa riferimento PSFunction.psm1a , ovvero un scriptFile modulo di PowerShell in un'altra cartella. La entryPoint proprietà fa riferimento alla Invoke-PSTestFunc funzione, ovvero il punto di ingresso nel modulo.

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

Con questa configurazione, l'oggetto Invoke-PSTestFunc viene eseguito esattamente come run.ps1 sarebbe.

Considerazioni sulle funzioni di PowerShell

Quando si utilizzano le funzioni di PowerShell, tenere presente le considerazioni riportate nelle sezioni seguenti.

Avvio a freddo

Quando si sviluppa Funzioni di Azure nel modello di hosting serverless, l'avvio a freddo è una realtà. L'inizio a freddo fa riferimento a un periodo di tempo necessario per avviare l'esecuzione dell'app per le funzioni per elaborare una richiesta. L'avvio a freddo si verifica più frequentemente nel piano di consumo perché l'app per le funzioni viene arrestata durante periodi di inattività.

Moduli di bundle anziché usare Install-Module

Lo script viene eseguito in ogni chiamata. Evitare di usare Install-Module nello script. Usare invece Save-Module prima della pubblicazione in modo che la funzione non deve perdere tempo per scaricare il modulo. Se l'avvio a freddo influisce sulle funzioni, valutare la possibilità di distribuire l'app per le funzioni in un piano di servizio app impostato su sempre o su un piano di Premium.

Passaggi successivi

Per altre informazioni, vedere le seguenti risorse: