Azure Functions HTTP 트리거

HTTP 트리거를 사용하면 HTTP 요청으로 함수를 호출할 수 있습니다. HTTP 트리거를 사용하여 서버리스 API를 빌드하고 웹후크에 응답할 수 있습니다.

HTTP 트리거 함수의 기본 반환 값은 다음과 같습니다.

  • HTTP 204 No Content Functions 2.x 이상에서 빈 본문 포함
  • Functions 1.x에서 빈 본문이 있는 HTTP 200 OK

HTTP 응답을 수정하려면 출력 바인딩을 구성합니다.

HTTP 바인딩에 대한 자세한 내용은 개요 및 출력 바인딩 참조를 참조하세요.

HTTP 또는 WebHook를 사용할 계획인 경우 HttpClient의 부적절한 인스턴스화로 인해 발생할 수 있는 포트 소모를 피하도록 계획합니다. 자세한 내용은 Azure Functions에서 연결을 관리하는 방법을 참조하세요.

Important

이 문서에서는 탭을 사용하여 여러 버전의 Node.js 프로그래밍 모델을 지원합니다. v4 모델은 일반적으로 사용 가능하며 JavaScript 및 TypeScript 개발자를 위해 보다 유연하고 직관적인 환경을 제공하도록 설계되었습니다. v4 모델의 작동 방식에 대한 자세한 내용은 Azure Functions Node.js 개발자 가이드를 참조하세요. v3과 v4의 차이점에 대해 자세히 알아보려면 마이그레이션 가이드를 참조하세요.

Azure Functions는 Python용 두 가지 프로그래밍 모델을 지원합니다. 바인딩을 정의하는 방법은 선택한 프로그래밍 모델에 따라 달라집니다.

Python v2 프로그래밍 모델을 사용하면 Python 함수 코드에서 직접 데코레이터를 사용하여 바인딩을 정의할 수 있습니다. 자세한 내용은 Python 개발자 가이드참조하세요.

이 문서에서는 두 프로그래밍 모델을 모두 지원합니다.

예시

C# 함수는 다음 C# 모드 중 하나를 사용하여 만들 수 있습니다.

  • 격리된 작업자 모델: 런타임에서 격리된 작업자 프로세스에서 실행되는 컴파일된 C# 함수입니다. LTS 및 비 LTS 버전 .NET 및 .NET Framework에서 실행되는 C# 함수를 지원하려면 격리된 작업자 프로세스가 필요합니다. 격리된 작업자 프로세스 함수에 대한 확장은 Microsoft.Azure.Functions.Worker.Extensions.* 네임스페이스를 사용합니다.
  • In Process 모델: Functions 런타임과 동일한 프로세스에서 실행되는 컴파일된 C# 함수입니다. 이 모델의 변형에서는 주로 C# 포털 편집에 지원되는 C# 스크립팅을 사용하여 Functions를 실행할 수 있습니다. In Process 함수에 대한 확장은 Microsoft.Azure.WebJobs.Extensions.* 네임스페이스를 사용합니다.

이 문서의 코드는 기본적으로 Functions 버전 2.x 이상에서 사용되는 .NET Core 구문으로 설정됩니다. 1.x 구문에 대한 자세한 내용은 1.x 함수 템플릿을 참조 하세요.

다음 예에서는 .NET 격리의 ASP.NET Core 통합을 사용하여 "hello, world" 응답을 IActionResult로 반환하는 HTTP 트리거를 보여 줍니다.

[Function("HttpFunction")]
public IActionResult Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get")] HttpRequest req)
{
    return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
}

다음 예제에서는 “hello world” 응답을 HttpResponseData 개체로 반환하는 HTTP 트리거를 보여 줍니다.

[Function(nameof(HttpFunction))]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger(nameof(HttpFunction));
    logger.LogInformation("message logged");

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString("Welcome to .NET isolated worker !!");

    return response;
}

이 섹션에는 다음 예제가 포함되어 있습니다.

다음 예제에서는 HTTP 트리거 바인딩을 보여 줍니다.

쿼리 문자열에서 매개 변수 읽기

이 예제에서는 쿼리 문자열에서 id라는 매개 변수를 읽고 이 매개 변수를 사용하여 콘텐츠 형식 application/json으로 클라이언트에 반환되는 JSON 문서를 빌드합니다.

@FunctionName("TriggerStringGet")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", 
            methods = {HttpMethod.GET}, 
            authLevel = AuthorizationLevel.ANONYMOUS)
        HttpRequestMessage<Optional<String>> request,
        final ExecutionContext context) {

    // Item list
    context.getLogger().info("GET parameters are: " + request.getQueryParameters());

    // Get named parameter
    String id = request.getQueryParameters().getOrDefault("id", "");

    // Convert and display
    if (id.isEmpty()) {
        return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                        .body("Document not found.")
                        .build();
    } 
    else {
        // return JSON from to the client
        // Generate document
        final String name = "fake_name";
        final String jsonDocument = "{\"id\":\"" + id + "\", " + 
                                        "\"description\": \"" + name + "\"}";
        return request.createResponseBuilder(HttpStatus.OK)
                        .header("Content-Type", "application/json")
                        .body(jsonDocument)
                        .build();
    }
}

POST 요청에서 본문 읽기

이 예제에서는 POST 요청의 본문을 a String로 읽고 이를 사용하여 콘텐츠 형식 application/json으로 클라이언트에 반환된 JSON 문서를 빌드합니다.

    @FunctionName("TriggerStringPost")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", 
              methods = {HttpMethod.POST}, 
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Request body is: " + request.getBody().orElse(""));

        // Check request body
        if (!request.getBody().isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        } 
        else {
            // return JSON from to the client
            // Generate document
            final String body = request.getBody().get();
            final String jsonDocument = "{\"id\":\"123456\", " + 
                                         "\"description\": \"" + body + "\"}";
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(jsonDocument)
                          .build();
        }
    }

경로에서 매개 변수 읽기

이 예제에서는 경로 경로에서 필수 매개 변수와 선택 id적 매개 변수 name 를 읽고 이를 사용하여 콘텐츠 형식 application/json을 사용하여 클라이언트에 반환된 JSON 문서를 작성합니다.

@FunctionName("TriggerStringRoute")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", 
            methods = {HttpMethod.GET}, 
            authLevel = AuthorizationLevel.ANONYMOUS,
            route = "trigger/{id}/{name=EMPTY}") // name is optional and defaults to EMPTY
        HttpRequestMessage<Optional<String>> request,
        @BindingName("id") String id,
        @BindingName("name") String name,
        final ExecutionContext context) {

    // Item list
    context.getLogger().info("Route parameters are: " + id);

    // Convert and display
    if (id == null) {
        return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                        .body("Document not found.")
                        .build();
    } 
    else {
        // return JSON from to the client
        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " + 
                                        "\"description\": \"" + name + "\"}";
        return request.createResponseBuilder(HttpStatus.OK)
                        .header("Content-Type", "application/json")
                        .body(jsonDocument)
                        .build();
    }
}

POST 요청에서 POJO 본문 읽기

다음은 이 예제에서 참조되는 ToDoItem 클래스의 코드입니다.


public class ToDoItem {

  private String id;
  private String description;  

  public ToDoItem(String id, String description) {
    this.id = id;
    this.description = description;
  }

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

이 예제에서는 POST 요청의 본문을 읽습니다. 요청 본문은 자동으로 개체로 ToDoItem 직렬화 해제되고 콘텐츠 형식 application/json을 사용하여 클라이언트로 반환됩니다. ToDoItem 매개 변수는 클래스의 HttpMessageResponse.Builder 속성에 할당되므로 Functions 런타임에 body 의해 serialize됩니다.

@FunctionName("TriggerPojoPost")
public HttpResponseMessage run(
        @HttpTrigger(name = "req", 
            methods = {HttpMethod.POST}, 
            authLevel = AuthorizationLevel.ANONYMOUS)
        HttpRequestMessage<Optional<ToDoItem>> request,
        final ExecutionContext context) {

    // Item list
    context.getLogger().info("Request body is: " + request.getBody().orElse(null));

    // Check request body
    if (!request.getBody().isPresent()) {
        return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                        .body("Document not found.")
                        .build();
    } 
    else {
        // return JSON from to the client
        // Generate document
        final ToDoItem body = request.getBody().get();
        return request.createResponseBuilder(HttpStatus.OK)
                        .header("Content-Type", "application/json")
                        .body(body)
                        .build();
    }
}

다음 예에서는 HTTP 트리거 TypeScript 함수를 보여 줍니다. 함수는 쿼리 문자열 또는 HTTP 요청의 본문에서 매개 변수를 찾 name 습니다.

import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    context.log(`Http function processed request for url "${request.url}"`);

    const name = request.query.get('name') || (await request.text()) || 'world';

    return { body: `Hello, ${name}!` };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: httpTrigger1,
});

다음 예에서는 HTTP 트리거 JavaScript 함수를 보여 줍니다. 함수는 쿼리 문자열 또는 HTTP 요청의 본문에서 매개 변수를 찾 name 습니다.

const { app } = require('@azure/functions');

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        context.log(`Http function processed request for url "${request.url}"`);

        const name = request.query.get('name') || (await request.text()) || 'world';

        return { body: `Hello, ${name}!` };
    },
});

다음 예제에서는 function.json 파일의 트리거 바인딩 및 PowerShell 함수보여줍니다. 함수는 쿼리 문자열 또는 HTTP 요청의 본문에서 매개 변수를 찾 name 습니다.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    }
  ]
}
using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$name = $Request.Query.Name
if (-not $name) {
    $name = $Request.Body.Name
}

$body = "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."

if ($name) {
    $body = "Hello, $name. This HTTP triggered function executed successfully."
}

# Associate values to output bindings by calling 'Push-OutputBinding'.
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body       = $body
})

다음 예제에서는 바인딩을 사용하는 트리거 바인딩 및 Python 함수를 보여줍니다. 함수는 쿼리 문자열 또는 HTTP 요청의 본문에서 매개 변수를 찾 name 습니다. 이 예제는 v1 또는 v2 Python 프로그래밍 모델을 사용하는지 여부에 따라 달라집니다.

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
def test_function(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')
    return func.HttpResponse(
        "This HTTP triggered function executed successfully.",
        status_code=200
        )

특성

In Process격리된 작업자 프로세스 C# 라이브러리는 모두 HttpTriggerAttribute를 사용하여 트리거 바인딩을 정의합니다. 대신 C# 스크립트는 C# 스크립팅 가이드에 설명된 대로 function.json 구성 파일을 사용합니다.

격리된 작업자 프로세스 함수 앱에서 HttpTriggerAttribute는 다음 매개 변수를 지원합니다.

매개 변수 설명
AuthLevel 함수를 호출하기 위해 요청에 있어야 하는 키(있는 경우)를 결정합니다. 지원되는 값은 권한 부여 수준을 참조하세요.
메서드 함수에서 응답할 HTTP 메서드의 배열입니다. 지정하지 않으면 함수는 모든 HTTP 메서드에 응답합니다. HTTP 엔드포인트 사용자 지정을 참조하세요.
Route 함수가 응답하는 요청 URL을 제어하는 경로 템플릿을 정의합니다. 제공되지 않는 경우 기본값은 .입니다 <functionname>. 자세한 내용은 HTTP 엔드포인트 사용자 지정을 참조하세요.

데코레이터

Python v2 프로그래밍 모델에만 적용됩니다.

데코레이터를 사용하여 정의된 Python v2 함수의 경우 트리거에 대한 다음 속성이 데코레이터에 route 정의되어 HttpTrigger 및 HttpOutput 바인딩을 추가합니다.

속성 설명
route http 엔드포인트에 대한 경로입니다. None이면 함수 이름이 있거나 사용자가 정의한 python 함수 이름이면 함수 이름으로 설정됩니다.
trigger_arg_name HttpRequest의 인수 이름입니다. 기본값은 'req'입니다.
binding_arg_name HttpResponse의 인수 이름입니다. 기본값은 '$return'입니다.
methods 함수가 응답하는 HTTP 메서드의 튜플입니다.
auth_level 함수를 호출하기 위해 요청에 있어야 하는 키(있는 경우)를 결정합니다.

function.json 사용하여 정의된 Python 함수는 구성 섹션을 참조하세요.

주석

Java 함수 런타임 라이브러리에서 다음 설정을 지원하는 HttpTrigger 주석을 사용합니다.

구성

Python v1 프로그래밍 모델에만 적용됩니다.

다음 표에서는 app.http() 메서드에 전달된 options 개체에 설정할 수 있는 속성에 대해 설명합니다.

속성 설명
authLevel 함수를 호출하기 위해 요청에 있어야 하는 키(있는 경우)를 결정합니다. 지원되는 값은 권한 부여 수준을 참조하세요.
메서드 함수에서 응답할 HTTP 메서드의 배열입니다. 지정하지 않으면 함수는 모든 HTTP 메서드에 응답합니다. HTTP 엔드포인트 사용자 지정을 참조하세요.
route 함수가 응답하는 요청 URL을 제어하는 경로 템플릿을 정의합니다. 제공되지 않는 경우 기본값은 .입니다 <functionname>. 자세한 내용은 HTTP 엔드포인트 사용자 지정을 참조하세요.

다음 표에서는 런타임 버전에 따라 다른 function.json 파일에서 설정하는 트리거 구성 속성을 설명합니다.

다음 표에서는 function.json 파일에 설정한 바인딩 구성 속성에 대해 설명합니다.

function.json 속성 설명
type 필수 - 로 설정 httpTrigger해야 합니다.
direction 필수 - 로 설정 in해야 합니다.
이름 필수 - 요청 또는 요청 본문의 함수 코드에 사용되는 변수 이름입니다.
authLevel 함수를 호출하기 위해 요청에 있어야 하는 키(있는 경우)를 결정합니다. 지원되는 값은 권한 부여 수준을 참조하세요.
메서드 함수에서 응답할 HTTP 메서드의 배열입니다. 지정하지 않으면 함수는 모든 HTTP 메서드에 응답합니다. HTTP 엔드포인트 사용자 지정을 참조하세요.
route 함수가 응답하는 요청 URL을 제어하는 경로 템플릿을 정의합니다. 제공되지 않는 경우 기본값은 .입니다 <functionname>. 자세한 내용은 HTTP 엔드포인트 사용자 지정을 참조하세요.

사용

이 섹션에서는 HTTP 트리거 함수 바인딩을 구성하는 방법을 자세히 설명합니다.

HttpTrigger 주석은 다음 형식 중 하나의 메서드 매개 변수에 적용해야 합니다.

  • HttpRequestMessage<T>.
  • int, String, byte[]와 같은 모든 네이티브 Java 형식.
  • 선택적 값을 사용하는 null 허용 값.
  • POJO(Plain Old Java Object) 형식.

페이로드

트리거 입력 형식은 다음 형식 중 하나로 선언됩니다.

Type 설명
HttpRequest 이 형식을 사용하려면 앱이 .NET 격리의 ASP.NET Core 통합으로 구성되어야 합니다.
이렇게 하면 요청 개체와 전체 HttpContext에 대한 모든 권한이 제공됩니다.
HttpRequestData 요청 개체의 프로젝션입니다.
사용자 지정 형식 요청 본문이 JSON인 경우 런타임은 개체 속성을 설정하기 위해 이를 구문 분석하려고 시도합니다.

트리거 매개 변수가 인 HttpRequestDataHttpRequest경우 사용자 지정 형식을 사용하여 Microsoft.Azure.Functions.Worker.Http.FromBodyAttribute추가 매개 변수에 바인딩할 수도 있습니다. 이 특성을 사용하려면 Microsoft.Azure.Functions.Worker.Extensions.Http 버전 3.1.0 이상이 필요합니다. 이는 Microsoft.AspNetCore.Mvc의 유사한 특성과 다른 형식이며 ASP.NET Core 통합을 사용하는 경우 정규화된 참조 또는 using 문이 필요합니다. 다음 예에서는 ASP.NET Core 통합을 사용하여 전체 HttpRequest에 계속 액세스하면서 본문 콘텐츠만 가져오는 특성을 사용하는 방법을 보여 줍니다.

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using FromBodyAttribute = Microsoft.Azure.Functions.Worker.Http.FromBodyAttribute;

namespace AspNetIntegration
{
    public class BodyBindingHttpTrigger
    {
        [Function(nameof(BodyBindingHttpTrigger))]
        public IActionResult Run([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequest req,
            [FromBody] Person person)
        {
            return new OkObjectResult(person);
        }
    }

    public record Person(string Name, int Age);
}

HTTP 엔드포인트 사용자 지정

기본적으로 HTTP 트리거에 대한 함수를 만들 때 함수는 양식의 경로로 주소를 지정할 수 있습니다.

http://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>

HTTP 트리거의 입력 바인딩에서 선택적 route 속성을 사용하여 이 경로를 사용자 지정할 수 있습니다. 매개 변수에서 웹 API 경로 제약 조건을 사용할 수 있습니다.

다음 함수 코드는 경로에서 두 개의 매개 변수 categoryid를 허용하고 두 매개 변수를 모두 사용하여 응답을 작성합니다.

[Function("HttpTrigger1")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Function, "get", "post",
Route = "products/{category:alpha}/{id:int?}")] HttpRequestData req, string category, int? id,
FunctionContext executionContext)
{
    var logger = executionContext.GetLogger("HttpTrigger1");
    logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = String.Format($"Category: {category}, ID: {id}");
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString(message);

    return response;
}

경로 매개 변수는 HttpTrigger 주석의 route 설정을 사용하여 정의합니다. 다음 함수 코드는 경로에서 두 개의 매개 변수 categoryid를 허용하고 두 매개 변수를 모두 사용하여 응답을 작성합니다.

package com.function;

import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerJava {
    public HttpResponseMessage<String> HttpTrigger(
            @HttpTrigger(name = "req",
                         methods = {"get"},
                         authLevel = AuthorizationLevel.FUNCTION,
                         route = "products/{category:alpha}/{id:int}") HttpRequestMessage<String> request,
            @BindingName("category") String category,
            @BindingName("id") int id,
            final ExecutionContext context) {

        String message = String.format("Category  %s, ID: %d", category, id);
        return request.createResponseBuilder(HttpStatus.OK).body(message).build();
    }
}

예를 들어, 다음 TypeScript 코드는 두 개의 매개 변수(categoryid)를 사용하여 HTTP 트리거의 route 속성을 정의합니다. 이 예에서는 요청에서 매개 변수를 읽고 응답에 해당 값을 반환합니다.

import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const category = request.params.category;
    const id = request.params.id;

    return { body: `Category: ${category}, ID: ${id}` };
}

app.http('httpTrigger1', {
    methods: ['GET'],
    authLevel: 'anonymous',
    route: 'products/{category:alpha}/{id:int?}',
    handler: httpTrigger1,
});

예를 들어, 다음 JavaScript 코드는 두 개의 매개 변수(categoryid)를 사용하여 HTTP 트리거의 route 속성을 정의합니다. 이 예에서는 요청에서 매개 변수를 읽고 응답에 해당 값을 반환합니다.

const { app } = require('@azure/functions');

app.http('httpTrigger1', {
    methods: ['GET'],
    authLevel: 'anonymous',
    route: 'products/{category:alpha}/{id:int?}',
    handler: async (request, context) => {
        const category = request.params.category;
        const id = request.params.id;

        return { body: `Category: ${category}, ID: ${id}` };
    },
});

예를 들어 다음 코드는 두 개의 매개 변수를 사용하여 route HTTP 트리거에 대한 속성을 정의하고 id다음 category 을 수행합니다.

@app.function_name(name="httpTrigger")
@app.route(route="products/{category:alpha}/{id:int?}")

function.json 파일에 선언된 경로 매개 변수는 개체의 $Request.Params 속성으로 액세스할 수 있습니다.

$Category = $Request.Params.category
$Id = $Request.Params.id

$Message = "Category:" + $Category + ", ID: " + $Id

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = [HttpStatusCode]::OK
    Body = $Message
})

함수 실행 컨텍스트는 로 선언된 매개 변수를 통해 노출됩니다 func.HttpRequest. 이 인스턴스를 사용하면 함수가 HTTP 응답을 반환할 수 있는 데이터 경로 매개 변수, 쿼리 문자열 값 및 메서드에 액세스할 수 있습니다.

정의되면 메서드를 호출하여 함수에 경로 매개 변수를 route_params 사용할 수 있습니다.

import logging

import azure.functions as func

def main(req: func.HttpRequest) -> func.HttpResponse:

    category = req.route_params.get('category')
    id = req.route_params.get('id')
    message = f"Category: {category}, ID: {id}"

    return func.HttpResponse(message)

이 구성을 사용하여 함수는 이제 원래 경로 대신 다음 경로로 주소 지정이 가능합니다.

http://<APP_NAME>.azurewebsites.net/api/products/electronics/357

이 구성을 사용하면 함수 코드가 주소, 범주ID의 두 매개 변수를 지원할 수 있습니다. URL에서 경로 매개 변수를 토큰화하는 방법에 대한 자세한 내용은 ASP.NET Core의 라우팅을 참조 하세요.

기본적으로 모든 함수 경로에는 api 접두사로 지정됩니다. host.json 파일의 속성을 사용하여 extensions.http.routePrefix 접두사를 사용자 지정하거나 제거할 수도 있습니다. 다음 예제에서는 host.json 파일에서 빈 문자열을 접두사로 사용하여 api 경로 접두사를 제거합니다.

{
    "extensions": {
        "http": {
            "routePrefix": ""
        }
    }
}

경로 매개 변수 사용

함수의 route 패턴을 정의한 경로 매개 변수는 각 바인딩에서 사용할 수 있습니다. 예를 들어 경로가 정의된 "route": "products/{id}" 경우 테이블 스토리지 바인딩은 바인딩 구성에서 매개 변수 값을 {id} 사용할 수 있습니다.

다음 구성은 매개 변수가 {id} 바인딩 rowKey에 전달되는 방법을 보여줍니다.

@app.table_input(arg_name="product", table_name="products", 
                 row_key="{id}", partition_key="products",
                 connection="AzureWebJobsStorage")
import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const tableInput = input.table({
    connection: 'MyStorageConnectionAppSetting',
    partitionKey: 'products',
    tableName: 'products',
    rowKey: '{id}',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    return { jsonBody: context.extraInputs.get(tableInput) };
}

app.http('httpTrigger1', {
    methods: ['GET'],
    authLevel: 'anonymous',
    route: 'products/{id}',
    extraInputs: [tableInput],
    handler: httpTrigger1,
});
const { app, input } = require('@azure/functions');

const tableInput = input.table({
    connection: 'MyStorageConnectionAppSetting',
    partitionKey: 'products',
    tableName: 'products',
    rowKey: '{id}',
});

app.http('httpTrigger1', {
    methods: ['GET'],
    authLevel: 'anonymous',
    route: 'products/{id}',
    extraInputs: [tableInput],
    handler: async (request, context) => {
        return { jsonBody: context.extraInputs.get(tableInput) };
    },
});
{
    "type": "table",
    "direction": "in",
    "name": "product",
    "partitionKey": "products",
    "tableName": "products",
    "rowKey": "{id}"
}

경로 매개 변수를 사용하면 함수에 invoke_URL_template 대해 자동으로 생성됩니다. 해당 URL 템플릿을 사용하여 클라이언트는 URL을 사용하여 함수를 호출할 때 URL에 전달해야 하는 매개 변수를 이해할 수 있습니다. Azure Portal에서 HTTP 트리거 함수 중 하나로 이동하고 함수 URL 가져오기를 선택합니다.

List Functions 또는 Get Functions용 Azure Resource Manager API를 사용하여 프로그래밍 방식으로 액세스할 invoke_URL_template 수 있습니다.

HTTP 스트림(미리 보기)

이제 Node.js v4 함수 앱에서 HTTP 엔드포인트에 대한 요청 및 응답을 스트리밍할 수 있습니다. 자세한 내용은 HTTP 스트림을 참조 하세요.

클라이언트 ID 사용

함수 앱이 App Service 인증/권한 부여를 사용하는 경우 코드에서 인증된 클라이언트에 대한 정보를 볼 수 있습니다. 이 정보는 플랫폼에 의해 삽입된 요청 헤더로서 사용할 수 있습니다.

바인딩 데이터에서 이 정보를 읽을 수도 있습니다. 이 기능은 2.x 이상에서 Functions 런타임에서만 사용할 수 있습니다. 또한 이 기능은 현재 .NET 언어에 대해서만 사용할 수 있습니다.

인증된 클라이언트에 대한 정보는 다음 예제와 같이 요청 컨텍스트의 일부로 사용할 수 있는 ClaimsPrincipal로 사용할 수 있습니다.

인증된 사용자는 HTTP 헤더를 통해 사용할 수 있습니다.

인증된 사용자는 HTTP 헤더를 통해 사용할 수 있습니다.

권한 부여 수준

권한 부여 수준은 함수 엔드포인트에 액세스하는 데 필요한 인증 키의 종류를 나타내는 문자열 값입니다. HTTP 트리거 함수의 경우 권한 부여 수준은 다음 값 중 하나일 수 있습니다.

수준 값 설명
익명 API 키가 필요하지 않습니다. 이는 수준이 특별히 설정되지 않은 경우 기본값입니다.
function 함수별 API 키가 필요합니다.
admin 마스터 키가 필요합니다.
수준 값 설명
익명 API 키가 필요하지 않습니다.
function 함수별 API 키가 필요합니다. 이는 수준이 특별히 설정되지 않은 경우 기본값입니다.
admin 마스터 키가 필요합니다.

함수 액세스 키

함수에서는 키를 사용해 개발 중에 HTTP 함수 엔드포인트 액세스를 더 어렵게 만들 수 있습니다. HTTP 트리거 함수의 HTTP 액세스 수준이 anonymous로 설정되지 않는 경우 요청에는 API 액세스 키가 포함되어야 합니다.

키가 기본 보안 메커니즘을 제공하는 동안 프로덕션에서 HTTP 엔드포인트를 보호하기 위해 다른 옵션을 고려할 수 있습니다. 예를 들어, 공용 앱에 공유 암호를 배포하는 것은 좋지 않습니다. 공용 클라이언트에서 함수가 호출되는 경우 다른 보안 메커니즘 구현을 고려하는 것이 좋습니다. 자세히 알아보려면 프로덕션 환경에서 HTTP 엔드포인트 보호를 참조하세요.

함수 키 값을 갱신하는 경우 함수를 호출하는 모든 클라이언트에 업데이트된 키 값을 수동으로 다시 배포해야 합니다.

권한 부여 범위(함수 수준)

함수 수준 키에는 두 가지 액세스 범위가 있습니다.

  • 함수: 이러한 키는 정의된 특정 함수에만 적용됩니다. API 키로 사용되면 이 키를 통해 해당 함수에만 액세스할 수 있습니다.

  • 호스트: 호스트 범위가 있는 키를 사용하여 함수 앱 내의 모든 함수에 액세스할 수 있습니다. API 키로 사용되면 이 키를 통해 함수 앱 내의 모든 함수에 액세스할 수 있습니다.

각 키의 이름은 참조될 수 있도록 지정되며 함수 및 호스트 수준에서는 "default"라는 기본 키가 있습니다. function 키는 호스트 키보다 우선합니다. 두 키가 동일한 이름으로 정의되면 항상 함수 키가 사용됩니다.

마스터 키(관리자 수준)

각 함수 앱에는 _master라는 관리자 수준 호스트 키도 있습니다. 마스터 키는 앱의 모든 함수에 대한 호스트 수준 액세스를 제공할 뿐만 아니라 런타임 REST API에 대한 관리 액세스도 제공합니다. 이 키는 해지할 수 없습니다. 액세스 수준을 admin으로 설정하면 요청에서 마스터 키를 사용해야 하며, 다른 키를 사용하면 액세스가 실패합니다.

주의

함수 앱에서는 마스터 키를 통해 높은 권한이 부여되므로, 이 키를 제3자와 공유하거나 네이티브 클라이언트 애플리케이션에 배포해서는 안 됩니다. 따라서 관리자 액세스 수준을 선택하는 경우 주의해야 합니다.

키 가져오기

키는 Azure에서 함수 앱의 일부로 저장되며 미사용 시 암호화됩니다. 키를 보거나 새 키를 만들거나 키를 새 값으로 전환하려면 Azure Portal에서 HTTP 트리거 함수 중 하나로 이동한 다음 함수 키를 선택합니다.

호스트 키를 관리할 수도 있습니다. Azure Portal에서 함수 앱으로 이동하고 앱 키를 선택합니다.

Azure Resource Manager API를 사용하여 프로그래밍 방식으로 함수 및 호스트 키를 가져올 수 있습니다. 함수 키 및 목록 호스트 키를 나열하는 API가 있으며 배포 슬롯을 사용하는 경우 해당하는 API는 목록 함수 키 슬롯목록 호스트 키 슬롯입니다.

함수 비밀 만들기 또는 업데이트, 함수 비밀 슬롯 만들기 또는 업데이트, 호스트 비밀을 만들거나 업데이트하고 호스트 비밀 슬롯 API를 만들거나 업데이트하여 프로그래밍 방식으로 새 함수 및 호스트 키를 만들 수도 있습니다.

함수 및 호스트 키는 함수 비밀 삭제, 함수 비밀 슬롯 삭제, 호스트 비밀 삭제 및 호스트 비밀 슬롯 API 삭제를 사용하여 프로그래밍 방식으로 삭제할 수 있습니다.

레거시 키 관리 API를 사용하여 함수 키를 가져올 수도 있지만 대신 Azure Resource Manager API를 사용하는 것이 좋습니다.

API 키 권한 부여

대부분의 HTTP 트리거 템플릿에는 요청에 API 키가 필요합니다. 따라서 HTTP 요청은 일반적으로 다음 URL과 같습니다.

https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?code=<API_KEY>

위에 나와 있는 것처럼 쿼리 문자열 변수 code에 키를 포함할 수 있습니다. HTTP 헤더에 x-functions-key 포함할 수도 있습니다. 키 값은 함수에 대해 정의된 함수 키 또는 호스트 키일 수 있습니다.

키가 필요하지 않은 익명 요청을 허용할 수 있습니다. 마스터 키를 사용하도록 요구할 수도 있습니다. 바인딩 JSON에서 authLevel 속성을 사용하여 기본 권한 수준을 변경합니다. 자세한 내용은 트리거 - 구성을 참조하세요.

참고 항목

함수를 로컬로 실행하는 경우 지정된 권한 부여 수준 설정에 관계없이 권한 부여가 비활성화됩니다. Azure에 게시하고 나면 트리거의 authLevel 설정이 적용됩니다. 컨테이너에서 로컬로 실행하는 경우에도 키가 필요합니다.

프로덕션 환경에서 HTTP 엔드포인트 보호

프로덕션 환경에서 함수 엔드포인트를 완전히 보호하려면 다음 함수 앱 수준 보안 옵션 중 하나를 구현하는 것이 좋습니다. 이러한 함수 앱 수준 보안 방법 중 하나를 사용하는 경우 HTTP 트리거 함수 권한 부여 수준을 anonymous으로 설정해야 합니다.

App Service 인증/권한 부여를 사용하도록 설정

App Service 플랫폼에서는 Microsoft Entra ID 및 기타 여러 타사 ID 공급자를 사용하여 클라이언트를 인증할 수 있습니다. 이 전략을 사용하여 함수용 사용자 지정 권한 부여 규칙을 구현할 수 있으며, 함수 코드에서 사용자 정보를 사용할 수 있습니다. 자세히 알아보려면 Azure App Service에서 인증 및 권한 부여클라이언트 ID 사용을 참조하세요.

Azure APIM(API Management)를 사용하여 요청 인증

APIM은 수신 요청에 사용할 수 있는 여러 가지 API 보안 옵션을 제공합니다. 자세히 알아보려면 API Management 인증 정책을 참조하세요. APIM을 적용하면 APIM 인스턴스의 IP 주소에서 보내는 요청만 수락하도록 함수 앱을 구성할 수 있습니다. 자세히 알아보려면 IP 주소 제한을 참조하세요.

격리로 함수 앱 배포

ASE(Azure App Service Environment)는 함수를 실행할 전용 호스팅 환경을 제공합니다. ASE 사용 시에는 모든 수신 요청을 인증하는 데 사용할 수 있는 단일 프런트 엔드 게이트웨이를 구성할 수 있습니다. 자세한 내용은 App Service Environment용 WAF(웹 애플리케이션 방화벽) 구성을 참조하세요.

웹후크

참고 항목

웹후크 모드는 Functions 런타임의 버전 1.x에서만 사용 가능합니다. 이 변경 내용은 버전 2.x 이상에서 HTTP 트리거의 성능을 향상하기 위해 수행되었습니다.

버전 1.x에서 웹후크 템플릿은 웹후크 페이로드용으로 추가 유효성 검사를 제공합니다. 버전 2.x 이상의 경우 기본 HTTP 트리거가 계속 작동하며, 웹후크에는 이 방식을 사용하는 것이 좋습니다.

WebHook 형식

webHookType 바인딩 속성은 함수에서 지원하는 웹후크인 경우 형식을 나타내며, 지원되는 페이로드도 나타냅니다. 웹후크 형식은 다음 값 중 하나일 수 있습니다.

형식 값 설명
genericJson 특정 공급자에 대한 논리가 없는 범용 웹후크 엔드포인트입니다. 이 설정은 HTTP POST application/json 및 콘텐츠 형식을 사용하는 요청만 제한합니다.
github 이 함수는 GitHub 웹후크에 응답 합니다. GitHub 웹후크와 함께 authLevel 속성을 사용하지 마세요.
slack 함수는 Slack 웹후크에 응답합니다. Slack 웹후크와 함께 authLevel 속성을 사용하지 마세요.

webHookType 속성을 설정할 때 바인딩에 대한 methods 속성도 설정하지 마세요.

GitHub 웹후크

GitHub 웹후크에 응답하려면 먼저 HTTP 트리거를 사용하여 함수를 만들고 webHookType 속성을 github로 설정합니다. 그런 다음 URL 및 API 키를 GitHub 리포지토리의 웹후크 추가 페이지에 복사합니다.

Screenshot that shows how to add a webhook for your function.

Slack 웹후크

Slack 웹후크는 지정하는 대신 토큰을 생성하므로 Slack의 토큰을 사용하여 함수별 키를 구성해야 합니다. 권한 부여 키를 참조하세요.

웹후크 및 키

웹후크 인증은 HTTP 트리거의 일부로 웹후크 수신기 구성 요소에서 처리하며 메커니즘은 웹후크 유형에 따라 다릅니다. 각 메커니즘은 키를 사용합니다. 기본적으로 "default"라는 함수 키가 사용됩니다. 다른 키를 사용하려면 다음 중 한 가지 방법으로 요청과 함께 키 이름을 보내도록 웹후크 공급자를 구성합니다.

  • 쿼리 문자열: 공급자가 쿼리 문자열 매개 변수의 clientid 키 이름(예: https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>?clientid=<KEY_NAME>.)을 전달합니다.
  • 요청 헤더: 공급자가 헤더의 키 이름을 x-functions-clientid 전달합니다.

내용 유형

C# 이외의 함수에 이진 및 양식 데이터를 전달하려면 적절한 콘텐츠 형식 헤더를 사용해야 합니다. 지원되는 콘텐츠 형식에는 이진 데이터 및 다중 파트 형식이 포함 octet-stream 됩니다.

알려진 문제

비 C# 함수에서 콘텐츠 형식 image/jpeg 과 함께 전송된 요청은 함수에 string 전달된 값을 생성합니다. 이와 같은 경우 값을 바이트 배열로 수동으로 변환 string 하여 원시 이진 데이터에 액세스할 수 있습니다.

제한

HTTP 요청 길이는 100MB(104,857,600바이트)로 제한되고 URL 길이는 4KB(4,096바이트)로 제한됩니다. 이러한 제한은 런타임의 Web.config 파일 요소에 의해 httpRuntime 지정됩니다.

HTTP 트리거를 사용하는 함수가 약 230초 안에 완료되지 않으면 Azure Load Balancer가 시간 제한을 적용하고 HTTP 502 오류를 반환합니다. 함수는 계속 실행되지만 HTTP 응답을 반환할 수 없습니다. 장기 실행 함수의 경우 비동기 패턴을 따르고 요청 상태를 ping할 수 있는 위치를 반환하는 것이 좋습니다. 함수를 실행할 수 있는 기간에 대한 자세한 내용은 크기 조정 및 호스팅 - 소비 계획을 참조하세요.

다음 단계