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

この記事では、PowerShell を使用して Azure Functions を作成する方法について詳しく説明します。This article provides details about how you write Azure Functions using PowerShell.

PowerShell Azure 関数 (関数) は、トリガーされた時点で実行される PowerShell スクリプトとして表されます。A PowerShell Azure function (function) is represented as a PowerShell script that executes when triggered. それぞれの関数スクリプトには、関連する function.json ファイルが存在し、関数の動作 (トリガー方法や入力および出力パラメーターなど) が定義されています。Each function script has a related function.json file that defines how the function behaves, such as how it's triggered and its input and output parameters. 詳細については、トリガーとバインディングに関する記事を参照してください。To learn more, see the Triggers and binding article.

他の種類の関数と同様、PowerShell スクリプト関数も、function.json ファイルで定義されているすべての入力バインディングの名前に対応したパラメーターを受け入れます。Like other kinds of functions, PowerShell script functions take in parameters that match the names of all the input bindings defined in the function.json file. また、関数を開始したトリガーに関する追加情報を含む TriggerMetadata パラメーターも渡されます。A TriggerMetadata parameter is also passed that contains additional information on the trigger that started the function.

この記事では、「Azure Functions の開発者向けガイド」を既に読んでいることを前提としています。This article assumes that you have already read the Azure Functions developer reference. また、Functions の PowerShell 向けクイックスタートで、初めての PowerShell 関数を作成しておく必要があります。You should have also completed the Functions quickstart for PowerShell to create your first PowerShell function.

フォルダー構造Folder structure

PowerShell プロジェクトに必要なフォルダー構造は次のようになります。The required folder structure for a PowerShell project looks like the following. この既定値は変更可能です。This default can be changed. 詳しくは、後の scriptFile に関するセクションをご覧ください。For more information, see the scriptFile section below.

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 ファイルがあります。At the root of the project, there's a shared host.json file that can be used to configure the function app. 各関数には、独自のコード ファイル (.ps1) とバインディング構成ファイル (function.json) が含まれるフォルダーがあります。Each function has a folder with its own code file (.ps1) and binding configuration file (function.json). function.json ファイルの親ディレクトリの名前は常に関数の名前です。The name of the function.json file's parent directory is always the name of your function.

特定のバインディングには、extensions.csproj ファイルが必要になります。Certain bindings require the presence of an extensions.csproj file. Functions ランタイムのバージョン 2.x 以降に必要なバインド拡張機能は extensions.csproj ファイルで定義されており、実際のライブラリ ファイルは bin フォルダーにあります。Binding extensions, required in version 2.x and later versions of the Functions runtime, are defined in the extensions.csproj file, with the actual library files in the bin folder. ローカルで開発する場合は、バインド拡張機能を登録する必要があります。When developing locally, you must register binding extensions. Azure portal 上で関数を開発するときに、この登録が実行されます。When developing functions in the Azure portal, this registration is done for you.

PowerShell 関数アプリには、必要に応じて profile.ps1 を含めることができます。これは、関数アプリの実行開始時 (" コールド スタート " とも呼ばれます) に実行されます。In PowerShell Function Apps, you may optionally have a profile.ps1 which runs when a function app starts to run (otherwise know as a cold start. 詳細については、「PowerShell プロファイル」を参照してください。For more information, see PowerShell profile.

PowerShell スクリプトを関数として定義するDefining a PowerShell script as a function

既定では、Functions ランタイムは run.ps1 で関数を検索します。run.ps1 は、対応する function.json と同じ親ディレクトリを共有します。By default, the Functions runtime looks for your function in run.ps1, where run.ps1 shares the same parent directory as its corresponding function.json.

スクリプトは、実行時に多数の引数が渡されます。Your script is passed a number of arguments on execution. それらのパラメーターを処理するには、次の例のように、スクリプトの先頭に param ブロックを追加します。To handle these parameters, add a param block to the top of your script as in the following example:

# $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 parameter

TriggerMetadata パラメーターは、トリガーに関する追加情報を指定するために使用されます。The TriggerMetadata parameter is used to supply additional information about the trigger. 追加のメタデータはバインディングによって異なりますが、いずれにも、次のデータが格納される sys プロパティが含まれています。The additional metadata varies from binding to binding but they all contain a sys property that contains the following data:

$TriggerMetadata.sys
プロパティProperty 説明Description TypeType
UtcNowUtcNow 関数がトリガーされた日時 (UTC)When, in UTC, the function was triggered DateTimeDateTime
MethodNameMethodName トリガーされた関数の名前The name of the Function that was triggered stringstring
RandGuidRandGuid この関数の実行に対して一意の GUIDa unique guid to this execution of the function stringstring

トリガーの種類ごとに、異なる一連のメタデータがあります。Every trigger type has a different set of metadata. たとえば、QueueTrigger$TriggerMetadata には、数ある中でも InsertionTimeIdDequeueCount が格納されます。For example, the $TriggerMetadata for QueueTrigger contains the InsertionTime, Id, DequeueCount, among other things. キュー トリガーのメタデータの詳細については、キュー トリガーの公式ドキュメントを参照してください。For more information on the queue trigger's metadata, go to the official documentation for queue triggers. 実際に使用しているトリガーのドキュメントを確認すると、そのトリガーのメタデータに含まれるものがわかります。Check the documentation on the triggers you're working with to see what comes inside the trigger metadata.

バインドBindings

PowerShell では、バインディングの構成と定義が関数の function.json に記述されます。In PowerShell, bindings are configured and defined in a function's function.json. 関数は、さまざまな方法でバインドを操作します。Functions interact with bindings a number of ways.

トリガーと入力データの読み取りReading trigger and input data

トリガーと入力バインディングは、関数に渡されたパラメーターとして読み取られます。Trigger and input bindings are read as parameters passed to your function. 入力バインディングの direction は、function.json で in に設定されています。Input bindings have a direction set to in in function.json. function.json で定義された name プロパティは、param ブロックにおけるパラメーターの名前です。The name property defined in function.json is the name of the parameter, in the param block. PowerShell ではバインディングに名前付きパラメーターが使用されるため、パラメーターの順序は重要ではありません。Since PowerShell uses named parameters for binding, the order of the parameters doesn't matter. ただし、function.json で定義されているバインディングの順序に従うことをお勧めします。However, it's a best practice to follow the order of the bindings defined in the function.json.

param($MyFirstInputBinding, $MySecondInputBinding)

出力データの書き込みWriting output data

Functions では、出力バインディングの direction が function.json で out に設定されています。In Functions, an output binding has a direction set to out in the function.json. 出力バインディングに書き込むには、Push-OutputBinding コマンドレットを使用します。このコマンドレットは、Functions ランタイムから利用できます。You can write to an output binding by using the Push-OutputBinding cmdlet, which is available to the Functions runtime. どのような場合も、function.json で定義されたバインディングの name プロパティは、Push-OutputBinding コマンドレットの Name パラメーターに対応します。In all cases, the name property of the binding as defined in function.json corresponds to the Name parameter of the Push-OutputBinding cmdlet.

関数スクリプトから Push-OutputBinding を呼び出す方法を次に示します。The following shows how to call Push-OutputBinding in your function script:

param($MyFirstInputBinding, $MySecondInputBinding)

Push-OutputBinding -Name myQueue -Value $myValue

特定のバインディングの値をパイプラインを介して渡すこともできます。You can also pass in a value for a specific binding through the pipeline.

param($MyFirstInputBinding, $MySecondInputBinding)

Produce-MyOutputValue | Push-OutputBinding -Name myQueue

Push-OutputBinding の動作は、-Name に指定された値に応じて異なります。Push-OutputBinding behaves differently based on the value specified for -Name:

  • 指定された名前を有効な出力バインディングに解決できない場合は、エラーがスローされます。When the specified name cannot be resolved to a valid output binding, then an error is thrown.

  • 出力バインディングが値のコレクションを受け入れると、Push-OutputBinding を繰り返し呼び出して複数の値をプッシュすることができます。When the output binding accepts a collection of values, you can call Push-OutputBinding repeatedly to push multiple values.

  • 出力バインディングがシングルトン値しか受け入れない場合は、2 回目に Push-OutputBinding を呼び出した時点でエラーが発生します。When the output binding only accepts a singleton value, calling Push-OutputBinding a second time raises an error.

Push-OutputBinding の構文Push-OutputBinding syntax

Push-OutputBinding の呼び出しに使用できる有効なパラメーターを次に示します。The following are valid parameters for calling Push-OutputBinding:

名前Name TypeType [位置]Position 説明Description
-Name StringString 11 設定する出力バインディングの名前。The name of the output binding you want to set.
-Value ObjectObject 22 設定する出力バインディングの値。パイプライン ByValue から受け取ります。The value of the output binding you want to set, which is accepted from the pipeline ByValue.
-Clobber SwitchParameterSwitchParameter namedNamed (省略可能) 指定した場合は、指定した出力バインディングに対して値が強制的に設定されます。(Optional) When specified, forces the value to be set for a specified output binding.

以下の共通パラメーターもサポートされています。The following common parameters are also supported:

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

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

Push-OutputBinding の例: HTTP 応答Push-OutputBinding example: HTTP responses

HTTP トリガーは、response という名前の出力バインディングを使用して応答を返します。An HTTP trigger returns a response using an output binding named response. 次の例では、出力バインディング response に値 "output #1" が設定されます。In the following example, the output binding of response has the value of "output #1":

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

出力先は HTTP ですが、シングルトン値しか受け入れないため、Push-OutputBinding が 2 回呼び出されると、エラーがスローされます。Because the output is to HTTP, which accepts a singleton value only, an error is thrown when Push-OutputBinding is called a second time.

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

出力がシングルトン値しか受け入れない場合は、-Clobber パラメーターを使用すると、コレクションへの追加を試みる代わりに古い値をオーバーライドすることができます。For outputs that only accept singleton values, you can use the -Clobber parameter to override the old value instead of trying to add to a collection. 次の例では、既に値が追加されていることを前提としています。The following example assumes that you have already added a value. -Clobber を使用することで、次の例からの応答では、既存の値がオーバーライドされ、"output #3" という値が返されます。By using -Clobber, the response from the following example overrides the existing value to return a value of "output #3":

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

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

Push-OutputBinding は、出力バインディング (Azure Queue storage 出力バインディングなど) にデータを送信するために使用されます。Push-OutputBinding is used to send data to output bindings, such as an Azure Queue storage output binding. 次の例では、キューに書き込まれるメッセージの値は "output #1" です。In the following example, the message written to the queue has a value of "output #1":

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

ストレージ キューの出力バインディングは、複数の出力値を受け入れます。The output binding for a Storage queue accepts multiple output values. この場合、次の例を 1 つ目の例の後に呼び出すと、"output #1" と "output #2" の 2 つの項目を含むリストがキューに書き込まれます。In this case, calling the following example after the first writes to the queue a list with two items: "output #1" and "output #2".

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

次の例は、前述の 2 つを呼び出した後に呼び出すと、さらに 2 つの値が出力コレクションに追加されます。The following example, when called after the previous two, adds two more values to the output collection:

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

キューへの書き込み時には、メッセージに "output #1"、"output #2"、"output #3"、"output #4" という 4 つの値が格納されます。When written to the queue, the message contains these four values: "output #1", "output #2", "output #3", and "output #4".

Get-OutputBinding コマンドレットGet-OutputBinding cmdlet

出力バインディングに現在設定されている値を取得するには、Get-OutputBinding コマンドレットを使用できます。You can use the Get-OutputBinding cmdlet to retrieve the values currently set for your output bindings. このコマンドレットは、出力バインディングの名前とそれぞれに対応する値を含んだハッシュテーブルを取得します。This cmdlet retrieves a hashtable that contains the names of the output bindings with their respective values.

Get-OutputBinding を使用して現在のバインディング値を返す例を次に示します。The following is an example of using Get-OutputBinding to return current binding values:

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

Get-OutputBinding にも -Name というパラメーターがあります。これを使用すると、次の例に示すように、返されたバインディングをフィルター処理することができます。Get-OutputBinding also contains a parameter called -Name, which can be used to filter the returned binding, as in the following example:

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

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

ログ記録Logging

PowerShell 関数におけるログは、通常の PowerShell のログと同様に機能します。Logging in PowerShell functions works like regular PowerShell logging. 各出力ストリームへの書き込みには、ログ コマンドレットを使用できます。You can use the logging cmdlets to write to each output stream. 各コマンドレットは、Functions で使用されるログ レベルに対応します。Each cmdlet maps to a log level used by Functions.

Functions のログ レベルFunctions logging level ログ コマンドレットLogging cmdlet
エラーError Write-Error
警告Warning Write-Warning
InformationInformation Write-Information
Write-Host
Write-Output
InformationInformation "情報" レベル ログへの書き込みWrites to Information level logging.
デバッグDebug Write-Debug
TraceTrace Write-Progress
Write-Verbose

これらのコマンドレットに加え、パイプラインに書き込まれた内容はすべて Information ログ レベルにリダイレクトされ、PowerShell の既定の書式で表示されます。In addition to these cmdlets, anything written to the pipeline is redirected to the Information log level and displayed with the default PowerShell formatting.

重要

Write-Verbose または Write-Debug コマンドレットを使用するだけでは、詳細およびデバッグ レベルのログを表示するには不十分です。Using the Write-Verbose or Write-Debug cmdlets is not enough to see verbose and debug level logging. ログ レベルのしきい値も構成して、実際に注目するログのレベルを宣言する必要があります。You must also configure the log level threshold, which declares what level of logs you actually care about. 詳細については、「関数アプリのログ レベルの構成」を参照してください。To learn more, see Configure the function app log level.

関数アプリのログ レベルの構成Configure the function app log level

Azure Functions では、しきい値レベルを定義することで、関数によるログへの書き込み方法を簡単に制御することができます。Azure Functions lets you define the threshold level to make it easy to control the way Functions writes to the logs. コンソールに書き込まれるすべてのトレースのしきい値を設定するには、host.json ファイルlogging.logLevel.default プロパティを使用します。To set the threshold for all traces written to the console, use the logging.logLevel.default property in the host.json file. この設定は、関数アプリのすべての関数に適用されます。This setting applies to all functions in your function app.

次の例では、すべての関数の詳細ログが有効になるようしきい値を設定しますが、MyFunction という名前の関数についてはデバッグ ログが有効になるようしきい値を設定しています。The following example sets the threshold to enable verbose logging for all functions, but sets the threshold to enable debug logging for a function named MyFunction:

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

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

ログの表示Viewing the logs

Azure 内で実行されている関数アプリは、Application Insights を使用して監視することができます。If your Function App is running in Azure, you can use Application Insights to monitor it. 関数のログの表示とクエリについて詳しくは、「Azure Functions を監視する」をご覧ください。Read monitoring Azure Functions to learn more about viewing and querying function logs.

開発のために関数アプリをローカルで実行している場合、ログの既定の出力先はファイル システムとなります。If you're running your Function App locally for development, logs default to the file system. コンソールでログを確認するには、AZURE_FUNCTIONS_ENVIRONMENT 環境変数を Development に設定してから関数アプリを開始してください。To see the logs in the console, set the AZURE_FUNCTIONS_ENVIRONMENT environment variable to Development before starting the Function App.

トリガーとバインディングの種類Triggers and bindings types

関数アプリで使用できるトリガーとバインディングは多数あります。There are a number of triggers and bindings available to you to use with your function app. トリガーとバインディングの全一覧は、こちらを参照してくださいThe full list of triggers and bindings can be found here.

コード内では、すべてのトリガーとバインディングが、以下に示した少数の実数データ型として表現されます。All triggers and bindings are represented in code as a few real data types:

  • HashtableHashtable
  • stringstring
  • byte[]byte[]
  • INTint
  • doubledouble
  • HttpRequestContextHttpRequestContext
  • HttpResponseContextHttpResponseContext

この一覧の最初の 5 つの型は、標準 .NET 型です。The first five types in this list are standard .NET types. 最後の 2 つは、HttpTrigger トリガーのみで使用されます。The last two are used only by the HttpTrigger trigger.

関数に含まれる各バインディング パラメーターは、これらの型のいずれかにする必要があります。Each binding parameter in your functions must be one of these types.

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

HTTP、webhook トリガー、および HTTP 出力バインディングでは、要求オブジェクトと応答オブジェクトを使用して HTTP メッセージングを表します。HTTP and webhook triggers and HTTP output bindings use request and response objects to represent the HTTP messaging.

要求オブジェクトRequest object

スクリプトに渡される要求オブジェクトは HttpRequestContext 型で、次のプロパティを持ちます。The request object that's passed into the script is of the type HttpRequestContext, which has the following properties:

プロパティProperty 説明Description TypeType
Body 要求の本文を格納するオブジェクト。An object that contains the body of the request. Body は、データに基づいて最適な型にシリアル化されます。Body is serialized into the best type based on the data. たとえば、データが JSON である場合はハッシュテーブルとして渡されます。For example, if the data is JSON, it's passed in as a hashtable. データが文字列の場合は文字列として渡されます。If the data is a string, it's passed in as a string. objectobject
Headers 要求ヘッダーを格納するディクショナリ。A dictionary that contains the request headers. Dictionary<string,string>*Dictionary<string,string>*
Method 要求の HTTP メソッド。The HTTP method of the request. stringstring
Params 要求のルーティング パラメーターを格納するオブジェクト。An object that contains the routing parameters of the request. Dictionary<string,string>*Dictionary<string,string>*
Query クエリ パラメーターを格納するオブジェクト。An object that contains the query parameters. Dictionary<string,string>*Dictionary<string,string>*
Url 要求の URL。The URL of the request. stringstring

*Dictionary<string,string> のキーはすべて、大文字と小文字が区別されません。* All Dictionary<string,string> keys are case-insensitive.

応答オブジェクトResponse object

返すべき応答オブジェクトは HttpResponseContext 型で、次のプロパティを持ちます。The response object that you should send back is of the type HttpResponseContext, which has the following properties:

プロパティProperty 説明Description TypeType
Body 応答の本文を格納するオブジェクト。An object that contains the body of the response. objectobject
ContentType 応答のコンテンツ タイプを設定するための省略表現。A short hand for setting the content type for the response. stringstring
Headers 応答ヘッダーを格納するオブジェクト。An object that contains the response headers. ディクショナリまたはハッシュテーブルDictionary or Hashtable
StatusCode 応答の HTTP 状態コード。The HTTP status code of the response. 文字列または整数string or int

要求と応答へのアクセスAccessing the request and response

HTTP トリガーを使用する場合、他の入力バインディングと同じ方法で HTTP 要求にアクセスできます。When you work with HTTP triggers, you can access the HTTP request the same way you would with any other input binding. これは param ブロックにあります。It's in the param block.

応答を返すには、次に示すように、HttpResponseContext オブジェクトを使用します。Use an HttpResponseContext object to return a response, as shown in the following:

function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "anonymous"
    },
    {
      "type": "http",
      "direction": "out"
    }
  ]
}

run.ps1

param($req, $TriggerMetadata)

$name = $req.Query.Name

Push-OutputBinding -Name res -Value ([HttpResponseContext]@{
    StatusCode = [System.Net.HttpStatusCode]::OK
    Body = "Hello $name!"
})

この関数を呼び出した結果は次のとおりです。The result of invoking this function would be:

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

トリガーとバインドの型キャストType-casting for triggers and bindings

BLOB バインディングなど、いくつかのバインディングでは、パラメーターの型を指定できます。For certain bindings like the blob binding, you're able to specify the type of the parameter.

たとえば、Blob Storage のデータを文字列として指定するには、param ブロックに次の型キャストを追加します。For example, to have data from Blob storage supplied as a string, add the following type cast to my param block:

param([string] $myBlob)

PowerShell プロファイルPowerShell profile

PowerShell には、PowerShell プロファイルという概念があります。In PowerShell, there's the concept of a PowerShell profile. PowerShell プロファイルに詳しくない場合は、「About profiles (プロファイルについて)」を参照してください。If you're not familiar with PowerShell profiles, see About profiles.

PowerShell 関数では、関数アプリの起動時にプロファイル スクリプトが実行されます。In PowerShell Functions, the profile script executes when the function app starts. 関数アプリが起動するのは、最初にデプロイされたときとアイドル状態になった後です (コールド スタート)。Function apps start when first deployed and after being idled (cold start).

Visual Studio Code や Azure Functions Core Tools などのツールを使用して関数アプリを作成すると、既定の profile.ps1 が自動的に作成されます。When you create a function app using tools, such as Visual Studio Code and Azure Functions Core Tools, a default profile.ps1 is created for you. 既定のプロファイルは Core Tools GitHub リポジトリで保持されており、次の機能を備えています。The default profile is maintained on the Core Tools GitHub repository and contains:

  • Azure に対する自動 MSI 認証。Automatic MSI authentication to Azure.
  • 必要に応じて Azure PowerShell AzureRM PowerShell エイリアスを有効にする機能。The ability to turn on the Azure PowerShell AzureRM PowerShell aliases if you would like.

PowerShell バージョンPowerShell version

次の表では、Functions Runtime のメジャー バージョンごとに使用される PowerShell バージョンを示しています。The following table shows the PowerShell version used by each major version of the Functions runtime:

Functions バージョンFunctions version PowerShell バージョンPowerShell version
1.x1.x Windows PowerShell 5.1 (ランタイムによりロック)Windows PowerShell 5.1 (locked by the runtime)
2.x2.x PowerShell Core 6PowerShell Core 6

現在のバージョンを確認するには、任意の関数から $PSVersionTable を出力します。You can see the current version by printing $PSVersionTable from any function.

依存関係の管理Dependency management

Functions では、依存関係の管理に PowerShell ギャラリーを使用できます。Functions lets you leverage PowerShell gallery for managing dependencies. 依存関係の管理を有効になっていると、.psd1 ファイルを使って、必要なモジュールが自動的にダウンロードされます。With dependency management enabled, the requirements.psd1 file is used to automatically download required modules. この動作を有効にするには、次の例のように、host.json ファイルのルートで managedDependency プロパティを true に設定します。You enable this behavior by setting the managedDependency property to true in the root of the host.json file, as in the following example:

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

新しい PowerShell 関数プロジェクトを作成すると、依存関係の管理が既定で有効になり、Az モジュールが組み込まれます。When you create a new PowerShell functions project, dependency management is enabled by default, with the Azure Az module included. 現在サポートされているモジュールの最大数は 10 です。The maximum number of modules currently supported is 10. サポートされている構文は、次の requirements.psd1 に示すように、 MajorNumber .* または厳密なモジュール バージョンです。The supported syntax is MajorNumber.* or exact module version as shown in the following requirements.psd1 example:

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

requirements.psd1 ファイルを更新すると、更新されたモジュールは、再起動後にインストールされます。When you update the requirements.psd1 file, updated modules are installed after a restart.

注意

管理対象の依存関係では、モジュールをダウンロードするときに、 www.powershellgallery.com にアクセスする必要があります。Managed dependencies requires access to www.powershellgallery.com to download modules. ローカルで実行する場合は、必要なファイアウォール規則を追加して、ランタイムがこの URL にアクセスできることを確認してください。When running locally, make sure that the runtime can access this URL by adding any required firewall rules.

次のアプリケーション設定を使用して、管理対象の依存関係をダウンロードしてインストールする方法を変更できます。The following application settings can be used to change how the managed dependencies are downloaded and installed. アプリのアップグレードは MDMaxBackgroundUpgradePeriod 以内に開始され、アップグレード プロセスはほぼ MDNewSnapshotCheckPeriod 以内に完了します。Your app upgrade starts within MDMaxBackgroundUpgradePeriod, and the upgrade process completes within approximately the MDNewSnapshotCheckPeriod.

関数アプリ設定Function App setting 既定値Default value 説明Description
MDMaxBackgroundUpgradePeriod 7.00:00:00 (7 日)7.00:00:00 (7 days) 各 PowerShell ワーカー プロセスは、そのプロセスの開始時に PowerShell ギャラリーでモジュールのアップグレードのチェックを開始し、その後は MDMaxBackgroundUpgradePeriod ごとにチェックします。Each PowerShell worker process initiates checking for module upgrades on the PowerShell Gallery on process start and every MDMaxBackgroundUpgradePeriod after that. PowerShell ギャラリーで利用可能になった新しいモジュール バージョンは、ファイル システムにインストールされ、PowerShell ワーカーが使用できるになります。When a new module version is available in the PowerShell Gallery, it's installed to the file system and made available to PowerShell workers. この値を小さくすると、関数アプリは新しいモジュール バージョンを早く取得できますが、アプリ リソースの使用量 (ネットワーク I/O、CPU、ストレージ) も増加します。Decreasing this value lets your function app get newer module versions sooner, but it also increases the app resource usage (network I/O, CPU, storage). この値を大きくすると、アプリ リソースの使用量は減少しますが、アプリへの新しいモジュール バージョンの配信が遅れる可能性があります。Increasing this value decreases the app's resource usage, but it may also delay delivering new module versions to your app.
MDNewSnapshotCheckPeriod 01:00:00 (1 時間)01:00:00 (1 hour) 新しいモジュール バージョンがファイル システムにインストールされたら、すべての PowerShell ワーカー プロセスを再起動する必要があります。After new module versions are installed to the file system, every PowerShell worker process must be restarted. PowerShell ワーカーを再起動すると、現在の関数の実行が中断される可能性があるため、アプリの可用性がその影響を受けます。Restarting PowerShell workers affects your app availability as it can interrupt current function execution. すべての PowerShell ワーカー プロセスが再起動されるまで、関数呼び出しでは、前のモジュール バージョンまたは新しいモジュール バージョンのいずれかが使用される可能性があります。Until all PowerShell worker processes are restarted, function invocations may use either the old or the new module versions. すべての PowerShell ワーカーの再起動は MDNewSnapshotCheckPeriod 以内に完了します。Restarting all PowerShell workers complete within MDNewSnapshotCheckPeriod. この値を大きくすると、中断の頻度は低くなりますが、関数呼び出しで、前のモジュール バージョンまたは新しいモジュール バージョンのいずれかが非決定的に使用される期間が長くなることもあります。Increasing this value decreases the frequency of interruptions, but may also increase the period of time when function invocations use either the old or the new module versions non-deterministically.
MDMinBackgroundUpgradePeriod 1.00:00:00 (1 日)1.00:00:00 (1 day) ワーカーの頻繁な再起動によってモジュールのアップグレードが過剰にならないように、任意のワーカーで直近 MDMinBackgroundUpgradePeriod 以内にモジュールのアップグレード確認が開始されているときは、その確認は行われません。To avoid excessive module upgrades on frequent Worker restarts, checking for module upgrades isn't performed when any worker has already initiated that check in the last MDMinBackgroundUpgradePeriod.

独自のカスタム モジュールを利用する方法が、通常の方法とは若干異なります。Leveraging your own custom modules is a little different than how you would do it normally.

ローカル コンピューターでは、モジュールは、$env:PSModulePath にあるグローバルに利用できるフォルダーのいずれかにインストールされます。On your local computer, the module gets installed in one of the globally available folders in your $env:PSModulePath. Azure で実行されているときは、お使いのマシンにインストールされたモジュールにアクセスできません。When running in Azure, you don't have access to the modules installed on your machine. つまり、PowerShell 関数アプリの $env:PSModulePath は、通常の PowerShell スクリプトの $env:PSModulePath とは異なります。This means that the $env:PSModulePath for a PowerShell function app differs from $env:PSModulePath in a regular PowerShell script.

Functions では、PSModulePath に次の 2 つのパスが存在します。In Functions, PSModulePath contains two paths:

  • 関数アプリのルートに存在する Modules フォルダー。A Modules folder that exists at the root of your function app.
  • PowerShell 言語ワーカーによって制御される Modules フォルダーのパス。A path to a Modules folder that is controlled by the PowerShell language worker.

関数アプリレベルの Modules フォルダーFunction app-level Modules folder

カスタム モジュールを使用するには、関数が依存しているモジュールを Modules フォルダーに置きます。To use custom modules, you can place modules on which your functions depend in a Modules folder. このフォルダーにあるモジュールは、自動的に Functions Runtime から利用できる状態になります。From this folder, modules are automatically available to the functions runtime. 関数アプリ内のどの関数でもこれらのモジュールを使用できます。Any function in the function app can use these modules.

注意

requirements.psd1 ファイルで指定されているモジュールは、自動的にダウンロードされてパスに組み込まれるため、modules フォルダーに含める必要はありません。Modules specified in the requirements.psd1 file are automatically downloaded and included in the path so you don't need to include them in the modules folder. これらは、ローカルでは $env:LOCALAPPDATA/AzureFunctions フォルダーに、クラウドで実行されるときは /data/ManagedDependencies フォルダーに格納されます。These are stored locally in the $env:LOCALAPPDATA/AzureFunctions folder and in the /data/ManagedDependencies folder when run in the cloud.

カスタム モジュール機能を利用するには、関数アプリのルートに Modules フォルダーを作成します。To take advantage of the custom module feature, create a Modules folder in the root of your function app. 関数で使用したいモジュールをこの場所にコピーします。Copy the modules you want to use in your functions to this location.

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

Modules フォルダーでは、関数アプリのフォルダー構造が次のようになっている必要があります。With a Modules folder, your function app should have the following folder structure:

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

関数アプリを起動すると、PowerShell 言語ワーカーによりこの Modules フォルダーが $env:PSModulePath に追加されるため、通常の PowerShell スクリプトと同様に、モジュールの自動読み込みを利用できます。When you start your function app, the PowerShell language worker adds this Modules folder to the $env:PSModulePath so that you can rely on module autoloading just as you would in a regular PowerShell script.

言語ワーカー レベルの Modules フォルダーLanguage worker level Modules folder

いくつかのモジュールは、PowerShell 言語ワーカーによってよく使用されます。Several modules are commonly used by the PowerShell language worker. これらのモジュールは、PSModulePath の最後の位置で定義されます。These modules are defined in the last position of PSModulePath.

現在のモジュールの一覧は次のとおりです。The current list of modules is as follows:

  • Microsoft.PowerShell.Archive: アーカイブ (.zip.nupkg など) に使用されるモジュール。Microsoft.PowerShell.Archive: module used for working with archives, like .zip, .nupkg, and others.
  • ThreadJob: PowerShell ジョブ API のスレッドベースの実装です。ThreadJob: A thread-based implementation of the PowerShell job APIs.

既定では、Functions では、これらのモジュールの最新のバージョンが使用されます。By default, Functions uses the most recent version of these modules. 特定のバージョンを使用するには、関数アプリの Modules フォルダーにその特定のバージョンのモジュールを格納してください。To use a specific module version, put that specific version in the Modules folder of your function app.

環境変数Environment variables

Functions では、サービス接続文字列などのアプリ設定は、実行中に環境変数として公開されます。In Functions, app settings, such as service connection strings, are exposed as environment variables during execution. 次の例に示すように、これらの設定には $env:NAME_OF_ENV_VAR を使用してアクセスできます。You can access these settings using $env:NAME_OF_ENV_VAR, as shown in the following example:

param($myTimer)

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

関数アプリの設定は、いくつかの方法で追加、更新、削除できます。There are several ways that you can add, update, and delete function app settings:

ローカルで実行する場合、アプリ設定は local.settings.json プロジェクト ファイルから読み取られます。When running locally, app settings are read from the local.settings.json project file.

コンカレンシーConcurrency

既定では、Functions PowerShell ランタイムで一度に処理できる関数の呼び出しは 1 つだけです。By default, the Functions PowerShell runtime can only process one invocation of a function at a time. ただし、以下の状況では、このコンカレンシー レベルが十分でない場合があります。However, this concurrency level might not be sufficient in the following situations:

  • 多数の呼び出しを同時に処理しようとした場合。When you're trying to handle a large number of invocations at the same time.
  • 他の関数を呼び出す関数が同じ関数アプリ内にある場合。When you have functions that invoke other functions inside the same function app.

この動作を変更するには、次の環境変数を整数値に設定します。You can change this behavior by setting the following environment variable to an integer value:

PSWorkerInProcConcurrencyUpperBound

この環境変数は、関数アプリのアプリ設定で設定します。You set this environment variable in the app settings of your Function App.

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

PowerShell は、既定では "シングル スレッド" のスクリプト言語です。PowerShell is a single threaded scripting language by default. ただし、同じプロセス内で複数の PowerShell 実行空間を使用することで、コンカレンシーを追加できます。However, concurrency can be added by using multiple PowerShell runspaces in the same process. 作成される実行空間の量は、PSWorkerInProcConcurrencyUpperBound のアプリケーション設定と一致します。The amount of runspaces created will match the PSWorkerInProcConcurrencyUpperBound application setting. スループットは、選択したプランで使用可能な CPU とメモリの量によって影響を受けます。The throughput will be impacted by the amount of CPU and memory available in the selected plan.

開発者の入力の手間を軽減するために、Azure PowerShell では、"プロセスレベル" のコンテキストと状態が使用されています。Azure PowerShell uses some process-level contexts and state to help save you from excess typing. ただし、関数アプリでコンカレンシーを有効にし、状態の変更を伴うアクションを呼び出した場合は、最終的に競合状態に陥る可能性があります。However, if you turn on concurrency in your function app and invoke actions that change state, you could end up with race conditions. このような競合状態をデバッグするのは困難です。なぜなら、一方の呼び出しが特定の状態に依存しているのに、もう一方の呼び出しがその状態を変更したためです。These race conditions are difficult to debug because one invocation relies on a certain state and the other invocation changed the state.

一部の操作にはかなりの時間がかかる可能性があるため、Azure PowerShell のコンカレンシーには非常に大きな価値があります。There's immense value in concurrency with Azure PowerShell, since some operations can take a considerable amount of time. しかし、実際に使用する場合には注意が必要です。However, you must proceed with caution. 競合状態が発生していると思われる場合は、PSWorkerInProcConcurrencyUpperBound アプリ設定を 1 に設定し、代わりに、コンカレンシーに対して言語ワーカー プロセス レベルの分離を使用します。If you suspect that you're experiencing a race condition, set the PSWorkerInProcConcurrencyUpperBound app setting to 1 and instead use language worker process level isolation for concurrency.

関数の scriptFile を構成するConfigure function scriptFile

既定では、PowerShell 関数は run.ps1 から実行されます。これは、対応する function.json と同じ親ディレクトリを共有するファイルです。By default, a PowerShell function is executed from run.ps1, a file that shares the same parent directory as its corresponding function.json.

function.jsonscriptFile プロパティを使用すると、次の例のようなフォルダー構造を取得できます。The scriptFile property in the function.json can be used to get a folder structure that looks like the following example:

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

この場合、myFunctionfunction.json には、実行するにあたってエクスポートされた関数のファイルを参照する scriptFile プロパティが含まれています。In this case, the function.json for myFunction includes a scriptFile property referencing the file with the exported function to run.

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

entryPoint を構成して PowerShell モジュールを使用するUse PowerShell modules by configuring an entryPoint

この記事では、テンプレートによって生成される既定の run.ps1 スクリプト ファイル内の PowerShell 関数について説明してきました。This article has shown PowerShell functions in the default run.ps1 script file generated by the templates. ただし、PowerShell モジュールには自作の関数を含めることもできます。However, you can also include your functions in PowerShell modules. モジュールに含まれている特定の関数コードを参照するには、function.json 構成ファイル内の scriptFile フィールドと entryPoint フィールドを使用します。You can reference your specific function code in the module by using the scriptFile and entryPoint fields in the function.json` configuration file.

この場合の entryPoint は、scriptFile で参照される PowerShell モジュール内の関数またはコマンドレットの名前です。In this case, entryPoint is the name of a function or cmdlet in the PowerShell module referenced in scriptFile.

次のフォルダー構造を考えてみましょう。Consider the following folder structure:

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

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

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

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

Export-ModuleMember -Function "Invoke-PSTestFunc"

この例の myFunction の構成には、PSFunction.psm1 (別のフォルダーにある PowerShell モジュール) を参照する scriptFile プロパティが含まれています。In this example, the configuration for myFunction includes a scriptFile property that references PSFunction.psm1, which is a PowerShell module in another folder. entryPoint プロパティは、このモジュールのエントリ ポイントである Invoke-PSTestFunc 関数を参照します。The entryPoint property references the Invoke-PSTestFunc function, which is the entry point in the module.

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

この構成では、run.ps1 の場合とまったく同じように Invoke-PSTestFunc が実行されます。With this configuration, the Invoke-PSTestFunc gets executed exactly as a run.ps1 would.

PowerShell 関数に関する注意点Considerations for PowerShell functions

PowerShell 関数を使用するときは、以下のセクションに記載されている事柄に注意してください。When you work with PowerShell functions, be aware of the considerations in the following sections.

コールド スタートCold Start

サーバーレス ホスティング モデルで Azure Functions を開発する際は、コールド スタートを避けて通ることはできません。When developing Azure Functions in the serverless hosting model, cold starts are a reality. "コールド スタート" とは、関数アプリの実行が開始されて要求が処理されるまでにかかる時間のことを指します。Cold start refers to period of time it takes for your function app to start running to process a request. 従量課金プランでは、非アクティブな期間中に関数アプリがシャットダウンされるため、コールド スタートの発生頻度が高くなります。Cold start happens more frequently in the Consumption plan because your function app gets shut down during periods of inactivity.

Install-Module を使用せずにモジュールをバンドルするBundle modules instead of using Install-Module

スクリプトは、呼び出しのたびに実行されます。Your script is run on every invocation. スクリプト内で Install-Module を使用することは避けてください。Avoid using Install-Module in your script. その代わり、発行前に Save-Module を使用します。そうすれば、関数がモジュールをダウンロードする際に生じる無駄な時間をなくすことができます。Instead use Save-Module before publishing so that your function doesn't have to waste time downloading the module. コールド スタートが関数に影響を及ぼす場合は、"常にオン" に設定された App Service プラン、または Premium プランに関数アプリをデプロイすることを検討してください。If cold starts are impacting your functions, consider deploying your function app to an App Service plan set to always on or to a Premium plan.

次のステップNext steps

詳細については、次のリソースを参照してください。For more information, see the following resources: