Azure Functions PowerShell 개발자 가이드Azure Functions PowerShell developer guide

이 문서에서는 PowerShell을 사용 하 여 Azure Functions를 작성 하는 방법에 대해 자세히 설명 합니다.This article provides details about how you write Azure Functions using PowerShell.

참고

Azure Functions용 PowerShell은 현재 미리 보기로 제공되고 있습니다.PowerShell for Azure Functions is currently in preview. 중요 업데이트를 받으려면 GitHub의 Azure App Service 알림 리포지토리를 구독합니다.To receive important updates, subscribe to the Azure App Service announcements repository on GitHub.

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. 또한 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). 함수의 이름입니다. 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. 함수 런타임의 버전 2.x에 필요한 바인딩 확장은 bin 폴더의 실제 라이브러리 파일을 사용 하 여 extensions.csproj 파일에 정의 됩니다.Binding extensions, required in version 2.x 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

@No__t_0 매개 변수는 트리거에 대 한 추가 정보를 제공 하는 데 사용 됩니다.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 문자열string
RandGuidRandGuid 이 함수 실행에 대 한 고유 guid입니다.a unique guid to this execution of the function 문자열string

모든 트리거 형식에는 서로 다른 메타 데이터 집합이 있습니다.Every trigger type has a different set of metadata. 예를 들어 QueueTrigger에 대 한 $TriggerMetadata에는 InsertionTime, Id, DequeueCount 등이 포함 됩니다.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에서 바인딩은 함수의 함수 json에서 구성 및 정의 됩니다.In PowerShell, bindings are configured and defined in a function's function.json. Functions는 다양한 방법으로 바인딩과 상호 작용합니다.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는 json에서 in로 설정 됩니다.Input bindings have a direction set to in in function.json. @No__t_1에 정의 된 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

함수에서 출력 바인딩의 direction은 json에서 out로 설정 됩니다.In Functions, an output binding has a direction set to out in the function.json. 함수 런타임에 사용할 수 있는 Push-OutputBinding cmdlet을 사용 하 여 출력 바인딩에 쓸 수 있습니다.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 cmdlet의 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:

  • 지정 된 이름을 유효한 출력 바인딩으로 확인할 수 없으면 오류가 throw 됩니다.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.

  • 출력 바인딩에서 singleton 값만 허용 하는 경우 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:

nameName TypeType PositionPosition 설명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.

푸시 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를 두 번째로 호출 하면 오류가 발생 합니다.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"
})

Singleton 값만 허용 하는 출력의 경우에는 -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. @No__t_0를 사용 하 여 다음 예제의 응답은 기존 값을 재정의 하 여 "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

푸시 OutputBinding 예: 큐 출력 바인딩Push-OutputBinding example: Queue output binding

Push-OutputBindingAzure 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. 이 경우 첫 번째 이후에 다음 예제를 호출 하면 "output #1" 및 "output #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"

다음 예제는 이전 두 번째 이후에 호출 될 때 출력 컬렉션에 두 개의 값을 더 합니다.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"의 네 가지 값을 포함 합니다.When written to the queue, the message contains these four values: "output #1", "output #2", "output #3", and "output #4".

Get-OutputBinding cmdletGet-OutputBinding cmdlet

@No__t_0 cmdlet을 사용 하 여 출력 바인딩에 대해 현재 설정 된 값을 검색할 수 있습니다.You can use the Get-OutputBinding cmdlet to retrieve the values currently set for your output bindings. 이 cmdlet은 해당 값을 사용 하 여 출력 바인딩의 이름을 포함 하는 해시 테이블을 검색 합니다.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. 로깅 cmdlet을 사용 하 여 각 출력 스트림에 쓸 수 있습니다.You can use the logging cmdlets to write to each output stream. 각 cmdlet은 함수에서 사용 하는 로그 수준에 매핑됩니다.Each cmdlet maps to a log level used by Functions.

함수 로깅 수준Functions logging level 로깅 cmdletLogging cmdlet
오류Error Write-Error
경고Warning Write-Warning
정보Information Write-Information
Write-Host
Write-Output
정보Information 정보 수준 로깅에 씁니다.Writes to Information level logging.
디버그Debug Write-Debug
추적Trace Write-Progress
Write-Verbose

이러한 cmdlet 외에도 파이프라인에 쓰여진 모든 항목은 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.

중요

@No__t_0 또는 Write-Debug cmdlet을 사용 하는 것 만으로는 자세한 정보와 디버그 수준 로깅을 볼 수 없습니다.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:

  • 테이블Hashtable
  • 문자열string
  • byte[]byte[]
  • intint
  • Doubledouble
  • HttpRequestContextHttpRequestContext
  • HttpResponseContextHttpResponseContext

이 목록에서 처음 5 개 형식은 표준 .NET 형식입니다.The first five types in this list are standard .NET types. 마지막 두 개는 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, 웹후크 트리거 및 HTTP 출력 바인딩은 요청 및 응답 개체를 사용하여 HTTP 메시지를 나타냅니다.HTTP and webhook triggers and HTTP output bindings use request and response objects to represent the HTTP messaging.

요청 개체Request object

스크립트에 전달 되는 request 개체는 다음 속성을 포함 하는 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 인 경우 hashtable로 전달 됩니다.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>*
Method 요청의 HTTP 메서드입니다.The HTTP method of the request. 문자열string
Params 요청의 라우팅 매개 변수를 포함하는 개체입니다.An object that contains the routing parameters of the request. 사전 < 문자열, 문자열 > *Dictionary<string,string>*
Query 쿼리 매개 변수를 포함하는 개체입니다.An object that contains the query parameters. 사전 < 문자열, 문자열 > *Dictionary<string,string>*
Url 요청의 URL입니다.The URL of the request. 문자열string

* 모든 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. 문자열string
Headers 응답 헤더를 포함하는 개체입니다.An object that contains the response headers. 사전 또는 해시 테이블Dictionary or Hashtable
StatusCode 응답의 HTTP 상태 코드입니다.The HTTP status code of the response. 문자열 또는 intstring 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. @No__t_0 블록에 있습니다.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 프로필에 대해 잘 모르는 경우 프로필 정보를 참조 하세요.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. 기본 프로필은 핵심 도구 GitHub 리포지토리에서 유지 관리 되며 다음을 포함 합니다.The default profile is maintained on the Core Tools GitHub repository and contains:

  • Azure에 대 한 자동 MSI 인증.Automatic MSI authentication to Azure.
  • 원하는 경우 PowerShell 별칭 AzureRM Azure PowerShell을 켜는 기능입니다.The ability to turn on the Azure PowerShell AzureRM PowerShell aliases if you would like.

PowerShell 버전PowerShell version

다음 표에서는 함수 런타임의 각 주 버전에서 사용 하는 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

함수를 사용 하 여 종속성 관리를 위한 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. 다음 예제와 같이 managedDependency 속성을 호스트 json 파일의 루트에 있는 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 함수 프로젝트를 만들 때 종속성 관리는 기본적으로 사용 하도록 설정 되며 Azure 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. 다음 요구 사항에 나와 있는 것 처럼 지원 되는 구문은 .* 또는 정확한 모듈 버전 MajorNumber 됩니다. psd1 예:The supported syntax is MajorNumber.* or exact module version as shown in the following requirements.psd1 example:

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

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 작업자 프로세스는 프로세스 시작 시와 그 이후의 모든 MDMaxBackgroundUpgradePeriod에서 PowerShell 갤러리에 대 한 모듈 업그레이드 검사를 시작 합니다.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. @No__t_0 내에서 전체 PowerShell 작업자를 다시 시작 합니다.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.

함수에서 PSModulePath는 두 개의 경로를 포함 합니다.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. 이 폴더에서 모듈은 함수 런타임에 자동으로 사용할 수 있습니다.From this folder, modules are automatically available to the functions runtime. 함수 앱의 모든 함수는 이러한 모듈을 사용할 수 있습니다.Any function in the function app can use these modules.

참고

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

@No__t_0 폴더를 사용 하는 경우 함수 앱은 다음과 같은 폴더 구조를 가져야 합니다.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.

기본적으로 함수는 이러한 모듈의 최신 버전을 사용 합니다.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

기본적으로 함수 PowerShell 런타임은 한 번에 하나의 함수 호출만 처리할 수 있습니다.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 runspace을 사용 하 여 동시성을 추가할 수 있습니다.However, concurrency can be added by using multiple PowerShell runspaces in the same process. 만든 runspace의 양은 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 함수는 해당 function.json와 동일한 부모 디렉터리를 공유 하는 파일인 run.ps1에서 실행 됩니다.By default, a PowerShell function is executed from run.ps1, a file that shares the same parent directory as its corresponding function.json.

@No__t_1의 scriptFile 속성을 사용 하 여 다음 예제와 같은 폴더 구조를 가져올 수 있습니다.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

이 경우 myFunction에 대 한 function.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. @No__t_0 및 entryPoint 필드를 사용 하 여 모듈에서 특정 함수 코드를 참조할 수 있습니다.You can reference your specific function code in the module by using the scriptFile and entryPoint fields in the function.json` configuration file.

이 경우 entryPointscriptFile에서 참조 되는 PowerShell 모듈에 있는 함수 또는 cmdlet의 이름입니다.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

@No__t_0에는 다음이 포함 됩니다.Where PSFunction.psm1 contains:

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

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

Export-ModuleMember -Function "Invoke-PSTestFunc"

이 예제에서 myFunction에 대 한 구성에는 다른 폴더의 PowerShell 모듈인 PSFunction.psm1를 참조 하는 scriptFile 속성이 포함 되어 있습니다.In this example, the configuration for myFunction includes a scriptFile property that references PSFunction.psm1, which is a PowerShell module in another folder. @No__t_0 속성은 모듈의 진입점 인 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": [
    // ...
  ]
}

이 구성을 사용 하면 Invoke-PSTestFunc run.ps1와 똑같이 실행 됩니다.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.

@No__t_0를 사용 하는 대신 번들 모듈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. 콜드 시작이 함수에 영향을 주는 경우에는 always on 또는 프리미엄 계획으로 설정 된 App Service 계획 에 함수 앱을 배포 하는 것이 좋습니다.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: