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

Artykuł
01/23/2025

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

Funkcja platformy Azure programu PowerShell (funkcja) 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 sposób działania funkcji, na przykład sposób wyzwalania i parametrów wejściowych i wyjściowych. Aby dowiedzieć się więcej, zobacz artykuł Triggers and binding (Wyzwalacze i powiązania).

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 założono, że znasz już dokumentację dla deweloperów usługi Azure Functions. Założono również, że ukończono przewodnik Szybki start dotyczący funkcji dla programu PowerShell w celu utworzenia pierwszej funkcji programu PowerShell.

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 .

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 wersji ś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 opracowywania funkcji w witrynie Azure Portal ta rejestracja jest wykonywana.

W aplikacjach funkcji programu PowerShell możesz opcjonalnie mieć profile.ps1 elementy uruchamiane po uruchomieniu aplikacji funkcji (w przeciwnym razie można znać 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.ps1pliku , gdzie run.ps1 współudzieli ten sam katalog nadrzędny co odpowiadający mu function.jsonelement .

Skrypt jest przekazywany kilka argumentów podczas wykonywania. Aby obsłużyć te parametry, dodaj param blok na początku 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)

Parametr TriggerMetadata

Parametr TriggerMetadata służy do podawania dodatkowych informacji o wyzwalaczu. Te 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ści	Opis	Type
UtcNow	Kiedy w formacie UTC funkcja została wyzwolona	DateTime
MethodName	Nazwa funkcji, która została wyzwolona	string
RandGuid	unikatowy identyfikator GUID dla tego wykonania funkcji	string

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 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 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. Jednak najlepszym rozwiązaniem jest przestrzeganie kolejności powiązań zdefiniowanych w pliku function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

Zapisywanie danych wyjściowych

W usłudze Functions powiązanie wyjściowe ma ustawioną direction out wartość w function.json. Możesz zapisać w powiązaniu Push-OutputBinding danych wyjściowych za pomocą 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 parametrze function.json polecenia cmdlet odpowiada parametrowi Push-OutputBinding polecenia cmdlet.

W poniższym przykładzie pokazano, jak wywołać Push-OutputBinding skrypt funkcji:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

Możesz 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 :

Jeśli nie można rozpoznać określonej nazwy jako 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 zgłasza błąd.

Składnia push-OutputBinding

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

Nazwisko	Typ	Position	opis
`-Name`	String	1	Nazwa powiązania wyjściowego, które chcesz ustawić.
`-Value`	Objekt	2	Wartość powiązania wyjściowego, które chcesz ustawić, które jest akceptowane z potoku ByValue.
`-Clobber`	PrzełącznikParametr	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).

Przykład push-OutputBinding: 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 mają wartość HTTP, która akceptuje tylko pojedynczą wartość, jest zgłaszany błąd, 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 wartości pojedyncze, można użyć parametru -Clobber , aby zastąpić starą wartość zamiast próby dodania do kolekcji. W poniższym przykładzie przyjęto założenie, że dodano już wartość. Przy użyciu metody -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

Przykład push-OutputBinding: powiązanie wyjściowe 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ótów zawierającą nazwy powiązań wyjściowych z odpowiednimi wartościami.

Poniżej przedstawiono przykład użycia polecenia Get-OutputBinding , aby zwrócić bieżące wartości powiązania:

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 zwróconego 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 jest mapowane na poziom dziennika używany przez funkcje.

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

Oprócz tych poleceń cmdlet wszystkie elementy zapisywane w potoku są przekierowywane do Information poziomu dziennika i wyświetlane z domyślnym formatowaniem 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 faktycznie cię interesuje. Aby dowiedzieć się więcej, zobacz Konfigurowanie poziomu dziennika aplikacji funkcji.

Konfigurowanie poziomu dziennika aplikacji funkcji

Usługa Azure Functions umożliwia zdefiniowanie poziomu progu, aby ułatwić kontrolowanie sposobu zapisywania w dziennikach przez funkcję Functions. Aby ustawić próg dla wszystkich śladów zapisanych w konsoli programu , 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 host.json dokumentacji.

Wyświetlanie dzienników

Jeśli aplikacja funkcji jest uruchomiona na platformie Azure, możesz użyć usługi Application Insights do jej monitorowania. Przeczytaj artykuł Monitoring Azure Functions (Monitorowanie usługi Azure Functions ), 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 programu , ustaw zmienną AZURE_FUNCTIONS_ENVIRONMENT środowiskową na wartość Development przed uruchomieniem aplikacji funkcji.

Wyzwalacze i typy powiązań

Istnieje wiele wyzwalaczy i powiązań dostępnych 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
string
byte[]
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ści	Opis	Type
`Body`	Obiekt zawierający treść żądania. `Body` jest serializowany do najlepszego typu na podstawie danych. Na przykład jeśli dane są danymi JSON, są przekazywane jako tabela skrótu. Jeśli dane są ciągiem, są przekazywane jako ciąg.	obiekt
`Headers`	Słownik zawierający nagłówki żądań.	Ciąg słownika<, ciąg>^*
`Method`	Metoda HTTP żądania.	string
`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.	string

^* 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ści	Opis	Type
`Body`	Obiekt zawierający treść odpowiedzi.	obiekt
`ContentType`	Krótka ręka ustawiania typu zawartości odpowiedzi.	string
`Headers`	Obiekt zawierający nagłówki odpowiedzi.	Słownik lub tabela skrótu
`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 w poniższym przykładzie:

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 pojęcie profilu programu PowerShell. Jeśli nie znasz profilów programu PowerShell, zobacz About profiles (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 idled (zimny start). Po włączeniu współbieżności przez ustawienie wartości PSWorkerInProcConcurrencyUpperBound skrypt profilu jest uruchamiany dla każdego utworzonego obszaru uruchomieniowego.

Podczas tworzenia aplikacji funkcji przy użyciu narzędzi, takich jak Visual Studio Code i Azure Functions Core Tools, zostanie utworzona wartość domyślna profile.ps1 . Domyślny profil jest utrzymywany w repozytorium GitHub narzędzi Core Tools i zawiera następujące elementy:

Automatyczne uwierzytelnianie msi na platformie Azure.
Możliwość włączania aliasów programu PowerShell programu Azure PowerShell AzureRM , jeśli chcesz.

Wersje programu PowerShell

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

Wersja usługi Functions	Wersja programu PowerShell	Wersja platformy .NET
4.x	PowerShell 7.4	.NET 8
4.x	PowerShell 7.2 (zakończenie obsługi)	.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 usługi Azure Functions, zapoznaj się z tym artykułem

Uwaga

Obsługa programu PowerShell 7.2 w usłudze Azure Functions kończy się 8 listopada 2024 r. Może być konieczne rozwiązanie niektórych zmian powodujących niezgodność podczas uaktualniania funkcji programu PowerShell 7.2 do uruchomienia w programie PowerShell 7.4. Postępuj zgodnie z tym przewodnikiem migracji , aby uaktualnić program PowerShell do wersji 7.4.

Uruchamianie lokalnego w określonej wersji

Podczas lokalnego uruchamiania funkcji programu PowerShell należy dodać ustawienie "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4" do Values tablicy w pliku local.setting.json w katalogu głównym projektu. W przypadku uruchamiania lokalnego w programie PowerShell 7.4 plik local.settings.json wygląda następująco:

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

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.4". 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óra ma być docelowa. W związku z tym należy wspomnieć o wartości "7.4", jeśli chcesz użyć wartości docelowej "7.4.x"

Zmienianie wersji programu PowerShell

Przed przeprowadzeniem migracji aplikacji funkcji programu PowerShell do programu PowerShell w wersji 7.4 należy wziąć pod uwagę następujące kwestie:

Ponieważ migracja może wprowadzać zmiany powodujące niezgodność w aplikacji, zapoznaj się z tym przewodnikiem migracji przed uaktualnieniem aplikacji do programu PowerShell 7.4.
Upewnij się, że aplikacja funkcji jest uruchomiona w najnowszej wersji środowiska uruchomieniowego usługi Functions na platformie Azure, która jest w wersji 4.x. Aby uzyskać więcej informacji, zobacz Wyświetlanie i aktualizowanie bieżącej wersji środowiska uruchomieniowego.

Wykonaj poniższe kroki, aby zmienić wersję programu PowerShell używaną przez aplikację funkcji. Tę operację można wykonać w witrynie 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 wyświetleniu ostrzeżenia o oczekiwaniu na ponowne uruchomienie wybierz pozycję Kontynuuj. Aplikacja funkcji zostanie uruchomiona ponownie w wybranej wersji programu PowerShell.

Uwaga

Obsługa usługi Azure Functions dla programu PowerShell 7.4 jest ogólnie dostępna . Program PowerShell 7.4 może być nadal wskazywany jako wersja zapoznawcza w witrynie Azure Portal, ale wkrótce zostanie zaktualizowany, aby odzwierciedlić stan ogólnie dostępnej wersji.

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> ciągiem 7.4. Możesz sprawdzić zaktualizowaną wartość powerShellVersion ustawienia w Properties zwracanej tabeli skrótów.

Aplikacja funkcji zostanie ponownie uruchomiona po wprowadzeniu zmiany w konfiguracji.

Zarządzanie zależnościami

Zarządzanie modułami w usłudze Azure Functions napisanymi w programie PowerShell można uzyskać na dwa sposoby: przy użyciu funkcji Zależności zarządzane lub dołączania modułów bezpośrednio w zawartości aplikacji. Każda metoda ma własne zalety i wybór odpowiedniej metody zależy od konkretnych potrzeb.

Wybieranie odpowiedniego podejścia do zarządzania modułami

Dlaczego warto używać funkcji Zależności zarządzane?

Uproszczona instalacja początkowa: automatycznie obsługuje instalację modułu na requirements.psd1 podstawie pliku.
Automatyczne uaktualnianie: moduły są aktualizowane automatycznie, w tym poprawki zabezpieczeń, bez konieczności ręcznej interwencji.

Dlaczego warto dołączać moduły do zawartości aplikacji?

Brak zależności od Galeria programu PowerShell: moduły są połączone z aplikacją, eliminując zależności zewnętrzne.
Większa kontrola: pozwala uniknąć ryzyka regresji spowodowanych automatycznymi uaktualnieniami, zapewniając pełną kontrolę nad używanymi wersjami modułów.
Zgodność: działa w środowisku Flex Consumption i jest zalecany w przypadku innych jednostek SKU systemu Linux.

Funkcja zależności zarządzanych

Funkcja Zależności zarządzane umożliwia usłudze Azure Functions automatyczne pobieranie modułów programu PowerShell określonych w requirements.psd1 pliku i zarządzanie nimi. Ta funkcja jest domyślnie włączona w nowych aplikacjach funkcji programu PowerShell.

Konfigurowanie wymagań.psd1

Aby używać zarządzanych zależności w usłudze Azure Functions za pomocą programu PowerShell, należy skonfigurować requirements.psd1 plik. Ten plik określa moduły wymagane przez funkcję, a usługa Azure Functions automatycznie pobiera i aktualizuje te moduły, aby zapewnić aktualność środowiska.

Poniżej przedstawiono sposób konfigurowania i konfigurowania requirements.psd1 pliku:

requirements.psd1 Utwórz plik w katalogu głównym funkcji platformy Azure, jeśli jeszcze nie istnieje.
Zdefiniuj moduły i ich wersje w strukturze danych programu PowerShell.

Przykład pliku requirements.psd1:

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

Dołączanie modułów do zawartości aplikacji

Aby uzyskać większą kontrolę nad wersjami modułów i uniknąć zależności od zasobów zewnętrznych, możesz dołączyć moduły bezpośrednio do zawartości aplikacji funkcji.

Aby uwzględnić moduły niestandardowe:

Modules Utwórz folder w katalogu głównym aplikacji funkcji.
```
mkdir ./Modules
```
Skopiuj moduły do Modules folderu przy użyciu jednej z następujących metod:
- Jeśli moduły są już dostępne lokalnie:
```
Copy-Item -Path /mymodules/mycustommodule -Destination ./Modules -Recurse
```
- Użyj polecenia Save-Module , aby pobrać z Galeria programu PowerShell:
```
Save-Module -Name MyCustomModule -Path ./Modules
```
- Korzystanie Save-PSResource z modułuPSResourceGet:
```
Save-PSResource -Name MyCustomModule -Path ./Modules
```

Aplikacja funkcji powinna mieć następującą strukturę:

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 , dzięki czemu można polegać na automatycznym ładowaniu modułu tak samo, jak w zwykłym skryscie programu PowerShell.

Rozwiązywanie problemów z zarządzanymi zależnościami

Włączanie zależności zarządzanych

Aby można było działać w zależnościach zarządzanych, funkcja musi być włączona w host.json:

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

Określone wersje docelowe

W przypadku określania wartości docelowej dla określonych wersji modułu należy wykonać oba poniższe kroki, aby upewnić się, że załadowana jest poprawna wersja modułu:

Określ wersję modułu w pliku requirements.psd1:
```
@{
  'Az.Accounts' = '1.9.5'
}
```

Dodaj instrukcję import do polecenia profile.ps1:

Import-Module Az.Accounts -RequiredVersion '1.9.5'

Wykonanie tych kroków gwarantuje, że określona wersja zostanie załadowana po uruchomieniu funkcji.

Konfigurowanie określonych ustawień interwału zależności zarządzanej

Sposób pobierania i instalowania zarządzanych zależności można skonfigurować przy użyciu następujących ustawień aplikacji:

Ustawienie	Wartość domyślna	opis
MDMaxBackgroundUpgradePeriod	`7.00:00:00` (siedem dni)	Określa okres aktualizacji w tle dla aplikacji funkcji programu PowerShell.
MDNewSnapshotCheckPeriod	`01:00:00` (jedna godzina)	Określa, jak często proces roboczy programu PowerShell sprawdza dostępność aktualizacji.
MDMinBackgroundUpgradePeriod	`1.00:00:00` (jeden dzień)	Minimalny czas między sprawdzaniem uaktualnienia.

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

Dostęp do Internetu: zależności zarządzane wymagają dostępu do https://www.powershellgallery.com pobierania modułów. Upewnij się, że środowisko zezwala na ten dostęp, w tym modyfikowanie reguł zapory/sieci wirtualnej zgodnie z potrzebami.
Akceptacja licencji: zależności zarządzane nie obsługują modułów wymagających akceptacji licencji.
Plan elastycznego zużycia: funkcja zależności zarządzanych nie jest obsługiwana w planie Flex Consumption. Zamiast tego użyj modułów niestandardowych.
Lokalizacje modułów: na komputerze lokalnym moduły są zwykle instalowane w jednym z globalnie dostępnych folderów w programie $env:PSModulePath. W przypadku uruchamiania na platformie Azure $env:PSModulePath aplikacja funkcji programu PowerShell różni się od $env:PSModulePath zwykłego skryptu programu PowerShell i będzie zawierać zarówno Modules folder przekazany z zawartością aplikacji, jak i oddzielną lokalizację zarządzaną przez zarządzane zależności.

Zmienne środowiskowe

W usłudze Functions 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.

W przypadku 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 w danym momencie. 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.
Jeśli masz funkcje, które wywołują inne funkcje wewnątrz 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. Zwiększenie tego ustawienia umożliwia obsługę wywołań funkcji w wielu procesach w ramach tego samego wystąpienia, co wprowadza pewne obciążenie procesora CPU i pamięci. Ogólnie rzecz biorąc, funkcje związane z we/wy nie cierpią z powodu tego obciążenia. W przypadku funkcji związanych z procesorem CPU wpływ może być znaczący.
PSWorkerInProcConcurrencyUpperBound Zwiększ wartość ustawienia aplikacji. Zwiększenie tego ustawienia pozwala na tworzenie wielu obszarów uruchamiania 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 rozszerzenie Durable Functions może znacznie zwiększyć skalowalność. Aby dowiedzieć się więcej, zobacz Durable Functions application patterns (Wzorce aplikacji Durable Functions).

Uwaga

Może zostać wyświetlony komunikat "Żądania są kolejkowane z powodu braku dostępnych przestrzeni uruchomieniowych" ostrzeżenia, 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 jest domyślnie językiem skryptów single_threaded . Współbieżność można jednak dodać przy użyciu wielu obszarów uruchomieniowych programu PowerShell w tym samym procesie. Liczba utworzonych przestrzeni uruchomieniowych i w związku z tym liczba współbieżnych wątków na proces roboczy jest ograniczona PSWorkerInProcConcurrencyUpperBound przez 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 uruchomieniowych jest ustawiona na 1. Przepływność aplikacji funkcji ma wpływ na ilość procesora CPU i pamięci dostępnej w wybranym planie.

Program 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 zakończyć się warunkami wyścigu. Te warunki wyścigu są trudne do debugowania, ponieważ jedno wywołanie opiera się na określonym stanie, a drugie wywołanie zmieniło stan.

Istnieje ogromna wartość współbieżności w programie 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 wartość i zamiast tego użyj izolacji poziomu procesu roboczego języka dla 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 function.jsonelement .

Właściwość scriptFile w pliku function.json może służyć do uzyskania 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 element function.json 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 programu entryPoint

Funkcje programu PowerShell w tym artykule są wyświetlane z domyślnym run.ps1 plikiem 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 się PSFunction.psm1do 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 polecenie Invoke-PSTestFunc jest wykonywane dokładnie tak, jak w przypadku.run.ps1

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 usługi Azure Functions w modelu hostingu bezserwerowego zimne starty są rzeczywistością. Zimny start odnosi się do okresu, przez jaki aplikacja funkcji zacznie uruchamiać żądanie. Zimny start występuje częściej w planie Zużycie, ponieważ aplikacja funkcji jest zamykana w okresach braku aktywności.

Unikaj używania modułu Install-Module

Uruchomienie Install-Module skryptu funkcji w każdym wywołaniu może spowodować problemy z wydajnością. Zamiast tego użyj polecenia Save-Module lub Save-PSResource przed opublikowaniem aplikacji funkcji, aby powiązać niezbędne moduły.

Aby uzyskać więcej informacji, zobacz sekcję Zarządzanie zależnościami .

Następne kroki

Aby uzyskać więcej informacji, zobacz następujące zasoby:

Udostępnij za pośrednictwem

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

Struktura folderów

Definiowanie skryptu programu PowerShell jako funkcji

Parametr TriggerMetadata

Powiązania

Odczytywanie wyzwalacza i danych wejściowych

Zapisywanie danych wyjściowych

Składnia push-OutputBinding

Przykład push-OutputBinding: odpowiedzi HTTP

Przykład push-OutputBinding: powiązanie wyjściowe kolejki

Polecenie cmdlet Get-OutputBinding

Rejestrowanie

Konfigurowanie poziomu dziennika aplikacji funkcji

Wyświetlanie dzienników

Wyzwalacze i typy 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 lokalnego w określonej wersji

Zmienianie wersji programu PowerShell

Zarządzanie zależnościami

Wybieranie odpowiedniego podejścia do zarządzania modułami

Funkcja zależności zarządzanych

Konfigurowanie wymagań.psd1

Dołączanie modułów do zawartości aplikacji

Rozwiązywanie problemów z zarządzanymi zależnościami

Włączanie zależności zarządzanych

Określone wersje docelowe

Konfigurowanie określonych ustawień interwału zależności zarządzanej

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

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 programu entryPoint

Zagadnienia dotyczące funkcji programu PowerShell

Zimny start

Unikaj używania modułu Install-Module

Następne kroki

Opinia

Dodatkowe zasoby