Azure Functions の PowerShell 開発者向けガイド

[アーティクル]
01/30/2025

この記事では、PowerShell を使用して Azure Functions を作成する方法について詳しく説明します。

PowerShell Azure Functions (関数) は、トリガーされた時点で実行される PowerShell スクリプトとして表されます。それぞれの関数スクリプトには、関連する function.json ファイルが存在し、関数の動作 (トリガー方法や入力および出力パラメーターなど) が定義されています。詳細については、トリガーとバインディングに関する記事を参照してください。

他の種類の関数と同様、PowerShell スクリプト関数も、function.json ファイルで定義されているすべての入力バインディングの名前に対応したパラメーターを受け入れます。また、関数を開始したトリガーに関する追加情報を含む TriggerMetadata パラメーターも渡されます。

この記事では、「Azure Functions の開発者向けガイド」を既に読んでいることを前提としています。また、最初の PowerShell 関数を作成するために、PowerShell の Functions クイックスタートを完了していることも前提としています。

フォルダー構造

PowerShell プロジェクトに必要なフォルダー構造は次のようになります。この既定値は変更可能です。詳細については、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

プロジェクトのルートには、関数アプリの構成に使用できる共有 host.json ファイルがあります。各関数には、独自のコードファイル (.ps1) とバインディング構成ファイル (function.json) が含まれるフォルダーがあります。 function.json ファイルの親ディレクトリの名前は常に関数の名前です。

特定のバインディングには、extensions.csproj ファイルが必要になります。 Functions ランタイムのバージョン 2.x 以降に必要なバインド拡張機能は extensions.csproj ファイルで定義されており、実際のライブラリファイルは bin フォルダーにあります。ローカルで開発する場合は、バインド拡張機能を登録する必要があります。 Azure portal 上で関数を開発するときに、この登録が実行されます。

PowerShell 関数アプリには、必要に応じて profile.ps1 を含めることができます。これは、関数アプリの実行開始時 ("コールドスタート" とも呼ばれます) に実行されます。詳細については、「PowerShell プロファイル」を参照してください。

PowerShell スクリプトを関数として定義する

既定では、Functions ランタイムは run.ps1 で関数を検索します。run.ps1 は、対応する function.json と同じ親ディレクトリを共有します。

スクリプトは、実行時に複数の引数が渡されます。それらのパラメーターを処理するには、次の例のように、スクリプトの先頭に param ブロックを追加します。

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

TriggerMetadata パラメーター

TriggerMetadata パラメーターは、トリガーに関する追加情報を指定するために使用されます。このメタデータはバインディングによって異なりますが、いずれにも、次のデータが格納される sys プロパティが含まれています。

$TriggerMetadata.sys

プロパティ	説明	Type
UtcNow	関数がトリガーされた日時 (UTC)	DateTime
MethodName	トリガーされた関数の名前	string
RandGuid	この関数の実行に対して一意の GUID	string

トリガーの種類ごとに、異なる一連のメタデータがあります。たとえば、QueueTrigger の $TriggerMetadata には、数ある中でも InsertionTime、Id、DequeueCount が格納されます。キュートリガーのメタデータの詳細については、キュートリガーの公式ドキュメントを参照してください。実際に使用しているトリガーのドキュメントを確認すると、そのトリガーのメタデータに含まれるものがわかります。

バインド

PowerShell では、バインディングの構成と定義が関数の function.json に記述されます。関数は、さまざまな方法でバインドを操作します。

トリガーと入力データの読み取り

トリガーと入力バインディングは、関数に渡されたパラメーターとして読み取られます。入力バインディングの direction は、function.json で in に設定されています。 function.json で定義された name プロパティは、param ブロックにおけるパラメーターの名前です。 PowerShell ではバインディングに名前付きパラメーターが使用されるため、パラメーターの順序は重要ではありません。ただし、function.json で定義されているバインディングの順序に従うことをお勧めします。

param($MyFirstInputBinding, $MySecondInputBinding)

出力データの書き込み

Functions では、出力バインディングの direction が function.json で out に設定されています。出力バインディングに書き込むには、Push-OutputBinding コマンドレットを使用します。このコマンドレットは、Functions ランタイムから利用できます。どのような場合も、function.json で定義されたバインディングの name プロパティは、Push-OutputBinding コマンドレットの Name パラメーターに対応します。

次の例は、関数スクリプトで Push-OutputBinding を呼び出す方法を示しています。

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

特定のバインディングの値をパイプラインを介して渡すこともできます。

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding の動作は、-Name に指定された値に応じて異なります。

指定された名前を有効な出力バインディングに解決できない場合は、エラーがスローされます。
出力バインディングが値のコレクションを受け入れると、Push-OutputBinding を繰り返し呼び出して複数の値をプッシュすることができます。
出力バインディングがシングルトン値しか受け入れない場合は、2 回目に Push-OutputBinding を呼び出した時点でエラーが発生します。

Push-OutputBinding の構文

Push-OutputBinding の呼び出しに使用できる有効なパラメーターを次に示します。

名前	Type	[位置]	説明
`-Name`	String	1	設定する出力バインディングの名前。
`-Value`	Object	2	設定する出力バインディングの値。パイプライン ByValue から受け取ります。
`-Clobber`	SwitchParameter	named	(省略可能) 指定した場合は、指定した出力バインディングに対して値が強制的に設定されます。

以下の共通パラメーターもサポートされています。

Verbose
Debug
ErrorAction
ErrorVariable
WarningAction
WarningVariable
OutBuffer
PipelineVariable
OutVariable

詳細については、「About CommonParameters (共通パラメーターについて)」を参照してください。

Push-OutputBinding の例: HTTP 応答

HTTP トリガーは、response という名前の出力バインディングを使用して応答を返します。次の例では、出力バインディング response に値 "output #1" が設定されます。

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

出力先は HTTP ですが、シングルトン値しか受け入れないため、Push-OutputBinding が 2 回呼び出されると、エラーがスローされます。

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

出力がシングルトン値しか受け入れない場合は、-Clobber パラメーターを使用すると、コレクションへの追加を試みる代わりに古い値をオーバーライドすることができます。次の例では、既に値が追加されていることを前提としています。 -Clobber を使用することで、次の例からの応答では、既存の値がオーバーライドされ、"output #3" という値が返されます。

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

Push-OutputBinding の例: キュー出力バインディング

Push-OutputBinding は、出力バインディング (Azure Queue storage 出力バインディングなど) にデータを送信するために使用されます。次の例では、キューに書き込まれるメッセージの値は "output #1" です。

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

ストレージキューの出力バインディングは、複数の出力値を受け入れます。この場合、次の例を 1 つ目の例の後に呼び出すと、"output #1" と "output #2" の 2 つの項目を含むリストがキューに書き込まれます。

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

次の例は、前述の 2 つを呼び出した後に呼び出すと、さらに 2 つの値が出力コレクションに追加されます。

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

キューへの書き込み時には、メッセージに "output #1"、"output #2"、"output #3"、"output #4" という 4 つの値が格納されます。

Get-OutputBinding コマンドレット

出力バインディングに現在設定されている値を取得するには、Get-OutputBinding コマンドレットを使用できます。このコマンドレットは、出力バインディングの名前とそれぞれに対応する値を含んだハッシュテーブルを取得します。

Get-OutputBinding を使用して現在のバインディング値を返す例を次に示します。

Get-OutputBinding

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

Get-OutputBinding にも -Name というパラメーターがあります。これを使用すると、次の例に示すように、返されたバインディングをフィルター処理することができます。

Get-OutputBinding -Name MyQ*

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

Get-OutputBinding では、ワイルドカード (*) がサポートされます。

ログ記録

PowerShell 関数におけるログは、通常の PowerShell のログと同様に機能します。各出力ストリームへの書き込みには、ログコマンドレットを使用できます。各コマンドレットは、Functions で使用されるログレベルに対応します。

Functions のログレベル	ログコマンドレット
エラー	`Write-Error`
警告	`Write-Warning`
Information	`Write-Information` `Write-Host` `Write-Output` `Information` ログレベルに書き込みます。
デバッグ	`Write-Debug`
Trace	`Write-Progress` `Write-Verbose`

これらのコマンドレットに加え、パイプラインに書き込まれた内容はすべて Information ログレベルにリダイレクトされ、PowerShell の既定の書式で表示されます。

重要

Write-Verbose または Write-Debug コマンドレットを使用するだけでは、詳細およびデバッグレベルのログを表示するには不十分です。ログレベルのしきい値も構成して、実際に注目するログのレベルを宣言する必要があります。詳細については、「関数アプリのログレベルの構成」を参照してください。

関数アプリのログレベルの構成

Azure Functions では、しきい値レベルを定義することで、関数によるログへの書き込み方法を簡単に制御することができます。コンソールに書き込まれるすべてのトレースのしきい値を設定するには、host.json ファイルの logging.logLevel.default プロパティを使用します。この設定は、関数アプリのすべての関数に適用されます。

次の例では、すべての関数の詳細ログが有効になるようしきい値を設定しますが、MyFunction という名前の関数についてはデバッグログが有効になるようしきい値を設定しています。

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

詳細については、host.json のリファレンスを参照してください。

ログの表示

Azure 内で実行されている関数アプリは、Application Insights を使用して監視することができます。関数のログの表示とクエリについて詳しくは、「Azure Functions を監視する」をご覧ください。

開発のために関数アプリをローカルで実行している場合、ログの既定の出力先はファイルシステムとなります。コンソールでログを確認するには、AZURE_FUNCTIONS_ENVIRONMENT 環境変数を Development に設定してから関数アプリを開始してください。

トリガーとバインディングの種類

関数アプリで使用できるトリガーとバインディングは多数あります。トリガーとバインディングの全一覧は、こちらを参照してください。

コード内では、すべてのトリガーとバインディングが、以下に示した少数の実数データ型として表現されます。

Hashtable
string
byte[]
INT
double
HttpRequestContext
HttpResponseContext

この一覧の最初の 5 つの型は、標準 .NET 型です。最後の 2 つは、HttpTrigger トリガーのみで使用されます。

関数に含まれる各バインディングパラメーターは、これらの型のいずれかにする必要があります。

HTTP トリガーとバインディング

HTTP、webhook トリガー、および HTTP 出力バインディングでは、要求オブジェクトと応答オブジェクトを使用して HTTP メッセージングを表します。

要求オブジェクト

スクリプトに渡される要求オブジェクトは HttpRequestContext 型で、次のプロパティを持ちます。

プロパティ	説明	Type
`Body`	要求の本文を格納するオブジェクト。 `Body` は、データに基づいて最適な型にシリアル化されます。たとえば、データが JSON である場合はハッシュテーブルとして渡されます。データが文字列の場合は文字列として渡されます。	object
`Headers`	要求ヘッダーを格納するディクショナリ。	Dictionary<string,string>^*
`Method`	要求の HTTP メソッド。	string
`Params`	要求のルーティングパラメーターを格納するオブジェクト。	Dictionary<string,string>^*
`Query`	クエリパラメーターを格納するオブジェクト。	Dictionary<string,string>^*
`Url`	要求の URL。	string

^* Dictionary<string,string> のキーはすべて、大文字と小文字が区別されません。

応答オブジェクト

返すべき応答オブジェクトは HttpResponseContext 型で、次のプロパティを持ちます。

プロパティ	説明	Type
`Body`	応答の本文を格納するオブジェクト。	object
`ContentType`	応答のコンテンツタイプを設定するための省略表現。	string
`Headers`	応答ヘッダーを格納するオブジェクト。	ディクショナリまたはハッシュテーブル
`StatusCode`	応答の HTTP 状態コード。	文字列または整数

要求と応答へのアクセス

HTTP トリガーを使用する場合、他の入力バインディングと同じ方法で HTTP 要求にアクセスできます。これは param ブロックにあります。

応答を返すには、次の例に示すように、HttpResponseContext オブジェクトを使用します。

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

この関数を呼び出した結果は次のとおりです。

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

トリガーとバインドの型キャスト

BLOB バインディングなど、いくつかのバインディングでは、パラメーターの型を指定できます。

たとえば、Blob Storage のデータを文字列として指定するには、param ブロックに次の型キャストを追加します。

param([string] $myBlob)

PowerShell プロファイル

PowerShell には、PowerShell プロファイルという概念があります。 PowerShell プロファイルに詳しくない場合は、「About profiles (プロファイルについて)」を参照してください。

PowerShell 関数では、プロファイルスクリプトは、最初のデプロイ時とアイドル状態からの復帰 (コールドスタート) 後にアプリの PowerShell worker インスタンスごとに 1 回実行されます。 PSWorkerInProcConcurrencyUpperBound 値を設定してコンカレンシーを有効にすると、作成された実行空間ごとにプロファイルスクリプトが実行されます。

Visual Studio Code や Azure Functions Core Tools などのツールを使用して関数アプリを作成すると、既定の profile.ps1 が自動的に作成されます。既定のプロファイルは Core Tools GitHub リポジトリで保持されており、次の機能を備えています。

Azure に対する自動 MSI 認証。
必要に応じて Azure PowerShell AzureRM PowerShell エイリアスを有効にする機能。

PowerShell のバージョン

次の表は、Functions ランタイムのメジャーバージョンと、それに必要な .NET バージョンごとに使用可能な PowerShell バージョンを示しています。

Functions バージョン	PowerShell バージョン	.NET バージョン
4.x	PowerShell 7.4	.NET 8
4.x	PowerShell 7.2 (サポート終了)	.NET 6

現在のバージョンを確認するには、任意の関数から $PSVersionTable を出力します。

Azure Functions のランタイムサポートポリシーについて詳しくは、こちらの記事をご覧ください

Note

Azure Functions での PowerShell 7.2 のサポートは、2024 年 11 月 8 日に終了します。 PowerShell 7.4 で実行するために PowerShell 7.2 関数をアップグレードするときに、いくつかの破壊的変更を解決しなければならない場合があります。 PowerShell 7.4 にアップグレードするには、こちらの移行ガイドに従ってください。

特定のバージョンでのローカルな実行

ローカルで PowerShell 関数を実行するときは、プロジェクトルートにある local.setting.json ファイル内の Values 配列に設定 "FUNCTIONS_WORKER_RUNTIME_VERSION" : "7.4" を追加する必要があります。 PowerShell 7.4 でローカルに実行する場合、local.settings.json ファイルは次の例のようになります。

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

Note

PowerShell 関数では、FUNCTIONS_WORKER_RUNTIME_VERSION の値 "~7" は "7.0.x" を意味します。 "~7" の PowerShell 関数アプリは、"7.4" に自動的にアップグレードされません。今後は、PowerShell 関数アプリの場合、対象とするメジャーとマイナーの両方のバージョンをアプリで指定することが必要になります。したがって、"7.4.x" を対象にする場合は、"7.4" を指定する必要があります

PowerShell のバージョンの変更

PowerShell 関数アプリを PowerShell 7.4 に移行する前に、次の点を考慮してください。

移行によってアプリに破壊的変更が生じる可能性があるため、アプリを PowerShell 7.4 にアップグレードする前にこちらの移行ガイドを確認してください。
関数アプリが Azure の Functions ランタイムの最新バージョン (バージョン 4.x) で実行されていることを確認します。詳細については、現在のランタイムバージョンを表示および更新する方法に関するセクションを参照してください。

関数アプリで使用される PowerShell のバージョンを変更するには、次のステップに従います。この操作は、Azure portal または PowerShell を使用して実行できます。

ポータル
PowerShell

Azure portal で、関数アプリに移動します。
[設定] で [構成] を選択します。 [全般設定] タブで、PowerShell のバージョンを探します。
目的の PowerShell Core のバージョンを選択し、 [保存] を選択します。再起動の保留に関する警告が表示されたら、 [続行] を選択します。関数アプリは、選択した PowerShell のバージョンで再起動します。

Note

PowerShell 7.4 に対する Azure Functions のサポートは一般公開 (GA) されています。 Azure portal で PowerShell 7.4 が引き続きプレビューとして表示される場合がありますが、近日中に GA の状態を反映するように更新されます。

PowerShell のバージョンを変更するには、次のスクリプトを実行します。

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

<SUBSCRIPTION_ID>、<RESOURCE_GROUP>、<FUNCTION_APP> を、Azure サブスクリプションの ID、リソースグループと関数アプリの名前にそれぞれ置き換えます。また、<VERSION> を 7.4 に置き換えます。返されたハッシュテーブルの Properties で powerShellVersion 設定の更新された値を確認できます。

構成に変更が加えられると、関数アプリが再起動します。

依存関係管理

PowerShell で記述された Azure Functions のモジュールの管理には、マネージド依存関係機能を使用するか、アプリコンテンツに直接モジュールを含めるという 2 つの方法があります。それぞれの方法には独自の利点があり、適切な方法を選択するかどうかは特定のニーズによって異なります。

適切なモジュール管理アプローチの選択

マネージド依存関係機能を使用する理由

簡略化された初期インストール: requirements.psd1 ファイルに基づいてモジュールのインストールを自動的に処理します。
自動アップグレード: モジュールは、手動による介入を必要とせずに、セキュリティ修正プログラムを含めて自動的に更新されます。

アプリコンテンツにモジュールを含める理由

PowerShell ギャラリーに依存しない: モジュールはアプリにバンドルされており、外部依存関係が排除されます。
より高度な制御: 自動アップグレードによって引き起こされる回帰のリスクを回避し、使用されるモジュールのバージョンを完全に制御できます。
互換性: Flex 従量課金で動作し、他の Linux SKU に推奨されます。

マネージド依存関係機能

マネージド依存関係機能を使用すると、Azure Functions は、requirements.psd1 ファイルで指定された PowerShell モジュールを自動的にダウンロードして管理できます。この機能は、新しい PowerShell 関数アプリで既定で有効になっています。

requirements.psd1 の構成

PowerShell を使用して Azure Functions でマネージド依存関係を使用するには、requirements.psd1 ファイルを構成する必要があります。このファイルには関数に必要なモジュールが指定されており、Azure Functions はこれらのモジュールを自動的にダウンロードして更新し、環境が最新の状態に保たれるようにします。

requirements.psd1 ファイルを設定して構成する方法は次のとおりです。

まだ存在しない場合は、Azure Functions のルートディレクトリに requirements.psd1 ファイルを作成します。
PowerShell データ構造でモジュールとそのバージョンを定義します。

requirements.psd1 ファイルの例:

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

アプリコンテンツにモジュールを含める

モジュールのバージョンをより詳細に制御し、外部リソースへの依存関係を回避するために、モジュールを関数アプリのコンテンツに直接含めることができます。

カスタムモジュールを含めるには:

関数アプリのルートにModulesフォルダーを作成します。
```
mkdir ./Modules
```
次のいずれかの方法を使用して、モジュールをModulesフォルダーにコピーします。
- モジュールがすでにローカルで使用可能な場合:
```
Copy-Item -Path /mymodules/mycustommodule -Destination ./Modules -Recurse
```
- Save-Module を使用して PowerShell ギャラリーから取得する:
```
Save-Module -Name MyCustomModule -Path ./Modules
```
- PSResourceGet モジュールの Save-PSResource を使用する:
```
Save-PSResource -Name MyCustomModule -Path ./Modules
```

関数アプリの構造が次のようになっている必要があります。

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

関数アプリを起動すると、PowerShell 言語ワーカーによりこの Modules フォルダーが $env:PSModulePath に追加されるため、通常の PowerShell スクリプトと同様に、モジュールの自動読み込みを利用できます。

マネージド依存関係のトラブルシューティング

マネージド依存関係の有効化

マネージド依存関係を機能させるには、host.jsonで機能を有効にする必要があります。

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

特定のバージョンをターゲットにする

特定のモジュールバージョンを対象とする場合、次の手順の両方に従って、正しいモジュールバージョンが読み込まれるようにすることが重要です。

requirements.psd1 でモジュールのバージョンを指定する:
```
@{
  'Az.Accounts' = '1.9.5'
}
```
import ステートメントを profile.ps1 に追加する:
```
Import-Module Az.Accounts -RequiredVersion '1.9.5'
```

次の手順に従うと、関数の起動時に指定したバージョンが読み込まれます。

特定のマネージド依存関係の間隔設定を構成する

次のアプリ設定を使用して、マネージド依存関係のダウンロードとインストール方法を構成できます。

設定	Default value	説明
MDMaxBackgroundUpgradePeriod	`7.00:00:00` (7 日)	PowerShell 関数アプリのバックグラウンド更新期間を制御します。
MDNewSnapshotCheckPeriod	`01:00:00` (1 時間)	PowerShell ワーカーが更新プログラムをチェックする頻度を指定します。
MDMinBackgroundUpgradePeriod	`1.00:00:00` (1 日)	アップグレードチェック間の最小時間。

依存関係の管理に関する考慮事項

インターネットアクセス: マネージド依存関係では、モジュールをダウンロードするために https://www.powershellgallery.com へのアクセスが必要です。必要に応じてファイアウォール/VNet 規則を変更するなど、環境でこのアクセスが許可されていることを確認します。
ライセンスへの同意: マネージド依存関係は、ライセンスへの同意を必要とするモジュールをサポートしていません。
Flex 従量課金プラン: マネージド依存関係機能は、Flex 従量課金プランではサポートされていません。代わりにカスタムモジュールを使用してください。
モジュールの場所: ローカルコンピューターでは、モジュールは通常、$env:PSModulePath のグローバルに使用可能なフォルダーのいずれかにインストールされます。 Azure で実行する場合、PowerShell 関数アプリの $env:PSModulePath は通常の PowerShell スクリプトの $env:PSModulePath とは異なり、アプリのコンテンツと共にアップロードされた Modules フォルダーと、マネージド依存関係によって管理される別の場所の両方が含まれます。

環境変数

Functions では、サービス接続文字列などのアプリ設定は、実行中に環境変数として公開されます。次の例に示すように、これらの設定には $env:NAME_OF_ENV_VAR を使用してアクセスできます。

param($myTimer)

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

関数アプリの設定は、いくつかの方法で追加、更新、削除できます。

関数アプリの設定に変更を加えるためには、関数アプリを再起動する必要があります。

ローカルで実行する場合、アプリ設定は local.settings.json プロジェクトファイルから読み取られます。

コンカレンシー

既定では、Functions PowerShell ランタイムで一度に処理できる関数の呼び出しは 1 つだけです。ただし、以下の状況では、このコンカレンシーレベルが十分でない場合があります。

多数の呼び出しを同時に処理しようとした場合。
他の関数を呼び出す関数が同じ関数アプリ内にある場合。

ワークロードの種類に応じて、いくつかのコンカレンシーモデルを調べることができます。

FUNCTIONS_WORKER_PROCESS_COUNT を増やします。この設定を大きくすると、同じインスタンス内の複数のプロセスで関数の呼び出しを処理できますが、特定の CPU とメモリでオーバーヘッドが発生します。一般に、I/O バインド関数は、このオーバーヘッドの影響を受けません。 CPU バインド関数の場合、影響が大きくなる可能性があります。
PSWorkerInProcConcurrencyUpperBound アプリの設定値を増やします。この設定を大きくすると、同じプロセス内に複数の実行空間を作成できるため、CPU とメモリのオーバーヘッドが大幅に減少します。

この環境変数は、関数アプリのアプリ設定で設定します。

使い方によっては、Durable Functions によってスケーラビリティが大幅に向上する場合があります。詳細については、Durable Functions のアプリケーションパターンに関する記事を参照してください。

Note

"使用可能な実行空間がないため、要求がキューに置かれています" という警告が表示される場合がありますが、これはエラーではありません。このメッセージは、要求がキューに登録されていて、前の要求が完了したときに処理されることを通知するものです。

コンカレンシーの使用に関する注意点

PowerShell は、既定では "シングルスレッド" のスクリプト言語です。ただし、同じプロセス内で複数の PowerShell 実行空間を使用することで、コンカレンシーを追加できます。作成された実行空間の数、つまりワーカーごとの同時実行スレッドの数は、PSWorkerInProcConcurrencyUpperBound アプリケーション設定によって制限されます。既定では、Functions ランタイムのバージョン 4.x では、実行空間の数は 1,000 に設定されています。バージョン 3.x 以下では、実行空間の最大数は 1 に設定されています。関数アプリのスループットは、選択したプランで使用可能な CPU とメモリの量によって影響を受けます。

開発者の入力の手間を軽減するために、Azure PowerShell では、"プロセスレベル" のコンテキストと状態が使用されています。ただし、関数アプリでコンカレンシーを有効にし、状態の変更を伴うアクションを呼び出した場合は、最終的に競合状態に陥る可能性があります。このような競合状態をデバッグするのは困難です。なぜなら、一方の呼び出しが特定の状態に依存しているのに、もう一方の呼び出しがその状態を変更したためです。

一部の操作にはかなりの時間がかかる可能性があるため、Azure PowerShell のコンカレンシーには非常に大きな価値があります。しかし、実際に使用する場合には注意が必要です。競合状態が発生していると思われる場合は、PSWorkerInProcConcurrencyUpperBound アプリ設定を 1 に設定し、代わりに、コンカレンシーに対して言語ワーカープロセスレベルの分離を使用します。

関数の scriptFile を構成する

既定では、PowerShell 関数は run.ps1 から実行されます。これは、対応する function.json と同じ親ディレクトリを共有するファイルです。

function.json の scriptFile プロパティを使用すると、次の例のようなフォルダー構造を取得できます。

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

この場合、myFunction の function.json には、実行するにあたってエクスポートされた関数のファイルを参照する scriptFile プロパティが含まれています。

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

entryPoint を構成して PowerShell モジュールを使用する

この記事の PowerShell 関数は、テンプレートによって生成される既定の run.ps1 スクリプトファイルと共に示されています。ただし、PowerShell モジュールには自作の関数を含めることもできます。モジュールに含まれている特定の関数コードを参照するには、function.json 構成ファイル内の scriptFile フィールドと entryPoint フィールドを使用します。

この場合の entryPoint は、scriptFile で参照される PowerShell モジュール内の関数またはコマンドレットの名前です。

次のフォルダー構造を考えてみましょう。

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

この場合、PSFunction.psm1 の内容は次のとおりです。

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

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

Export-ModuleMember -Function "Invoke-PSTestFunc"

この例の myFunction の構成には、PSFunction.psm1 (別のフォルダーにある PowerShell モジュール) を参照する scriptFile プロパティが含まれています。 entryPoint プロパティは、このモジュールのエントリポイントである Invoke-PSTestFunc 関数を参照します。

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

この構成では、run.ps1 の場合とまったく同じように Invoke-PSTestFunc が実行されます。

PowerShell 関数に関する注意点

PowerShell 関数を使用するときは、以下のセクションに記載されている事柄に注意してください。

コールドスタート

サーバーレスホスティングモデルで Azure Functions を開発する際は、コールドスタートを避けて通ることはできません。 "コールドスタート" とは、関数アプリの実行が開始されて要求が処理されるまでにかかる時間のことを指します。従量課金プランでは、非アクティブな期間中に関数アプリがシャットダウンされるため、コールドスタートの発生頻度が高くなります。

Install-Module の使用を避ける

呼び出しごとに関数スクリプトで Install-Module を実行すると、パフォーマンスの問題が発生する可能性があります。代わりに、関数アプリを発行して必要なモジュールをバンドルする前に、Save-Module または Save-PSResource を使用してください。

詳細については、「依存関係管理」のセクションを参照してください。

次のステップ

詳細については、次のリソースを参照してください。

次の方法で共有

Azure Functions の PowerShell 開発者向けガイド

フォルダー構造

PowerShell スクリプトを関数として定義する

TriggerMetadata パラメーター

バインド

トリガーと入力データの読み取り

出力データの書き込み

Push-OutputBinding の構文

Push-OutputBinding の例: HTTP 応答

Push-OutputBinding の例: キュー出力バインディング

Get-OutputBinding コマンドレット

ログ記録

関数アプリのログ レベルの構成

ログの表示

トリガーとバインディングの種類

HTTP トリガーとバインディング

要求オブジェクト

応答オブジェクト

要求と応答へのアクセス

トリガーとバインドの型キャスト

PowerShell プロファイル

PowerShell のバージョン

特定のバージョンでのローカルな実行

PowerShell のバージョンの変更

依存関係管理

適切なモジュール管理アプローチの選択

マネージド依存関係機能

requirements.psd1 の構成

アプリ コンテンツにモジュールを含める

マネージド依存関係のトラブルシューティング

マネージド依存関係の有効化

特定のバージョンをターゲットにする

特定のマネージド依存関係の間隔設定を構成する

依存関係の管理に関する考慮事項

環境変数

コンカレンシー

コンカレンシーの使用に関する注意点

関数の scriptFile を構成する

entryPoint を構成して PowerShell モジュールを使用する

PowerShell 関数に関する注意点

コールド スタート

Install-Module の使用を避ける

次のステップ

フィードバック

その他のリソース

関数アプリのログレベルの構成

アプリコンテンツにモジュールを含める

コールドスタート