API Gateway 타입 트리거

인쇄
공유
PDF

API Gateway 타입 트리거

인쇄
공유
PDF

기사 요약

이 요약이 도움이 되었나요?

의견을 보내 주셔서 감사합니다.

Classic 환경에서 이용 가능합니다.

네이버 클라우드 플랫폼 콘솔의 Cloud Functions > Action > 액션 상세 정보에서 API Gateway 타입 트리거를 추가할 수 있습니다. API Gateway는 API 호출, 관리, 모니터링 등 API와 관련된 모든 작업을 실행할 수 있는 서비스입니다.

참고

API Gateway 이용 시 별도의 요금이 부과됩니다. API Gateway 소개와 요금제에 대한 설명은 네이버 클라우드 플랫폼 포털의 서비스 > Application Services > API Gateway 메뉴를 참조해 주십시오.

트리거 추가

API Gateway 타입 트리거를 추가하려면 트리거 종류에서 API Gateway를 클릭하여 선택한 다음 API Gateway 연결 정보를 설정해야 합니다.

cloudfunctions-apigateway-vpc_v2_01_ko

트리거 유형

API Gateway 트리거의 유형은 연결하려는 액션 타입에 따라 달라집니다. 웹 액션 또는 시퀀스 웹 액션을 연결하려는 경우, HTTP 방식의 API Gateway 트리거가 생성됩니다. 반면, 일반 액션이나 시퀀스 액션을 연결하려는 경우에는 Webhook 방식의 API Gateway 트리거가 생성됩니다. 각 방식에 대한 설명은 다음과 같습니다:

HTTP 방식

HTTP 요청/응답을 직접 처리하는 방식으로 REST API를 구현할 수 있습니다.
POST, GET, OPTIONS, PUT, DELETE, PATCH, HEAD 메서드를 지원합니다.
HTTP 요청 헤더, 파라미터, 경로, 바디 값을 액션으로 전달합니다.
액션 코드에서 정의한 상태 코드, 헤더, 바디를 HTTP 응답으로 받을 수 있습니다.

Webhook 방식

HTTP 요청으로 액션을 실행할 수 있습니다.
POST 메서드를 지원합니다.
액션 코드에서 리턴하는 동기 방식(request and reply)과 액션의 실행하는 비동기 방식(fire and forget)을 지원합니다. 자세한 설명은 쿼리 파라미터를 참조해 주십시오.

API Gateway 설정

액션을 실행하기 위한 API Gateway 엔드포인트를 설정합니다. 자세한 API Gateway 설정은 API Gateway 사용 가이드를 참조해 주십시오.

Product

다수의 API를 관리하기 위한 단위로서 각각의 Product 별로 호출 도메인을 제공합니다.

API

API 명세와 Overview를 관리하는 단위로서 관련된 리소스와 메서드를 정의하고 인증 방식을 설정할 수 있습니다.

Resource

API URL 경로(엔드 포인트)를 설정할 수 있습니다.
HTTP 유형은 리소스 값을 {type+}로 지정하면 호출된 하위 리소스를 포함한 경로를 액션 코드에서 참조할 수 있습니다.
선택한 리소스 하위에 지원하는 메서드와 동일한 메서드가 이미 존재하면 선택할 수 없습니다.

Stage

API 배포 단위로서 개발, 테스트, 운영 또는 버전 코드(v 0.0.1)와 같은 형태로 생성, 운영할 수 있습니다.
기존 API Gateway 배포 Stage를 선택하거나 새로 생성할 수 있습니다.

API Key 인증

API Key 인증을 활성화하면 사용자의 API Key를 사용하여 API를 호출할 수 있습니다.

인증

API를 보호하기 위해 네이버클라우드플랫폼에서 제공하는 IAM 인증을 사용합니다.
- NONE: 인증 미사용
- IAM: 네이버 클라우드 플랫폼에서 제공하는 IAM 인증 사용
- IAM+AUTHORIZATION: 네이버 클라우드 플랫폼에서 제공하는 IAM을 통한 사용자 인증과 Method 단위 권한 인가 기능을 사용

트리거 실행

엔드포인트

액션을 실행할 수 있는 API Gateway 트리거의 실행 엔드포인트는 아래와 같은 형태로 생성됩니다.

https://{product_id}.apigw.gov-ntruss.com/{api_name}/{stage_name}/{resource_name}

HTTP 요청

요청 메서드

HTTP 방식

모든 POST, GET, OPTIONS, PUT, DELETE, PATCH, HEAD 메서드를 지원합니다.

Webhook 방식

POST 메서드를 지원합니다.

요청 헤더

HTTP 방식

모든 컨텐츠 타입을 허용하며 액션 코드에서 요청 헤더를 참조할 수 있습니다.

Webhook 방식

application/json 콘텐츠 타입만 허용합니다.

쿼리 파라미터

HTTP 방식

쿼리 파라미터 값을 액션 코드으로 전달하여 코드에서 파라미터 값을 사용할 수 있습니다.
쿼리 파라미터를 참조하기 위해서는 연결된 액션의 HTTP 원문 사용 설정을 활성화 해주십시오.

Webhook 방식

액션 코드에서 쿼리 파라미터 값을 참조할 수 없습니다.
실행 시 아래 쿼리 파라미터를 사용하여 API 호출 처리 방식과 결과값을 조정할 수 있습니다.
blocking
- true
  - 동기(request and reply) 요청.
  - 액션 실행이 완료된 후에 HTTP 응답을 받을 수 있고 액션 실행 결과가 응답 바디 값으로 전달됩니다.
  - 액션 실행이 1분을 초과하면 비동기 호출로 전환됩니다.
- false
  - 비동기(fire and forget) 요청. 기본 값.
  - 액션의 실행 성공/실패 여부와 관련없이 바로 HTTP 응답을 전달하며 응답 바디에는 액션 실행 이력 ID(액티베이션 ID) 값만 전달합니다.
result
- true
  - 액션 코드 리턴 값을 HTTP 응답 바디로 전달합니다.
- false
  - 액션 실행 결과를 HTTP 응답 바디로 전달합니다. 자세한 내용은 액티베이션 실행 결과를 참조해 주십시오.

요청 바디

HTTP 방식

application/json 콘텐츠 타입은 Cloud Functions 시스템 컨트롤러에서 자동으로 변환하여 액션 파라미터에 Key/Value 형식으로 전달합니다.
그 외 콘텐츠 타입은 처리를 위해서는 연결된 액션의 HTTP 원문 사용 설정을 활성화 해주십시오.
텍스트 콘텐츠 타입은 일반 문자 형태로 액션으로 전달되며 바이너리 유형은 Base64로 인코딩 되어 전달됩니다.

Webhook 방식

요청 바디의 JSON 데이터를 액션 런타임 파라미터로 전달 받습니다.

액션에 전달되는 이벤트

HTTP 요청 이벤트 데이터는 액션 런타임 파라미터로 전달됩니다.

HTTP 방식

{
    "__ow_headers": {
        "content-type": "application/json"
    },
    "__ow_method": "post",
    "__ow_path": "/",
    "__ow_query": "key1=value1&key2=value2",
    "__ow_body": "eyJhIjogImIiLCAiYyI6IDF9",
}

Webhook 방식

{
    "name": "Cloud Functions"
}

HTTP 응답

HTTP 방식

HTTP 방식은 액션 리턴 값에서 헤더, 바디, 상태 코드를 JSON 형태로 정의할 수 있습니다. Cloud Functions 시스템 컨트롤러에서 이를 HTTP 응답 형태로 변환합니다.

headers: 키가 헤더 이름이고 문자열, 숫자 또는 boolean 값으로 이루어져 있는 json 객체.
statusCode: HTTP 상태 코드. 기본 값은 200 OK. body가 null, 빈 문자열(""), undefined인 경우 204 No Content으로 처리됩니다.
body: 일반 텍스트, JSON 객체, 배열 문자열, base64로 인코딩된 바이너리 데이터 등 응답 바디 정의. 기본 값은 빈 응답.

// Content-Type: JSON
{
    statusCode: 200,
    headers: {
        "Content-Type": "application/json"
    },
    body: {"key":"value"}
}

// Content-Type: HTML 
{
    "statusCode": 200,
    "headers": {
        "Content-Type": "text/html"
    },
    "body": "<html><body><h3>hello</h3></body></html>" }
}

// Content-Type: TEXT 
{
    "statusCode": 200,
    "headers": {
        "Content-Type": "text/plain"
    },
    "body": "hello" }
}

// Content-Type: Image 
{
    "statusCode": 200,
    "headers": {
        "Content-Type": "image/png"
    },
    "body": "<base64 encoded string>" }
}

// HTTP Redirect
{
    "statusCode": 302,
    "headers": { 
        "location": "https://www.ncloud.com"
    }
}

// 헤더 쿠키 설정
{
    "statusCode": 302,
    "headers": { 
        "Set-Cookie": "UserID=Jane; Max-Age=3600; Version=",
        "Content-Type": "text/html"
    },
    "body": "<html><body><h3>hello</h3></body></html>"
}

참고

OPTIONS 요청은 기본적으로 Cors 헤더가 응답 헤더에 자동 추가됩니다. 이러한 헤더들은 모든 Origin을 허용하며, OPTIONS, GET, DELETE, POST, PUT, HEAD, PATCH 메서드를 허용합니다. 추가적으로 HTTP 요청이 존재하는 경우 Access-Control-Request-Headers 헤더는 Access-Control-Allow-Headers 헤더로 에코백됩니다. 생성되는 기본값은 다음과 같습니다.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: OPTIONS, GET, DELETE, POST, PUT, HEAD, PATCH
Access-Control-Allow-Headers: Authorization, Content-Type

OPTIONS 요청은 웹 액션에 의해 수동으로 처리될 수도 있습니다. 이를 위해 헤더 옵션 설정을 활성화 해 주십시오. CORS 헤더는 더 이상 자동으로 추가되지 않고 액션 코드에서 직접 정의해야 합니다.

주의

HTTP 방식은 최대 1분까지 응답을 받을 수 있습니다. 액션이 1분 이상 실행되면 202 Accepted 응답을 받게 됩니다. 바디에는 아래와 같은 에러가 포함됩니다.

{
    "code": "fe398a568d89a5efbeaedbb5bc415cbb",
    "error": "Response not yet ready."
}

액션이 반환할 수 있는 최대 응답 크기가 있기 때문에 최대 크기를 초과하는 응답값 반환 시도 시 액션 실행 결과를 실패로 처리됩니다. 이미지와 같은 객체 파일을 반환하려는 경우 최대 응답 크기에 주의하되 최대 크기를 초과하는 경우 액션 코드로 반환하지 않고 다른 저장소를 이용해 주십시오. 최대 응답 크기에 대한 사양은 Cloud Functions 사용 준비를 참조해 주십시오.

Webhook 방식

Webhook 방식은 바디만 정의할 수 있습니다.

상태 코드: 동기 방식은 200 OK. 비동기 방식은 202 Accepted
바디: 동기 방식은 액션 코드에서 리턴한 값. 비동기 방식은 액션 실행 이력 ID

주의

동기 방식으로 실행 시, 액션이 1분 이상 실행되면 비동기 방식으로 전환됩니다.

실행 예시

HTTP 방식

액션 리턴 값

{
    "statusCode": 200,
    "headers": {
            "Custom-Header": "custom value"
            "Content-Type": "application/json"
        },
    "body": {"name": "Cloud Functions"}
}

실행

$ curl -i -X GET "https://myproduct.apigw.gov-ntruss.com/api/v1/users" 

HTTP/2 200
content-type: application/json
custom-header: custom value
x-request-id: c64b4dc037c7be7bbe73213beacff8eb
x-ncp-apigw-response-origin: ENDPOINT

{
    "name": "Cloud Functions"
}

Webhook 방식

액션 리턴 값

{
    "name": "Cloud Functions"
}

실행 (동기)

$ curl -i -X POST -H "Content-Type: application/json" "https://myproduct.apigw.gov-ntruss.com/api/v1/action?blocking=true&result=true -d '{"key1": "value1"}'


HTTP/2 200
content-type: application/json
x-request-id: c64b4dc037c7be7bbe73213beacff8eb
x-ncp-apigw-response-origin: ENDPOINT

{"name":"Cloud Functions"}

실행 (비동기)

$ curl -i -X POST -H "Content-Type: application/json" "https://myproduct.apigw.gov-ntruss.com/api/v1/action?blocking=false -d '{"key1": "value1"}'

HTTP/2 202
content-type: application/json
x-request-id: c64b4dc037c7be7bbe73213beacff8eb
x-ncp-apigw-response-origin: ENDPOINT

{"activationId":"e04d1a62a3e14eb58d1a62a3e18eb590"}

이 문서가 도움이 되었습니까?

What's Next

Node.js

트리거 추가
트리거 실행