Lambda 함수 URL 호출

Lambda 함수 URL 호출

함수 URL(Function URL)은 Lambda 함수를 위한 전용 HTTP(S) 엔드포인트예요. Lambda 콘솔이나 Lambda API를 통해 함수 URL을 만들고 구성할 수 있죠.

팁
Lambda는 HTTP 엔드포인트로 함수를 호출하는 두 가지 방법을 제공해요: 함수 URL과 Amazon API Gateway. 어떤 방법이 여러분의 사용 사례에 가장 좋은지 잘 모르겠다면 HTTP 요청으로 Lambda 함수를 호출할 방법 선택을 참고하세요.

함수 URL을 만들면 Lambda가 고유한 URL 엔드포인트를 자동으로 생성해요. 함수 URL을 만든 후에는 URL 엔드포인트가 절대 바뀌지 않아요. 함수 URL 엔드포인트 형식은 다음과 같아요:

https://<url-id>.lambda-url.<region>.on.aws

참고
함수 URL은 모든 AWS 리전에서 지원되지는 않아요. 가용성을 확인하려면 AWS Regional Services에서 Feature Name = Function URLs로 필터링하세요.

함수 URL은 IPv4와 IPv6를 지원하는 듀얼 스택(dual stack)이에요. 함수 URL을 구성한 뒤에는 웹 브라우저, curl, Postman, 또는 어떤 HTTP 클라이언트로든 함수의 HTTP(S) 엔드포인트를 통해 함수를 호출할 수 있어요. 함수 URL을 호출하려면 lambda:InvokeFunctionUrl과 lambda:InvokeFunction 권한이 필요해요. 자세한 내용은 접근 제어를 참고하세요.

출처: AWS Lambda 개발자 안내서

본문

Topics(주제)

• 함수 URL 호출 기본
• 요청 및 응답 페이로드

함수 URL 호출 기본

함수 URL이 AWS_IAM 인증 유형을 사용한다면 AWS Signature Version 4(SigV4)로 각 HTTP 요청에 서명해야 해요. Postman 같은 도구는 SigV4로 요청에 서명하는 내장 기능을 제공하죠.

함수 URL에 대한 HTTP 요청 서명 도구를 사용하지 않는다면 각 요청을 SigV4로 수동 서명해야 해요. 함수 URL이 요청을 받으면 Lambda도 SigV4 서명을 계산해요. Lambda는 서명이 일치할 때만 요청을 처리하죠. SigV4로 요청을 수동 서명하는 방법은 Amazon Web Services General Reference Guide의 Signature Version 4로 AWS 요청 서명을 참고하세요.

함수 URL이 NONE 인증 유형을 사용한다면 SigV4로 요청에 서명할 필요가 없어요. 웹 브라우저, curl, Postman, 또는 어떤 HTTP 클라이언트로든 함수를 호출할 수 있죠.

함수에 대한 간단한 GET 요청을 테스트하려면 웹 브라우저를 사용하세요. 예를 들어 함수 URL이 https://abcdefg.lambda-url.us-east-1.on.aws이고 message 문자열 매개변수를 받는다면 요청 URL은 다음과 같을 수 있어요:

https://abcdefg.lambda-url.us-east-1.on.aws/?message=HelloWorld

POST 요청 같은 다른 HTTP 요청을 테스트하려면 curl 같은 도구를 사용할 수 있어요. 예를 들어 POST 요청에 JSON 데이터를 포함하고 싶다면 다음 curl 명령을 쓸 수 있어요:

curl -v 'https://abcdefg.lambda-url.us-east-1.on.aws/?message=HelloWorld' \
-H 'content-type: application/json' \
-d '{ "example": "test" }'

요청 및 응답 페이로드

클라이언트가 함수 URL을 호출하면 Lambda는 함수에 전달하기 전에 요청을 이벤트 객체로 매핑해요. 그러면 함수의 응답은 Lambda가 함수 URL을 통해 클라이언트에게 다시 보내는 HTTP 응답으로 매핑되죠.

요청과 응답 이벤트 형식은 Amazon API Gateway 페이로드 형식 버전 2.0과 동일한 스키마를 따릅니다.

요청 페이로드 형식

요청 페이로드는 다음 구조를 가져요:

{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "headers": {
    "header1": "value1",
    "header2": "value1,value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "<urlid>",
    "authentication": null,
    "authorizer": {
        "iam": {
                "accessKey": "AKIA...",
                "accountId": "111122223333",
                "callerId": "AIDA...",
                "cognitoIdentity": null,
                "principalOrgId": null,
                "userArn": "arn:aws:iam::111122223333:user/example-user",
                "userId": "AIDA..."
        }
    },
    "domainName": "<url-id>.lambda-url.us-west-2.on.aws",
    "domainPrefix": "<url-id>",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "123.123.123.123",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "body": "Hello from client!",
  "pathParameters": null,
  "isBase64Encoded": false,
  "stageVariables": null
}

응답 페이로드 형식

함수가 응답을 반환하면 Lambda는 응답을 파싱해 HTTP 응답으로 변환해요. 함수 응답 페이로드는 다음과 같은 형식이에요:

{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": "{ \"message\": \"Hello, world!\" }",
    "cookies": [
        "Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
        "Cookie_2=Value2; Max-Age=78000"
    ],
    "isBase64Encoded": false
}

Lambda가 응답 형식을 추론해 줘요. 함수가 유효한 JSON을 반환하고 statusCode를 반환하지 않으면 Lambda는 다음을 가정해요:

• statusCode는 200이다. 참고
  유효한 statusCode는 100에서 599 사이의 범위예요.
• content-type은 application/json이다.
• body는 함수 응답이다.
• isBase64Encoded는 false이다.

다음 예제는 Lambda 함수 출력이 응답 페이로드로 매핑되는 방식과 응답 페이로드가 최종 HTTP 응답으로 매핑되는 방식을 보여줘요. 클라이언트가 함수 URL을 호출하면 HTTP 응답을 보게 됩니다.

문자열 응답 출력 예제

JSON 응답 출력 예제

커스텀 응답 출력 예제

쿠키

함수에서 쿠키를 반환하려면 set-cookie 헤더를 수동으로 추가하지 마세요. 대신 쿠키를 응답 페이로드 객체에 포함하세요. Lambda가 이를 자동으로 해석해 다음 예제처럼 HTTP 응답의 set-cookie 헤더로 추가해요.

더 알아보기 (Learn more)

• SigV4 서명 방식과 인증 유형에 따른 호출 차이, 함수 URL 요청·응답 페이로드 형식(API Gateway 페이로드 2.0 스키마)을 이어서 살펴보세요.