Przewodnik dla deweloperów usługi Azure Functions pracujących w programie PowerShell

Artykuł
03/09/2023

Ten artykuł zawiera szczegółowe informacje o sposobie pisania Azure Functions przy użyciu programu PowerShell.

Funkcja (funkcja) platformy Azure programu PowerShell jest reprezentowana jako skrypt programu PowerShell, który jest wykonywany po wyzwoleniu. Każdy skrypt funkcji ma powiązany function.json plik, który definiuje, jak działa funkcja, na przykład sposób jego wyzwalania oraz jego parametrów wejściowych i wyjściowych. Aby dowiedzieć się więcej, zobacz artykuł Wyzwalacze i powiązanie.

Podobnie jak w przypadku innych rodzajów funkcji, funkcje skryptów programu PowerShell przyjmują parametry zgodne z nazwami wszystkich powiązań wejściowych zdefiniowanych w function.json pliku. Przekazano TriggerMetadata również parametr zawierający dodatkowe informacje na temat wyzwalacza, który uruchomił funkcję.

W tym artykule przyjęto założenie, że znasz już dokumentację dla deweloperów Azure Functions. Aby utworzyć pierwszą funkcję programu PowerShell, należy również ukończyć przewodnik Szybki start usługi Functions .

Struktura folderów

Wymagana struktura folderów dla projektu programu PowerShell wygląda następująco. Tę wartość domyślną można zmienić. Aby uzyskać więcej informacji, zobacz sekcję scriptFile poniżej.

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

W katalogu głównym projektu znajduje się udostępniony host.json plik, który może służyć do konfigurowania aplikacji funkcji. Każda funkcja ma folder z własnym plikiem kodu (.ps1) i plikiem konfiguracji powiązania (function.json). Nazwa katalogu nadrzędnego pliku function.json jest zawsze nazwą funkcji.

Niektóre powiązania wymagają obecności extensions.csproj pliku. Rozszerzenia powiązań wymagane w wersji 2.x i nowszych wersjach środowiska uruchomieniowego usługi Functions są definiowane w extensions.csproj pliku z rzeczywistymi plikami biblioteki w folderze bin . Podczas tworzenia aplikacji lokalnie należy zarejestrować rozszerzenia powiązań. Podczas tworzenia funkcji w Azure Portal ta rejestracja jest wykonywana.

W aplikacjach funkcji programu PowerShell możesz opcjonalnie mieć funkcję uruchamianą profile.ps1 po uruchomieniu aplikacji funkcji (w przeciwnym razie jako zimny start). Aby uzyskać więcej informacji, zobacz Profil programu PowerShell.

Definiowanie skryptu programu PowerShell jako funkcji

Domyślnie środowisko uruchomieniowe usługi Functions wyszukuje funkcję w run.ps1programie , gdzie run.ps1 udostępnia ten sam katalog nadrzędny co odpowiadający mu element function.json.

Skrypt jest przekazywany z wieloma argumentami wykonywania. Aby obsłużyć te parametry, dodaj param blok do góry skryptu, jak w poniższym przykładzie:

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

TriggerMetadata, parametr

Parametr służy do podawania TriggerMetadata dodatkowych informacji o wyzwalaczu. Dodatkowe metadane różnią się od powiązania do powiązania, ale wszystkie zawierają właściwość zawierającą sys następujące dane:

$TriggerMetadata.sys

Właściwość	Opis	Typ
Utcnow	Kiedy w formacie UTC funkcja została wyzwolona	DateTime
Methodname	Nazwa funkcji, która została wyzwolona	ciąg
RandGuid	unikatowy identyfikator GUID do wykonania funkcji	ciąg

Każdy typ wyzwalacza ma inny zestaw metadanych. Na przykład element $TriggerMetadata for QueueTrigger zawiera InsertionTimeelement , Id, DequeueCount, między innymi. Aby uzyskać więcej informacji na temat metadanych wyzwalacza kolejki, przejdź do oficjalnej dokumentacji wyzwalaczy kolejki. Zapoznaj się z dokumentacją wyzwalaczy, z którymi pracujesz, aby zobaczyć, co znajduje się wewnątrz metadanych wyzwalacza.

Powiązania

W programie PowerShell powiązania są konfigurowane i definiowane w pliku function.json funkcji. Funkcje współdziałają z powiązaniami na wiele sposobów.

Odczytywanie wyzwalacza i danych wejściowych

Powiązania wyzwalacza i wejściowe są odczytywane jako parametry przekazywane do funkcji. Powiązania wejściowe mają ustawioną direction wartość in w pliku function.json. Właściwość zdefiniowana name w pliku function.json jest nazwą parametru param w bloku. Ponieważ program PowerShell używa nazwanych parametrów do powiązania, kolejność parametrów nie ma znaczenia. Najlepszym rozwiązaniem jest jednak wykonanie kolejności powiązań zdefiniowanych w elemecie function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Zapisywanie danych wyjściowych

W usłudze Functions powiązanie danych wyjściowych ma ustawioną direction wartość out w pliku function.json. Możesz napisać do powiązania wyjściowego przy użyciu Push-OutputBinding polecenia cmdlet, które jest dostępne dla środowiska uruchomieniowego usługi Functions. We wszystkich przypadkach name właściwość powiązania zgodnie z definicją Name w function.json metodzie odpowiada parametrowi Push-OutputBinding polecenia cmdlet.

Poniżej przedstawiono sposób wywoływania Push-OutputBinding skryptu funkcji:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

Można również przekazać wartość dla określonego powiązania za pośrednictwem potoku.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding zachowuje się inaczej na podstawie wartości określonej dla -Nameelementu :

Gdy nie można rozpoznać określonej nazwy do prawidłowego powiązania wyjściowego, zostanie zgłoszony błąd.
Gdy powiązanie wyjściowe akceptuje kolekcję wartości, można wywołać Push-OutputBinding wielokrotnie, aby wypchnąć wiele wartości.
Gdy powiązanie wyjściowe akceptuje tylko pojedynczą wartość, wywołanie Push-OutputBinding po raz drugi powoduje wystąpienie błędu.

składnia Push-OutputBinding

Poniżej przedstawiono prawidłowe parametry wywoływania elementu Push-OutputBinding:

Nazwa	Typ	Położenie	Opis
`-Name`	Ciąg	1	Nazwa powiązania wyjściowego, które chcesz ustawić.
`-Value`	Obiekt	2	Wartość powiązania wyjściowego, które chcesz ustawić, które jest akceptowane z potoku ByValue.
`-Clobber`	SwitchParameter	O nazwie	(Opcjonalnie) Po określeniu wymusza ustawienie wartości dla określonego powiązania wyjściowego.

Obsługiwane są również następujące typowe parametry:

Verbose
Debug
ErrorAction
ErrorVariable
WarningAction
WarningVariable
OutBuffer
PipelineVariable
OutVariable

Aby uzyskać więcej informacji, zobacz About CommonParameters (Informacje o parametrach CommonParameters).

Push-OutputBinding przykład: odpowiedzi HTTP

Wyzwalacz HTTP zwraca odpowiedź przy użyciu powiązania wyjściowego o nazwie response. W poniższym przykładzie powiązanie wyjściowe elementu response ma wartość "output #1":

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

Ponieważ dane wyjściowe to HTTP, która akceptuje tylko pojedynczą wartość, błąd jest zgłaszany, gdy Push-OutputBinding jest wywoływany po raz drugi.

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

W przypadku danych wyjściowych, które akceptują tylko pojedyncze wartości, można użyć parametru -Clobber , aby zastąpić starą wartość zamiast próby dodania do kolekcji. W poniższym przykładzie założono, że dodano już wartość. Za pomocą polecenia -Clobberodpowiedź z następującego przykładu zastępuje istniejącą wartość, aby zwrócić wartość "output #3":

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

Push-OutputBinding przykład: Powiązanie danych wyjściowych kolejki

Push-OutputBinding służy do wysyłania danych do powiązań wyjściowych, takich jak powiązanie wyjściowe usługi Azure Queue Storage. W poniższym przykładzie komunikat zapisany w kolejce ma wartość "output #1":

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

Powiązanie wyjściowe kolejki usługi Storage akceptuje wiele wartości wyjściowych. W takim przypadku wywołanie następującego przykładu po pierwszym zapisie w kolejce listy z dwoma elementami: "output #1" i "output #2".

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

Poniższy przykład, po wywołaniu po dwóch poprzednich, dodaje dwie kolejne wartości do kolekcji danych wyjściowych:

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

Podczas zapisywania w kolejce komunikat zawiera następujące cztery wartości: "output #1", "output #2", "output #3" i "output #4".

polecenie cmdlet Get-OutputBinding

Możesz użyć Get-OutputBinding polecenia cmdlet , aby pobrać wartości aktualnie ustawione dla powiązań wyjściowych. To polecenie cmdlet pobiera tabelę skrótu zawierającą nazwy powiązań wyjściowych z odpowiednimi wartościami.

Poniżej przedstawiono przykład użycia funkcji Get-OutputBinding do zwracania bieżących wartości powiązań:

Get-OutputBinding

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

Get-OutputBinding Zawiera również parametr o nazwie -Name, który może służyć do filtrowania zwracanego powiązania, jak w poniższym przykładzie:

Get-OutputBinding -Name MyQ*

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

Symbole wieloznaczne (*) są obsługiwane w systemie Get-OutputBinding.

Rejestrowanie

Rejestrowanie w funkcjach programu PowerShell działa jak zwykłe rejestrowanie programu PowerShell. Polecenia cmdlet rejestrowania umożliwiają zapisywanie w każdym strumieniu wyjściowym. Każde polecenie cmdlet mapuje na poziom dziennika używany przez funkcje.

Poziom rejestrowania funkcji	Polecenie cmdlet rejestrowania
Błąd	`Write-Error`
Ostrzeżenie	`Write-Warning`
Informacje	`Write-Information` `Write-Host` `Write-Output` Zapisuje na `Information` poziomie dziennika.
Debugowanie	`Write-Debug`
Ślad	`Write-Progress` `Write-Verbose`

Oprócz tych poleceń cmdlet wszystkie elementy zapisywane w potoku są przekierowywane do Information poziomu dziennika i wyświetlane przy użyciu domyślnego formatowania programu PowerShell.

Ważne

Write-Verbose Użycie poleceń cmdlet lub Write-Debug nie wystarczy, aby wyświetlić pełne i debugowanie rejestrowania na poziomie. Należy również skonfigurować próg poziomu dziennika, który deklaruje, jaki poziom dzienników jest rzeczywiście potrzebny. Aby dowiedzieć się więcej, zobacz Konfigurowanie poziomu dziennika aplikacji funkcji.

Konfigurowanie poziomu dziennika aplikacji funkcji

Azure Functions umożliwia zdefiniowanie poziomu progu w celu ułatwienia kontrolowania sposobu zapisywania w dziennikach funkcji. Aby ustawić próg dla wszystkich śladów zapisanych w konsoli, użyj logging.logLevel.default właściwości w host.json pliku. To ustawienie dotyczy wszystkich funkcji w aplikacji funkcji.

Poniższy przykład ustawia próg, aby włączyć pełne rejestrowanie dla wszystkich funkcji, ale ustawia próg, aby włączyć rejestrowanie debugowania dla funkcji o nazwie MyFunction:

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

Aby uzyskać więcej informacji, zobacz dokumentacja pliku host.json.

Wyświetlanie dzienników

Jeśli aplikacja funkcji jest uruchomiona na platformie Azure, możesz użyć usługi Application Insights, aby ją monitorować. Przeczytaj Azure Functions monitorowania, aby dowiedzieć się więcej na temat wyświetlania i wykonywania zapytań dotyczących dzienników funkcji.

Jeśli aplikacja funkcji jest uruchamiana lokalnie na potrzeby programowania, dzienniki są domyślne dla systemu plików. Aby wyświetlić dzienniki w konsoli, ustaw zmienną AZURE_FUNCTIONS_ENVIRONMENT środowiskową na wartość Development przed uruchomieniem aplikacji funkcji.

Typy wyzwalaczy i powiązań

Dostępnych jest wiele wyzwalaczy i powiązań do użycia z aplikacją funkcji. Pełną listę wyzwalaczy i powiązań można znaleźć tutaj.

Wszystkie wyzwalacze i powiązania są reprezentowane w kodzie jako kilka rzeczywistych typów danych:

Hashtable
ciąg
bajt[]
int
double
HttpRequestContext
HttpResponseContext

Pierwsze pięć typów na tej liście to standardowe typy platformy .NET. Ostatnie dwa są używane tylko przez wyzwalacz HttpTrigger.

Każdy parametr powiązania w funkcjach musi być jednym z tych typów.

Wyzwalacze i powiązania HTTP

Wyzwalacze HTTP i element webhook oraz powiązania wyjściowe HTTP używają obiektów żądań i odpowiedzi do reprezentowania komunikatów HTTP.

Obiekt żądania

Obiekt żądania przekazany do skryptu jest typu HttpRequestContext, który ma następujące właściwości:

Właściwość	Opis	Typ
`Body`	Obiekt zawierający treść żądania. `Body` jest serializowany do najlepszego typu na podstawie danych. Jeśli na przykład dane są w formacie JSON, są przekazywane jako tabela skrótu. Jeśli dane są ciągiem, są przekazywane jako ciąg.	object
`Headers`	Słownik zawierający nagłówki żądania.	Ciąg słownika<, ciąg>^*
`Method`	Metoda HTTP żądania.	ciąg
`Params`	Obiekt zawierający parametry routingu żądania.	Ciąg słownika<, ciąg>^*
`Query`	Obiekt zawierający parametry zapytania.	Ciąg słownika<, ciąg>^*
`Url`	Adres URL żądania.	ciąg

^* Wszystkie Dictionary<string,string> klucze są bez uwzględniania wielkości liter.

Obiekt odpowiedzi

Obiekt odpowiedzi, który należy wysłać z powrotem, jest typu HttpResponseContext, który ma następujące właściwości:

Właściwość	Opis	Typ
`Body`	Obiekt zawierający treść odpowiedzi.	object
`ContentType`	Krótka ręka ustawiania typu zawartości dla odpowiedzi.	ciąg
`Headers`	Obiekt zawierający nagłówki odpowiedzi.	Słownik lub tabela skrótów
`StatusCode`	Kod stanu HTTP odpowiedzi.	ciąg lub int

Uzyskiwanie dostępu do żądania i odpowiedzi

Podczas pracy z wyzwalaczami HTTP można uzyskać dostęp do żądania HTTP w taki sam sposób, jak w przypadku dowolnego innego powiązania wejściowego. Znajduje się w param bloku.

HttpResponseContext Użyj obiektu, aby zwrócić odpowiedź, jak pokazano poniżej:

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

Wynikiem wywołania tej funkcji będzie:

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

Rzutowanie typów dla wyzwalaczy i powiązań

W przypadku niektórych powiązań, takich jak powiązanie obiektu blob, można określić typ parametru.

Aby na przykład mieć dane z usługi Blob Storage dostarczone jako ciąg, dodaj następujący typ rzutowania do mojego param bloku:

param([string] $myBlob)

Profil programu PowerShell

W programie PowerShell istnieje koncepcja profilu programu PowerShell. Jeśli nie znasz profilów programu PowerShell, zobacz Informacje o profilach.

W usłudze PowerShell Functions skrypt profilu jest wykonywany raz dla wystąpienia procesu roboczego programu PowerShell w aplikacji po pierwszym wdrożeniu i po bezczynności (zimny start). Po włączeniu współbieżności przez ustawienie wartości PSWorkerInProcConcurrencyUpperBound skrypt profilu jest uruchamiany dla każdego utworzonego obszaru runspace.

Podczas tworzenia aplikacji funkcji przy użyciu narzędzi, takich jak Visual Studio Code i Azure Functions Core Tools, zostanie utworzone ustawienie domyślneprofile.ps1. Profil domyślny jest utrzymywany w repozytorium GitHub narzędzi Core Tools i zawiera następujące elementy:

Automatyczne uwierzytelnianie MSI na platformie Azure.
Jeśli chcesz, możesz włączyć aliasy programu PowerShell Azure PowerShellAzureRM.

Wersje programu PowerShell

W poniższej tabeli przedstawiono wersje programu PowerShell dostępne dla każdej głównej wersji środowiska uruchomieniowego usługi Functions oraz wymaganą wersję platformy .NET:

Wersja usługi Functions	Wersja programu PowerShell	Wersja platformy .NET
4.x	PowerShell 7.2	.NET 6

Bieżącą wersję można wyświetlić, drukując $PSVersionTable z dowolnej funkcji.

Aby dowiedzieć się więcej na temat zasad obsługi środowiska uruchomieniowego Azure Functions, zapoznaj się z tym artykułem

Uruchamianie lokalne w określonej wersji

Obsługa programu PowerShell 7.0 w Azure Functions została zakończona 3 grudnia 2022 r. Aby użyć programu PowerShell 7.2 podczas uruchamiania lokalnego, należy dodać ustawienie "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.2" do Values tablicy w pliku local.setting.json w katalogu głównym projektu. W przypadku uruchamiania lokalnego w programie PowerShell 7.2 plik local.settings.json wygląda następująco:

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

Uwaga

W usłudze PowerShell Functions wartość "~7" dla FUNCTIONS_WORKER_RUNTIME_VERSION odnosi się do "7.0.x". Nie uaktualniamy automatycznie aplikacji funkcji programu PowerShell, które mają wartość "~7" do "7.2". W przyszłości w przypadku aplikacji funkcji programu PowerShell będziemy wymagać, aby aplikacje określały zarówno wersję główną, jak i pomocniczą, którą mają być docelowe. W związku z tym należy wspomnieć "7.2", jeśli chcesz kierować wartość docelową "7.2.x"

Zmienianie wersji programu PowerShell

Obsługa programu PowerShell 7.0 w Azure Functions została zakończona 3 grudnia 2022 r. Aby uaktualnić aplikację funkcji do programu PowerShell 7.2, upewnij się, że wartość FUNCTIONS_EXTENSION_VERSION jest ustawiona na ~4. Aby dowiedzieć się, jak to zrobić, zobacz Wyświetlanie i aktualizowanie bieżącej wersji środowiska uruchomieniowego.

Wykonaj następujące kroki, aby zmienić wersję programu PowerShell używaną przez aplikację funkcji. Można to zrobić w Azure Portal lub przy użyciu programu PowerShell.

Portal
Program PowerShell

W witrynie Azure Portal przejdź do swojej aplikacji funkcji.
W obszarze Ustawienia wybierz pozycję Konfiguracja. Na karcie Ustawienia ogólne znajdź wersję programu PowerShell.
Wybierz żądaną wersję programu PowerShell Core i wybierz pozycję Zapisz. Po ostrzeżeniu o oczekującym ponownym uruchomieniu wybierz pozycję Kontynuuj. Aplikacja funkcji jest uruchamiana ponownie w wybranej wersji programu PowerShell.

Uruchom następujący skrypt, aby zmienić wersję programu PowerShell:

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

Zastąp <SUBSCRIPTION_ID>wartości , <RESOURCE_GROUP>i <FUNCTION_APP> identyfikatorem subskrypcji platformy Azure, odpowiednio nazwą grupy zasobów i aplikacji funkcji. Zastąp również ciąg <VERSION> .7.2 Możesz sprawdzić zaktualizowaną wartość powerShellVersion ustawienia w Properties zwracanej tabeli skrótów.

Aplikacja funkcji jest uruchamiana ponownie po wprowadzeniu zmiany w konfiguracji.

Zarządzanie zależnościami

Usługa Functions umożliwia korzystanie z galerii programu PowerShell do zarządzania zależnościami. Po włączeniu zarządzania zależnościami plik requirements.psd1 jest używany do automatycznego pobierania wymaganych modułów. To zachowanie można włączyć, ustawiając managedDependency właściwość na true w katalogu głównym pliku host.json, tak jak w poniższym przykładzie:

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

Podczas tworzenia nowego projektu funkcji programu PowerShell zarządzanie zależnościami jest domyślnie włączone z dołączonym modułem platformy AzureAz. Maksymalna liczba aktualnie obsługiwanych modułów to 10. Obsługiwana składnia to MajorNumber.* lub dokładna wersja modułu, jak pokazano w poniższym przykładzie requirements.psd1:

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

Po zaktualizowaniu pliku requirements.psd1 zaktualizowane moduły są instalowane po ponownym uruchomieniu.

Docelowe wersje

W pliku requirements.psd1 możesz wybrać określoną wersję modułu. Jeśli na przykład chcesz użyć starszej wersji modułu Az.Accounts niż w dołączonym module Az, musisz określić określoną wersję, jak pokazano w poniższym przykładzie:

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

W takim przypadku należy również dodać instrukcję import do góry pliku profile.ps1, który wygląda podobnie do następującego przykładu:

Import-Module Az.Accounts -RequiredVersion '1.9.5'

W ten sposób starsza wersja modułu Az.Account jest ładowana jako pierwsza po uruchomieniu funkcji.

Zagadnienia dotyczące zarządzania zależnościami

Podczas korzystania z zarządzania zależnościami należy wziąć pod uwagę następujące kwestie:

Zależności zarządzane wymagają dostępu do https://www.powershellgallery.com pobierania modułów. Podczas uruchamiania lokalnego upewnij się, że środowisko uruchomieniowe może uzyskać dostęp do tego adresu URL, dodając wszystkie wymagane reguły zapory.
Obecnie zarządzane zależności nie obsługują modułów, które wymagają od użytkownika zaakceptowania licencji przez zaakceptowanie licencji interakcyjnej lub udostępnienie -AcceptLicense przełącznika podczas wywoływania Install-Module.

Ustawienia aplikacji do zarządzania zależnościami

Następujące ustawienia aplikacji mogą służyć do zmiany sposobu pobierania i instalowania zarządzanych zależności.

Ustawienie aplikacji funkcji	Wartość domyślna	Opis
MDMaxBackgroundUpgradePeriod	`7.00:00:00` (siedem dni)	Określa okres aktualizacji w tle dla aplikacji funkcji programu PowerShell. Aby dowiedzieć się więcej, zobacz MDMaxBackgroundUpgradePeriod.
MDNewSnapshotCheckPeriod	`01:00:00` (jedna godzina)	Określa, jak często każdy proces roboczy programu PowerShell sprawdza, czy zainstalowano uaktualnienia zależności zarządzanych. Aby dowiedzieć się więcej, zobacz MDNewSnapshotCheckPeriod.
MDMinBackgroundUpgradePeriod	`1.00:00:00` (jeden dzień)	Okres czasu po wcześniejszym sprawdzeniu uaktualnienia przed rozpoczęciem innego sprawdzania uaktualnienia. Aby dowiedzieć się więcej, zobacz MDMinBackgroundUpgradePeriod.

Zasadniczo uaktualnienie aplikacji rozpoczyna się w programie MDMaxBackgroundUpgradePeriod, a proces uaktualniania zakończy się w przybliżeniu w obrębie MDNewSnapshotCheckPeriod.

Moduły niestandardowe

Korzystanie z własnych modułów niestandardowych w Azure Functions różni się od tego, jak zwykle można to zrobić w programie PowerShell.

Na komputerze lokalnym moduł jest instalowany w jednym z folderów dostępnych globalnie w programie $env:PSModulePath. Podczas uruchamiania na platformie Azure nie masz dostępu do modułów zainstalowanych na maszynie. Oznacza to, że $env:PSModulePath aplikacja funkcji programu PowerShell różni się od $env:PSModulePath zwykłego skryptu programu PowerShell.

W obszarze PSModulePath Funkcje znajdują się dwie ścieżki:

Modules Folder, który istnieje w katalogu głównym aplikacji funkcji.
Ścieżka do folderu kontrolowanego Modules przez proces roboczy języka programu PowerShell.

Folder modułów na poziomie aplikacji funkcji

Aby użyć modułów niestandardowych, możesz umieścić moduły, na których zależą funkcje w folderze Modules . W tym folderze moduły są automatycznie dostępne dla środowiska uruchomieniowego funkcji. Dowolna funkcja w aplikacji funkcji może używać tych modułów.

Uwaga

Moduły określone w pliku requirements.psd1 są automatycznie pobierane i uwzględniane w ścieżce, więc nie trzeba ich dołączać do folderu modules. Są one przechowywane lokalnie w $env:LOCALAPPDATA/AzureFunctions folderze i w /data/ManagedDependencies folderze podczas uruchamiania w chmurze.

Aby skorzystać z funkcji modułu niestandardowego, utwórz Modules folder w katalogu głównym aplikacji funkcji. Skopiuj moduły, których chcesz użyć w funkcjach w tej lokalizacji.

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

Modules W folderze aplikacja funkcji powinna mieć następującą strukturę folderów:

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

Po uruchomieniu aplikacji funkcji proces roboczy języka programu PowerShell dodaje ten Modules folder do $env:PSModulePath folderu, aby można było polegać na automatycznym ładowaniu modułu tak samo jak w zwykłym skrycie programu PowerShell.

Folder modułów na poziomie procesu roboczego języka

Kilka modułów jest często używanych przez proces roboczy języka programu PowerShell. Te moduły są definiowane w ostatniej pozycji PSModulePathelementu .

Bieżąca lista modułów jest następująca:

Microsoft.PowerShell.Archive: moduł używany do pracy z archiwami, takimi jak .zip, .nupkgi inne.
ThreadJob: implementacja oparta na wątkach interfejsów API zadań programu PowerShell.

Domyślnie usługa Functions używa najnowszej wersji tych modułów. Aby użyć określonej wersji modułu, umieść tę określoną wersję w Modules folderze aplikacji funkcji.

Zmienne środowiskowe

W obszarze Funkcje ustawienia aplikacji, takie jak parametry połączenia usługi, są widoczne jako zmienne środowiskowe podczas wykonywania. Dostęp do tych ustawień można uzyskać przy użyciu metody $env:NAME_OF_ENV_VAR, jak pokazano w poniższym przykładzie:

param($myTimer)

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

Istnieje kilka sposobów dodawania, aktualizowania i usuwania ustawień aplikacji funkcji:

Zmiany ustawień aplikacji funkcji wymagają ponownego uruchomienia aplikacji funkcji.

Podczas uruchamiania lokalnego ustawienia aplikacji są odczytywane z pliku projektu local.settings.json .

Współbieżność

Domyślnie środowisko uruchomieniowe programu PowerShell usługi Functions może przetwarzać tylko jedno wywołanie funkcji jednocześnie. Jednak ten poziom współbieżności może nie być wystarczający w następujących sytuacjach:

Podczas próby obsługi dużej liczby wywołań jednocześnie.
Gdy masz funkcje, które wywołują inne funkcje w tej samej aplikacji funkcji.

Istnieje kilka modeli współbieżności, które można eksplorować w zależności od typu obciążenia:

Zwiększ wartość FUNCTIONS_WORKER_PROCESS_COUNT. Umożliwia to obsługę wywołań funkcji w wielu procesach w tym samym wystąpieniu, co wprowadza pewne obciążenie procesora CPU i pamięci. Ogólnie rzecz biorąc, funkcje związane z we/wy nie będą cierpieć z powodu tego obciążenia. W przypadku funkcji powiązanych z procesorem CPU wpływ może być znaczący.
PSWorkerInProcConcurrencyUpperBound Zwiększ wartość ustawienia aplikacji. Dzięki temu można tworzyć wiele przestrzeni uruchomieniowych w ramach tego samego procesu, co znacznie zmniejsza obciążenie procesora CPU i pamięci.

Te zmienne środowiskowe można ustawić w ustawieniach aplikacji funkcji.

W zależności od przypadku użycia Durable Functions może znacznie zwiększyć skalowalność. Aby dowiedzieć się więcej, zobacz Durable Functions wzorce aplikacji.

Uwaga

Może zostać wyświetlone ostrzeżenie "żądania są w kolejce z powodu braku dostępnych przestrzeni uruchomieniowych", należy pamiętać, że nie jest to błąd. Komunikat informuje o tym, że żądania są kolejkowane i będą obsługiwane po zakończeniu poprzednich żądań.

Zagadnienia dotyczące używania współbieżności

Program PowerShell to domyślnie język skryptów single_threaded. Współbieżność można jednak dodać przy użyciu wielu przestrzeni uruchomieniowych programu PowerShell w tym samym procesie. Liczba utworzonych przestrzeni runspace i w związku z tym liczba współbieżnych wątków na proces roboczy jest ograniczona przez PSWorkerInProcConcurrencyUpperBound ustawienie aplikacji. Domyślnie liczba obszarów uruchamiania jest ustawiona na 1000 w wersji 4.x środowiska uruchomieniowego usługi Functions. W wersjach 3.x i poniżej maksymalna liczba obszarów uruchamiania jest ustawiona na 1. Przepływność będzie mieć wpływ na ilość procesora CPU i pamięci dostępnej w wybranym planie.

Azure PowerShell używa niektórych kontekstów i stanu na poziomie procesu, aby pomóc zaoszczędzić na nadmiarowym wpisywaniu. Jeśli jednak włączysz współbieżność w aplikacji funkcji i wywołasz akcje, które zmieniają stan, możesz skończyć z warunkami wyścigu. Te warunki wyścigu są trudne do debugowania, ponieważ jedna wywołanie opiera się na określonym stanie, a druga wywołanie zmieniło stan.

Istnieje ogromna wartość współbieżności z Azure PowerShell, ponieważ niektóre operacje mogą zająć dużo czasu. Należy jednak zachować ostrożność. Jeśli podejrzewasz, że występuje warunek wyścigu, ustaw ustawienie aplikacji PSWorkerInProcConcurrencyUpperBound na 1 i zamiast tego użyj izolacji poziomu procesu roboczego języka na potrzeby współbieżności.

Konfigurowanie skryptu funkcjiFile

Domyślnie funkcja programu PowerShell jest wykonywana z run.ps1pliku, który współudzieli ten sam katalog nadrzędny co odpowiadający mu element function.json.

Właściwość scriptFile w obiekcie function.json może służyć do pobierania struktury folderów, która wygląda jak w poniższym przykładzie:

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

W tym przypadku function.json element for myFunction zawiera właściwość odwołującą scriptFile się do pliku z wyeksportowaną funkcją do uruchomienia.

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

Używanie modułów programu PowerShell przez skonfigurowanie punktu wejścia

W tym artykule przedstawiono funkcje programu PowerShell w domyślnym run.ps1 pliku skryptu generowanym przez szablony. Można jednak również uwzględnić funkcje w modułach programu PowerShell. Możesz odwołać się do określonego kodu funkcji w module przy użyciu scriptFile pól i entryPoint w pliku konfiguracji function.json.

W takim przypadku entryPoint jest nazwą funkcji lub polecenia cmdlet w module programu PowerShell, do których odwołuje się moduł .scriptFile

Rozważ następującą strukturę folderów:

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

Gdzie PSFunction.psm1 zawiera:

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

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

Export-ModuleMember -Function "Invoke-PSTestFunc"

W tym przykładzie konfiguracja elementu myFunction zawiera scriptFile właściwość, która odwołuje PSFunction.psm1się do modułu programu PowerShell w innym folderze. Właściwość entryPoint odwołuje się do Invoke-PSTestFunc funkcji, która jest punktem wejścia w module.

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

W przypadku tej konfiguracji Invoke-PSTestFunc polecenie jest wykonywane dokładnie tak samo jak w run.ps1 przypadku.

Zagadnienia dotyczące funkcji programu PowerShell

Podczas pracy z funkcjami programu PowerShell należy pamiętać o zagadnieniach w poniższych sekcjach.

Zimny start

Podczas opracowywania Azure Functions w modelu hostingu bezserwerowego zimne starty są rzeczywistością. Zimny start odnosi się do okresu, jaki zajmuje aplikacja funkcji, aby rozpocząć uruchamianie w celu przetworzenia żądania. Zimny start występuje częściej w planie Zużycie, ponieważ aplikacja funkcji jest zamykana w okresach braku aktywności.

Tworzenie pakietów modułów zamiast używania Install-Module

Skrypt jest uruchamiany przy każdym wywołaniu. Unikaj używania Install-Module w skrycie. Zamiast tego należy używać przed Save-Module opublikowaniem, aby funkcja nie musiała tracić czasu na pobieranie modułu. Jeśli zimny start wpływa na funkcje, rozważ wdrożenie aplikacji funkcji w planie App Service ustawionym na zawsze włączone lub w planie Premium.

Następne kroki

Więcej informacji można znaleźć w następujących zasobach:

Przewodnik dla deweloperów usługi Azure Functions pracujących w programie PowerShell

Struktura folderów

Definiowanie skryptu programu PowerShell jako funkcji

TriggerMetadata, parametr

Powiązania

Odczytywanie wyzwalacza i danych wejściowych

Zapisywanie danych wyjściowych

składnia Push-OutputBinding

Push-OutputBinding przykład: odpowiedzi HTTP

Push-OutputBinding przykład: Powiązanie danych wyjściowych kolejki

polecenie cmdlet Get-OutputBinding

Rejestrowanie

Konfigurowanie poziomu dziennika aplikacji funkcji

Wyświetlanie dzienników

Typy wyzwalaczy i powiązań

Wyzwalacze i powiązania HTTP

Obiekt żądania

Obiekt odpowiedzi

Uzyskiwanie dostępu do żądania i odpowiedzi

Rzutowanie typów dla wyzwalaczy i powiązań

Profil programu PowerShell

Wersje programu PowerShell

Uruchamianie lokalne w określonej wersji

Zmienianie wersji programu PowerShell

Zarządzanie zależnościami

Docelowe wersje

Zagadnienia dotyczące zarządzania zależnościami

Ustawienia aplikacji do zarządzania zależnościami

Moduły niestandardowe

Folder modułów na poziomie aplikacji funkcji

Folder modułów na poziomie procesu roboczego języka

Zmienne środowiskowe

Współbieżność

Zagadnienia dotyczące używania współbieżności

Konfigurowanie skryptu funkcjiFile

Używanie modułów programu PowerShell przez skonfigurowanie punktu wejścia

Zagadnienia dotyczące funkcji programu PowerShell

Zimny start

Tworzenie pakietów modułów zamiast używania Install-Module

Następne kroki

Dodatkowe zasoby

Dodatkowe zasoby