--- title: "API Gateway 타입 트리거" slug: "cloudfunctions-apigateway" updated: 2026-09-17T09:09:21Z published: 2026-09-17T09:09:21Z canonical: "guide-fin.ncloud-docs.com/cloudfunctions-apigateway" --- > ## Documentation Index > Fetch the complete documentation index at: https://guide-fin.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # API Gateway 타입 트리거 네이버 클라우드 플랫폼 콘솔의 **Cloud Functions > Action > 액션 상세 정보**에서 API Gateway 타입 트리거를 추가할 수 있습니다. API Gateway는 API 호출, 관리, 모니터링 등 API와 관련된 모든 작업을 실행할 수 있는 서비스입니다. 참고 API Gateway 이용 시 별도의 요금이 부과됩니다. API Gateway 소개와 요금제에 대한 설명은 네이버 클라우드 플랫폼 포털의 **[서비스 > Application Services > API Gateway](https://www.fin-ncloud.com/product/applicationService/apiGateway)** 메뉴를 참조해 주십시오. ## 트리거 추가 API Gateway 타입 트리거를 추가하려면 트리거 종류에서 API Gateway를 클릭하여 선택한 다음 API Gateway 연결 정보를 설정해야 합니다. ![cloudfunctions-apigateway-vpc_v2_01_ko](https://cdn.document360.io/0406ed95-101f-4cde-8dd8-308d03444a94/Images/Documentation/cloudfunctions-apigateway-vpc_v2_01_ko.png?sv=2026-02-06&spr=https&st=2026-11-07T16%3A50%3A52Z&se=2026-11-07T17%3A50%3A52Z&sr=c&sp=r&sig=lXikiDUPCBJFbJ8Lt%2FlzK%2FnOuNayFo%2FHeEvJ3Wx33C4%3D) ### 트리거 유형 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)을 지원합니다. 자세한 설명은 [쿼리 파라미터](/docs/cloudfunctions-apigateway#%EC%BF%BC%EB%A6%AC%ED%8C%8C%EB%9D%BC%EB%AF%B8%ED%84%B0)를 참조해 주십시오. ### API Gateway 설정 액션을 실행하기 위한 API Gateway 엔드포인트를 설정합니다. 자세한 API Gateway 설정은 [API Gateway 사용 가이드](/docs/api-gateway-myproducts)를 참조해 주십시오. **API Gateway Zone** - API 호출 위치에 따라 접근 가능 여부를 설정하는 것으로 Product 생성 시 반드시 선택해야 하며 수정이 불가합니다. - 비공개: 금융 VPC 또는 SSL VPN을 통해서만 접근할 수 있습니다. - 공개: 어디서든 접근할 수 있습니다. **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.fin-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 응답 바디로 전달합니다. 자세한 내용은 [액티베이션 실행 결과](/docs/cloudfunctions-info#%EC%8B%A4%ED%96%89%EA%B2%B0%EA%B3%BC)를 참조해 주십시오. #### 요청 바디 **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": "

hello

" } } // Content-Type: TEXT { "statusCode": 200, "headers": { "Content-Type": "text/plain" }, "body": "hello" } } // Content-Type: Image { "statusCode": 200, "headers": { "Content-Type": "image/png" }, "body": "" } } // 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": "

hello

" } ``` 참고 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 사용 준비](/docs/cloudfunctions-spec)를 참조해 주십시오. #### 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.fin-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.fin-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.fin-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"} ```