Azure Functions 핵심 도구 작업

Azure Functions Core Tools를 사용하면 명령 프롬프트나 터미널에서 함수를 개발하고 테스트할 수 있습니다. 로컬 함수는 라이브 Azure 서비스에 연결할 수 있고 사용자는 전체 Functions 런타임을 사용하여 로컬 머신에서 함수를 디버깅할 수 있습니다. Azure 구독에 함수 앱을 배포할 수도 있습니다.

중요

로컬 개발과 포털 개발을 동일한 함수 앱에 혼합하지 않도록 합니다. 로컬 프로젝트에서 함수를 만들고 게시할 경우 포털에서 프로젝트 코드를 유지하거나 수정하려고 하지 않아야 합니다.

Core Tools를 사용하여 로컬 컴퓨터에서 함수를 개발하고 Azure에 게시하는 작업은 다음과 같은 기본 단계를 따릅니다.

Core Tools 버전

Azure Functions Core Tools에는 세 가지 버전이 있습니다.* 사용하는 버전은 로컬 개발 환경, 선택 언어, 필요한 지원 수준에 따라 달라집니다.

지정된 컴퓨터에는 Core Tools의 한 버전만 설치할 수 있습니다. 별도로 언급하지 않는 한 이 문서의 예제는 3.x 버전용입니다.

* .NET 6.0 미리 보기에서 C# 함수를 실행할 수 있는 Azure Functions의 실험 버전을 사용할 수 있습니다. 자세한 내용은 Azure Functions v4 초기 미리 보기 페이지를 참조하세요.

필수 조건

Azure Functions Core Tools는 현재 Azure 계정으로 인증하기 위해 Azure CLI 또는 Azure PowerShell를 사용합니다. 즉, Azure Functions Core Tools에서 Azure에 게시할 수 있도록 하려면 해당 도구 중 하나를 설치해야 합니다.

Azure Functions 핵심 도구 설치

[Azure Functions 핵심 도구]에는 로컬 개발 컴퓨터에서 실행할 수 있는 Azure Functions 런타임을 제공하는 동일한 런타임 버전이 포함됩니다. 또한 함수를 만들고, Azure에 연결하고, 함수 프로젝트를 배포하는 명령을 제공합니다.

버전 3.x 및 2.x

버전 3.x/2.x 도구는 .NET Core에 빌드된 Azure Functions 런타임을 사용합니다. 이 버전은 Windows, macOSLinux를 포함하여 .NET Core에서 지원하는 모든 플랫폼에서 지원됩니다.

중요

확장 번들을 사용하여 .NET Core SDK를 설치하기 위한 요구 사항을 바이패스할 수 있습니다.

다음 단계에서는 MSI(Windows 설치 프로그램)를 사용하여 Core Tools v3.x를 설치합니다. Core Tools v2.x를 설치하는 데 필요한 다른 패키지 기반 설치 프로그램에 대한 자세한 내용은 Core Tools 추가 정보를 참조하세요.

  1. 다음과 같이 Windows 버전에 따라 Core Tools 설치 프로그램을 다운로드하여 실행합니다.

  2. 확장 번들을 사용하지 않으려는 경우 Windows용 .NET Core 3.x SDK를 설치합니다.

버전 1.x

Windows에서만 실행되는 Core Tools 버전 1.x를 설치해야 하는 경우 자세한 내용은 GitHub 리포지토리를 참조하세요.

로컬 Functions 프로젝트 만들기

Functions 프로젝트 디렉터리에는 언어에 관계없이 다음 파일과 폴더가 포함되어 있습니다.

파일 이름 Description
host.json 자세한 내용은 host.json 참조를 참조하세요.
local.settings.json 앱 설정을 포함하여 로컬에서 실행할 때 핵심 도구에서 사용하는 설정입니다. 자세히 알아보려면 로컬 설정을 참조하세요.
.gitignore local.settings.json 파일이 실수로 Git 리포지토리에 게시되는 것을 방지합니다. 자세히 알아보려면 로컬 설정을 참조하세요.
.vscode\extensions.json Visual Studio Code에서 프로젝트 폴더를 열 때 사용되는 설정 파일입니다.

Functions 프로젝트 폴더에 대한 자세한 내용은 Azure Functions 개발자 가이드를 참조하세요.

터미널 창이나 명령 프롬프트에서 다음 명령을 실행하여 프로젝트 및 로컬 Git 리포지토리를 만듭니다.

func init MyFunctionProj

이 예에서는 새 MyFunctionProj 폴더에 Functions 프로젝트를 만듭니다. 프로젝트의 기본 언어를 선택하라는 메시지가 표시됩니다.

프로젝트 초기화에는 다음 고려 사항이 적용됩니다.

  • 명령에 --worker-runtime 옵션을 제공하지 않으면 언어를 선택하라는 메시지가 표시됩니다. 자세한 내용은 func init 참조를 확인하세요.

  • 프로젝트 이름을 제공하지 않으면 현재 폴더가 초기화됩니다.

  • 프로젝트를 사용자 지정 Linux 컨테이너에 게시하려는 경우 --dockerfile 옵션을 사용하여 프로젝트에 대해 Dockerfile이 생성되었는지 확인합니다. 자세히 알아보려면 사용자 지정 이미지를 사용하여 Linux에서 함수 만들기를 참조하세요.

특정 언어에는 다음과 같은 추가 고려 사항이 있을 수 있습니다.

  • 기본적으로 Core Tools의 버전 2.x 이상 버전은 .NET 런타임에 대한 함수 앱 프로젝트를 C# 클래스 프로젝트(.csproj)로 만듭니다. 버전 3.x는 또한 분리된 프로세스의 .NET 5.0에서 실행하는 함수 만들기를 지원합니다. 이러한 C# 프로젝트는 Visual Studio 또는 Visual Studio Code에서 사용할 수 있으며, 디버그 중과 Azure에 게시할 때 컴파일됩니다.

  • C# 스크립트(.csx) 파일로 로컬에서 작업하려면 --csx 매개 변수를 사용합니다. Azure Portal에서 함수를 만들 때와 Core Tools 버전 1.x를 사용할 때 가져오는 동일한 파일입니다. 자세한 내용은 func init 참조를 참조하세요.

확장 등록

런타임 버전 2.x부터 Functions 바인딩은 .NET 확장(NuGet) 패키지로 구현됩니다. 컴파일된 C# 프로젝트의 경우 사용 중인 특정 트리거 및 바인딩에 대한 NuGet 확장 패키지를 참조하기만 하면 됩니다. HTTP 바인딩 및 타이머 트리거에는 확장이 필요하지 않습니다.

C#이 아닌 프로젝트의 개발 환경을 개선하기 위해 Functions를 사용하면 host.json 프로젝트 파일에서 버전이 지정된 확장 번들을 참조할 수 있습니다. 확장 번들은 앱에서 모든 확장을 사용할 수 있도록 하고 확장 간에 패키지 호환성 문제가 발생할 가능성을 제거합니다. 확장 번들은 .NET Core 2.x SDK를 설치하고 extension.csproj 파일을 처리해야 하는 요구 사항도 제거합니다.

확장 번들은 C# 호환 프로젝트 이외의 Functions 프로젝트에 권장되는 접근 방식입니다. 이러한 프로젝트의 경우 초기화 중에 확장 번들 설정이 host.json 파일에 생성됩니다. 이것이 작동한다면 이 전체 섹션을 건너뛸 수 있습니다.

확장 번들 사용

바인딩 확장을 설치하는 가장 쉬운 방법은 확장 번들을 사용하도록 설정하는 것입니다. 번들을 활성화하면 미리 정의된 확장 패키지 세트가 자동으로 설치됩니다.

확장 번들을 사용하도록 설정하려면 host.json 파일을 열고 다음 코드와 일치하도록 콘텐츠를 업데이트합니다.

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[1.*, 2.0.0)"
    }
}

사용자 언어에서 지원하는 경우 func init를 호출한 후 확장 번들이 이미 사용하도록 설정되어 있어야 합니다. function.json 파일에 바인딩을 추가하기 전에 host.json에 확장 번들을 추가해야 합니다. 자세한 내용은 Azure Functions 바인딩 확장 등록을 참조하세요.

명시적으로 확장 설치

번들에 없는 특정 버전의 확장을 대상으로 지정해야 하는 경우와 같이 확장 번들을 사용할 수 없는 비 .NET 프로젝트의 경우가 있을 수 있습니다. 자주 발생하지는 않지만 핵심 도구를 사용하여 프로젝트에 필요한 특정 확장 패키지를 로컬로 설치할 수 있습니다. 자세한 내용은 명시적으로 확장 설치를 참조하세요.

로컬 설정

Azure의 함수 앱에서 실행하는 경우 함수에 필요한 설정은 앱 설정에 안전하게 저장됩니다. 로컬 개발 중에 이러한 설정은 local.settings.json 파일의 Values 개체에 대신 추가됩니다. local.settings.json 파일은 로컬 개발 도구에서 사용하는 설정도 저장합니다.

local.settings.json에는 연결 문자열과 같은 비밀이 포함될 수 있으므로 원격 리포지토리에 저장해서는 안 됩니다. 로컬 설정에 대해 자세히 알아보려면 로컬 설정 파일을 참조하세요.

기본적으로 이러한 설정은 프로젝트가 Azure에 게시될 때 자동으로 마이그레이션되지 않습니다. 게시할 때 --publish-local-settings 옵션을 사용하여 이러한 설정이 Azure의 함수 앱에 추가되었는지 확인합니다. ConnectionStrings 섹션의 값은 게시되지 않습니다.

이 함수 앱 설정 값은 코드에서 환경 변수로 읽을 수도 있습니다. 자세한 내용은 다음 언어별 참조 항목의 Environment 변수 섹션을 참조하세요.

AzureWebJobsStorage에 유효한 스토리지 연결 문자열이 설정되어 있지 않고 에뮬레이터가 사용되지 않으면, 다음 오류 메시지가 표시됩니다.

local.settings.json에 AzureWebJobsStorage 값이 없습니다. 이 값은 HTTP 이외의 모든 트리거에 필요합니다. 'func azure functionapp fetch-app-settings <functionAppName>'를 실행하거나 local.settings.json에서 연결 문자열을 지정할 수 있습니다.

스토리지 연결 문자열 가져오기

개발에 Microsoft Azure Storage 에뮬레이터를 사용하는 경우에도 실제 스토리지를 연결하여 로컬로 실행하는 것이 좋을 수 있습니다. 이미 스토리지 계정을 만든 것으로 가정하면 몇 가지 방법 중 하나에서 유효한 스토리지 연결 문자열을 가져올 수 있습니다.

  1. Azure Portal에서 스토리지 계정 을 검색하여 선택합니다.

    Azure Portal에서 스토리지 계정 선택

  2. 스토리지 계정을 선택하고, 설정 에서 액세스 키 를 선택한 다음, 연결 문자열 값 중 하나를 복사합니다.

    Azure Portal에서 연결 문자열 복사

함수 만들기

기존 프로젝트에서 함수를 만들려면 다음 명령을 실행합니다.

func new

버전 3.x/2.x에서 func new를 실행하면 함수 앱의 기본 언어로 템플릿을 선택하라는 메시지가 표시됩니다. 다음으로 함수의 이름을 선택하라는 메시지가 표시됩니다. 버전 1.x에서는 언어를 선택하라고 요청합니다.

func new 명령에서 함수 이름과 템플릿을 지정할 수도 있습니다. 다음 예에서는 --template 옵션을 사용하여 MyHttpTrigger라는 HTTP 트리거를 만듭니다.

func new --template "Http Trigger" --name MyHttpTrigger

이 예에서는 MyQueueTrigger라는 Queue Storage 트리거를 만듭니다.

func new --template "Queue Trigger" --name MyQueueTrigger

자세한 내용은 func new 명령을 참조하세요.

로컬로 함수 실행

Functions 프로젝트를 실행하려면 프로젝트의 루트 디렉터리에서 Functions 호스트를 실행합니다. 해당 호스트는 프로젝트의 모든 함수에 대한 트리거를 사용하는 것으로 설정합니다. start 명령은 프로젝트 언어에 따라 달라집니다.

func start

참고

Functions 런타임 버전 1.x에는 대신 func host start가 필요합니다. 자세한 내용은 Azure Functions Core Tools 참조를 참조하세요.

Functions 호스트가 시작되면 다음 예와 같이 HTTP 트리거 함수의 URL을 출력합니다.

Found the following functions:
Host.Functions.MyHttpTrigger

Job host started
Http Function MyHttpTrigger: http://localhost:7071/api/MyHttpTrigger

중요

로컬로 실행하는 경우 HTTP 엔드포인트에 대한 권한 부여는 실행되지 않습니다. 즉, 모든 로컬 HTTP 요청은 authLevel = "anonymous"로 처리됩니다. 자세한 내용은 HTTP 바인딩 문서를 참조하세요.

테스트 데이터를 함수에 전달

로컬로 함수를 테스트하려면 Functions 호스트를 시작하고 HTTP 요청을 사용하여 로컬 서버에서 엔드포인트를 호출합니다. 호출하는 엔드포인트는 함수의 형식에 따라 달라집니다.

참고

이 항목의 예제에서는 cURL 도구를 사용하여 터미널 또는 명령 프롬프트의 HTTP 요청을 보냅니다. 로컬 서버에 HTTP 요청을 보내도록 선택한 도구를 사용할 수 있습니다. cURL 도구는 Linux 기반 시스템 및 Windows 10 빌드 17063 이상에서 기본적으로 사용할 수 있습니다. Windows에서는 먼저 cURL 도구를 다운로드한 후 설치해야 합니다.

함수를 테스트하는 방법에 대한 일반적인 내용은 Azure Functions에서 코드를 테스트하기 위한 전략을 참조하세요.

HTTP 및 웹후크 트리거된 함수

다음 엔드포인트를 호출하여 HTTP 및 웹후크 트리거된 함수를 로컬로 실행합니다.

http://localhost:{port}/api/{function_name}

Functions 호스트가 수신 대기 중인 동일한 서버 이름 및 포트를 사용하도록 합니다. Function 호스트를 시작할 때 생성된 출력에서 이 항목을 확인합니다. 트리거에서 지원하는 HTTP 메서드를 사용하여 이 URL을 호출할 수 있습니다.

다음 cURL 명령은 이름 매개 변수를 쿼리 문자열에 전달한 GET 요청에서 MyHttpTrigger 빠른 시작 함수를 트리거합니다.

curl --get http://localhost:7071/api/MyHttpTrigger?name=Azure%20Rocks

다음 예제는 요청 본문에서 이름 을 전달하는 POST 요청에서 호출되는 동일한 함수입니다.

curl --request POST http://localhost:7071/api/MyHttpTrigger --data '{"name":"Azure Rocks"}'

쿼리 문자열에서 데이터를 전달하는 브라우저에서 GET 요청을 수행할 수 있습니다. 다른 모든 HTTP 메서드에서 POST 요청을 지원하는 cURL, Fiddler, Postman 또는 비슷한 HTTP 테스트 도구를 사용해야 합니다.

HTTP가 아닌 트리거된 함수

HTTP 및 Event Grid 트리거를 제외한 모든 함수의 경우 관리 엔드포인트 라는 특수 엔드포인트를 호출하여 REST를 사용하여 로컬에서 함수를 테스트할 수 있습니다. 로컬 서버에서 HTTP POST 요청으로 이 엔드포인트를 호출하면 함수를 트리거합니다.

로컬로 Event Grid 트리거된 함수를 테스트하려면 뷰어 웹앱을 사용하여 로컬 테스트를 참조하세요.

필요에 따라 POST 요청의 본문에서 실행에 테스트 데이터를 전달할 수 있습니다. 이 기능은 Azure Portal에서 테스트 탭과 비슷합니다.

다음 관리자 엔드포인트를 호출하여 HTTP가 아닌 함수를 트리거합니다.

http://localhost:{port}/admin/functions/{function_name}

함수의 관리자 엔드포인트에 테스트 데이터를 전달하려면 POST 요청 메시지의 본문에서 데이터를 제공해야 합니다. 메시지 본문에는 다음 JSON 형식이 필요합니다.

{
    "input": "<trigger_input>"
}

<trigger_input> 값에는 함수에 필요한 형식의 데이터가 포함됩니다. 다음 cURL 예제는 QueueTriggerJS 함수에 대한 POST 요청입니다. 이 경우에 입력은 큐에 위치해야 하는 메시지에 해당하는 문자열입니다.

curl --request POST -H "Content-Type:application/json" --data '{"input":"sample queue data"}' http://localhost:7071/admin/functions/QueueTrigger

Azure의 함수 앱에서 관리자 엔드포인트를 호출할 때 액세스 키를 제공해야 합니다. 자세한 내용은 함수 액세스 키를 참조하세요.

Azure에 게시

Azure Functions Core Tools는 세 가지 배포 유형을 지원합니다.

배포 유형 명령 설명
프로젝트 파일 func azure functionapp publish zip 배포를 사용하여 함수 프로젝트 파일을 함수 앱에 직접 배포합니다.
사용자 지정 컨테이너 func deploy 프로젝트를 Linux 함수 앱에 사용자 지정 Docker 컨테이너로 배포합니다.
Kubernetes 클러스터 func kubernetes deploy Linux 함수 앱을 Kubernetes 클러스터에 고객 Docker 컨테이너로 배포합니다.

게시하기 전에

중요

Core Tools에서 Azure에 게시하려면 Azure CLI 또는 Azure PowerShell을 로컬로 설치해야 합니다.

프로젝트 폴더는 게시하지 않아야 하는 언어별 파일 및 디렉터리를 포함할 수 있습니다. 제외된 항목은 루트 프로젝트 폴더의 .funcignore 파일에 나열됩니다.

코드를 배포할 Azure 구독에서 생성된 함수 앱이 이미 있어야 합니다. 컴파일해야 하는 프로젝트는 이진 파일을 배포할 수 있는 방식으로 빌드해야 합니다.

Azure CLI 또는 Azure PowerShell을 사용하여 명령 프롬프트 또는 터미널 창에서 함수 앱을 만드는 방법을 알아보려면 서버리스 실행을 위한 함수 앱 만들기를 참조하세요.

중요

Azure Portal에서 함수 앱을 만들 때는 기본적으로 Function 런타임 버전 3.x가 사용됩니다. 함수 앱이 런타임 버전 1.x를 사용하도록 하려면 버전 1.x에서 실행의 지침을 따르세요. 기존 함수가 있는 함수 앱의 런타임 버전은 변경할 수 없습니다.

프로젝트 파일 배포

Azure의 함수 앱에 로컬 코드를 게시하려면 publish 명령을 사용합니다.

func azure functionapp publish <FunctionAppName>

이러한 종류의 배포에는 다음 고려 사항이 적용됩니다.

  • 게시하면 함수 앱의 기존 파일을 덮어씁니다.

  • --publish-local-settings 옵션을 사용하여 local.settings.json 파일의 값을 기반으로 함수 앱에서 앱 설정을 자동으로 만듭니다.

  • 컴파일된 프로젝트에서 원격 빌드가 수행됩니다. 이는 --no-build 옵션을 사용하여 제어할 수 있습니다.

  • 프로젝트는 배포 패키지에서 실행되도록 배포됩니다. 권장 배포 모드를 사용하지 않도록 설정하려면 --nozip 옵션을 사용합니다.

  • Java는 Maven을 사용하여 로컬 프로젝트를 Azure에 게시합니다. 대신 mvn azure-functions:deploy 명령을 사용하여 Azure에 게시합니다. Azure 리소스는 초기 배포 중에 생성됩니다.

  • 구독에 존재하지 않는 <FunctionAppName>에 게시하려고 하면 오류가 발생합니다.

Kubernetes 클러스터

Functions를 사용하면 Docker 컨테이너에서 실행할 Functions 프로젝트를 정의할 수도 있습니다. func init--docker 옵션을 사용하여 특정 언어에 대한 Dockerfile을 생성합니다. 이 파일은 배포할 컨테이너를 만들 때 사용됩니다.

핵심 도구를 사용하여 프로젝트를 Kubernetes 클러스터에 사용자 지정 컨테이너 이미지로 배포할 수 있습니다. 사용하는 명령은 클러스터에서 사용되는 배율 조정기 유형에 따라 다릅니다.

다음 명령은 Dockerfile을 사용하여 컨테이너를 생성하고 Kubernetes 클러스터에 배포합니다.

func kubernetes deploy --name <DEPLOYMENT_NAME> --registry <REGISTRY_USERNAME> 

자세한 내용은 Kubernetes에 함수 앱 배포를 참조하세요.

Kubernetes 없이 Azure에 사용자 지정 컨테이너를 게시하는 방법을 알아보려면 사용자 지정 컨테이너를 사용하여 Linux에서 함수 만들기를 참조하세요.

함수 모니터링

함수 실행을 모니터링할 때는 Azure Application Insights와 함수를 통합하는 방식을 사용하는 것이 좋습니다. 실행 로그를 로컬 컴퓨터로 스트림할 수도 있습니다. 자세히 알아보려면 Azure Functions 모니터링을 참조하세요.

Application Insights 통합

Azure에서 함수 앱을 만들 때 Application Insights 통합을 사용하도록 설정해야 합니다. 일부 이유로 함수 앱이 Application Insights 인스턴스에 연결되지 않은 경우 Azure Portal에서 이 통합을 쉽게 수행할 수 있습니다. 자세한 정보를 알아보려면 Application Insights 통합 사용을 참조하세요.

스트리밍 로그 사용

로컬 컴퓨터의 명령줄 세션에서 함수로 생성되는 로그 파일의 스트림을 볼 수 있습니다.

기본 제공 로그 스트리밍

다음 예제와 같이 func azure functionapp logstream 명령을 사용하여 Azure에서 실행 중인 특정 함수 앱의 스트리밍 로그 수신을 시작합니다.

func azure functionapp logstream <FunctionAppName>

참고

기본 제공 로그 스트리밍은 사용 계획의 Linux에서 실행되는 함수 앱의 핵심 도구에서 아직 사용하도록 설정되지 않습니다. 이러한 호스팅 계획의 경우 라이브 메트릭 스트림을 대신 사용하여 로그를 거의 실시간으로 볼 수 있어야 합니다.

라이브 메트릭 스트림

다음 예제와 같이 --browser 옵션을 포함하여 새 브라우저 창에서 함수 앱에 대한 라이브 메트릭 스트림을 볼 수도 있습니다.

func azure functionapp logstream <FunctionAppName> --browser

이 유형의 스트리밍 로그에는 함수 앱에 대한 Application Insights 통합을 사용하도록 설정해야 합니다.

다음 단계

Azure Functions Core Tools Microsoft 학습 모듈을 사용하여 Azure Functions를 개발, 테스트 및 게시하는 방법을 알아보세요. Azure Functions Core Tools는 오픈 소스이며 GitHub에서 호스트됩니다.
버그 또는 기능 요청을 제출하려면 GitHub 문제를 개설합니다.