Application Service > API Gateway > 콘솔 사용 가이드

API Gateway 서비스

API Gateway 서비스는 API Gateway를 통해 서비스할 API를 관리하는 단위입니다. API Gateway 서비스마다 하나의 API 리소스와 여러 개의 스테이지를 관리할 수 있으며, 대시보드를 통해 API 지표를 확인할 수 있습니다.

API Gateway 서비스 생성

API Gateway 서비스 정보를 입력한 후 생성 버튼을 클릭하면 API Gateway 서비스가 생성됩니다.

  • 서비스명: 서비스의 이름입니다.
  • 서비스 설명: 서비스의 설명입니다.
  • 서비스 ID: 서비스마다 임의로 발급된 고유한 ID입니다.

[참고] API Gateway 서비스 생성 개수 제한 API Gateway 서비스는 프로젝트당 최대 10개까지 생성 가능합니다.

API Gateway 서비스 조회

  • 등록된 API Gateway 서비스 목록이 표시됩니다.
  • 목록에서 서비스를 선택하면 등록된 스테이지 목록이 표시됩니다.
  • 리소스를 관리하려면 서비스 설정 열의 리소스 버튼을 클릭합니다.
  • 스테이지를 관리하려면 서비스 설정 열의 스테이지 버튼을 클릭합니다.

API Gateway 서비스 삭제

  • 등록된 API Gateway 서비스 목록이 표시됩니다.
  • 목록에서 서비스를 선택하고, 삭제 버튼을 클릭합니다.
  • 확인 창이 나타나면 확인 버튼을 클릭합니다. 삭제된 데이터는 복구할 수 없습니다.

[주의] API Gateway 서비스를 삭제할 수 없는 경우 API Gateway 서비스의 스테이지와 연결된 사용량 계획이 존재하면 API Gateway 서비스를 삭제할 수 없습니다.

리소스

리소스는 API Gateway를 통해 서비스할 API를 설계하는 화면입니다. 모든 API 요청 클라이언트는 API Gateway 리소스에 정의된 API에 대해 요청을 할 수 있습니다. 리소스는 API의 리소스 경로와 메서드를 관리합니다.

  1. 리소스 경로: API 경로
  2. 리소스 메서드: HTTP 메서드
  3. 플러그인: 리소스 경로 또는 메서드에 부가 기능을 추가합니다.

리소스 생성

  1. 리소스를 생성하려면 리소스 생성 버튼을 클릭하거나 좌측 리소스 트리 화면에서 마우스 오른쪽을 클릭하면 표시되는 메뉴에서 리소스 생성을 클릭합니다.
  2. 리소스 경로를 작성합니다. 작성된 리소스 경로를 포함하여 전체 경로는 255자 이내로 작성해야 합니다.
    • 예: /products/, /products/{productsId}, /{proxy+}
  3. 경로 변수: 리소스 경로에는 중괄호를 사용하여 경로 변수를 생성할 수 있습니다.
    • 경로 변수{variable} 또는 하위 경로를 포함한 경로 변수는 {variable+}와 같이 선언할 수 있습니다.
      • 경로 변수는 플러그인과 백엔드 엔드포인트 설정에서 활용할 수 있습니다.
      • {variable}는 경로 변수가 위치한 경로의 값을 변수로 선언합니다.
        • 예: /members/{memberId}
          • /members/id1 요청의 {memberId} 경로 변숫값은 id1이 됩니다.
      • {variable+} 는 경로 변수가 위치한 하위 경로를 포함하여 변수로 선언합니다. 하위 경로를 포함한 변수에는 하위 리소스 경로를 생성할 수 없습니다.
        • 예: /{proxy+}
          • /members/id1 요청의 {proxy+} 경로 변숫값은 members/id1이 됩니다.
  4. 플러그인: 선택된 경로에 추가된 플러그인을 생성된 메서드에도 추가하려면 체크합니다.
  5. 리소스를 생성하면서 메서드도 같이 등록하려면 HTTP 메서드를 선택합니다.
  6. 등록하지 않은 리소스 경로로 API Gateway에 요청하면 404 Not Found 응답을 반환합니다.

리소스 가져오기

Swagger v2.0 OpenAPI Specification 형식의 파일로 리소스를 가져올 수 있습니다. 1. 리소스 가져오기 버튼을 클릭합니다. 2. Swagger 파일 선택 버튼을 클릭하여 파일을 선택하거나 Swagger 내용을 직접 입력합니다. 3. 적용 버튼을 클릭합니다.

[주의] 리소스 가져오기시 기존 리소스 덮어쓰기 리소스를 가져오면 기존의 리소스는 삭제되고 가져온 리소스로 덮어씁니다.

메서드 생성

  • 선택된 리소스 경로 하위에 HTTP 메서드를 생성합니다.
    • 지원 HTTP 메서드: HEAD, OPTIONS, GET, POST, PUT, DELETE, PATCH
  • 메서드 이름: 메서드의 별칭입니다. 이름은 리소스 트리 화면에 설명으로 표시됩니다.
  • 메서드 설명: 메서드에 대한 설명입니다.
  • 백엔드 엔드포인트 타입
    • HTTP(S): API Gateway로 수신된 API 요청을 정의된 백엔드 엔드포인트 URL 경로로 전달합니다.
    • 사용자 정의 응답: API 게이트웨이는 수신된 요청에 대해 정의된 응답을 반환합니다.
  • 백엔드 엔드포인트 타입: HTTP(S)
    • 백엔드 엔드포인트 URL 경로: 수신된 API 요청을 전달할 백엔드 엔드포인트 서비스의 API URL을 설정합니다.
      • 루트(/)로 시작해야 합니다.
      • 경로에는 리소스에서 생성한 컨텍스트 변수를 설정할 수 있습니다. (자세한 컨텍스트 변수는 컨텍스트 변수를 참고하세요.)
  • 백엔드 엔드포인트 타입: 사용자 정의 응답

    • 사용자 정의 응답을 설정합니다.
    • 응답 상태 코드: 응답 HTTP 상태 코드를 입력합니다. (필수)
    • 헤더: 응답 헤더의 이름과 값을 입력합니다.
    • 응답 본문: 응답 본문을 입력합니다.
    • 헤더와 응답 본문에는 리소스에서 생성한 컨텍스트 변수를 설정할 수 있습니다. (자세한 컨텍스트 변수는 컨텍스트 변수를 참고하세요.)
  • 플러그인: 선택된 경로에 추가된 플러그인을 생성된 메서드에도 추가하려면 체크합니다.

  • 등록하지 않은 HTTP 메서드를 API Gateway에 요청하면 404 Not Found 응답을 반환합니다.

[참고] 리소스 메서드 생성 제한 개수 메서드는 모든 리소스 경로를 포함하여 최대 100개까지 생성 가능합니다.

리소스와 메서드 수정

  • 리소스 경로 수정
    • 리소스 경로는 수정이 불가합니다. 경로를 수정하려면 삭제 후 다시 생성해야 합니다.
  • 메서드 수정
    1. HTTP 메서드는 수정이 불가합니다. HTTP 메서드를 수정하려면 삭제 후 다시 생성해야 합니다.
    2. 메서드 이름, 설명, 백엔드 엔드포인트 항목은 수정할 수 있습니다.
    3. 수정을 하려면 좌측 리소스 트리에서 메서드를 선택합니다.
    4. 설정을 변경한 후 변경 내용 저장 버튼을 클릭합니다.

[참고] CORS플러그인에 의해 등록된 OPTIONS 메서드의 수정 CORS 플러그인에 의해 등록된 OPTIONS 메서드는 수정할 수 없습니다.

리소스와 메서드 삭제

  • 삭제할 리소스 경로 또는 메서드를 선택합니다.
    • 선택 삭제 버튼을 클릭하면 삭제 확인 창이 표시됩니다.
    • 왼쪽 리소스 트리에서 마우스 오른쪽 버튼을 클릭하고, 표시된 메뉴에서 리소스 삭제 또는 메서드 삭제를 선택합니다.
  • 확인 창이 나타나면 확인 버튼을 클릭합니다. 삭제된 데이터는 복구할 수 없습니다.

[주의] 리소스 경로 삭제 리소스 경로를 삭제하면 선택된 리소스의 경로의 하위 리로스 경로와 메서드가 모두 삭제 됩니다.

[참고] CORS플러그인에 의해 등록된 OPTIONS 메서드의 삭제 CORS 플러그인에 의해 등록된 OPTIONS 메서드는 삭제할 수 없습니다.

스테이지 리소스 적용

리소스를 변경한 후 스테이지에 변경된 리소스를 적용하려면 스테이지 리소스 적용을 해야 합니다.

  1. 변경된 리소스를 스테이지에 적용하려면 스테이지 리소스 적용 버튼을 클릭합니다.
  2. 변경된 리소스를 적용할 스테이지를 선택합니다.
  3. 적용 버튼을 클릭합니다.

[주의] 스테이지 리소스 적용 - 스테이지 리소스를 적용하려면 적어도 하나 이상의 스테이지가 존재해야 합니다. - 스테이지에 리소스가 적용된 후에는 기존 리소스로 복구가 불가합니다. - 이미 스테이지에 최신 리소스가 적용되어 있으면 스테이지 리소스 적용이 불가합니다.

플러그인 추가와 삭제

플러그인을 통해 API Gateway에서 제공하는 부가 기능을 추가할 수 있습니다.

  • 플러그인 적용 위치
    • 플러그인은 리소스 경로 또는 메서드에 추가할 수 있습니다.
    • 리소스 경로에 플러그인을 추가하면 선택된 경로의 하위 메서드에 플러그인이 일괄 적용됩니다.
    • 메서드에 플러그인을 추가하면 선택된 메서드에만 플러그인이 적용됩니다.
  • 플러그인 적용 단계
    • 플러그인은 백엔드 요청 사전 작업프런트엔드 응답 사전 작업 단계에 추가할 수 있습니다.
      • 백엔드 요청 사전 작업: API Gateway에 수신된 API 요청을 백엔드에 전달하기 전 플러그인을 적용합니다.
      • 프런트엔드 응답 사전 작업: 백엔드에서 전달받은 응답을 프런트엔드에 전달하기 전 플러그인을 적용합니다.
  • 플러그인 추가
    • 백엔드 요청 사전 작업과 프런트엔드 응답 사전 작업의 + 플러그인 버튼을 클릭합니다.
      1. 추가할 플러그인을 클릭합니다.
      2. 플러그인의 설정 내용을 입력한 후 추가 버튼을 클릭합니다.
      3. 선택된 경로를 포함하여 하위 경로와 메서드에 플러그인을 일괄 적용하려면 하위 경로와 메서드에 덮어쓰기를 체크합니다.
        • !주의: 하위 경로와 메서드에 추가하려는 플러그인이 이미 등록되어 있는 경우, 설정이 대체되므로 주의해주세요.
      4. 변경 내용 저장 버튼을 클릭합니다.
  • 플러그인 삭제
    1. 백엔드 요청 사전 작업과 프런트엔드 응답 사전의 등록된 플러그인을 선택합니다.
    2. 선택된 경로를 포함하여 하위 경로와 메서드에 플러그인을 일괄 삭제하려면 하위 경로와 메서드에 덮어쓰기를 체크합니다.
    3. 삭제 버튼을 클릭합니다.
    4. 변경 내용 저장 버튼을 클릭합니다.

[주의] 플러그인 추가 후 변경사항 저장 플러그인을 추가한 후 변경 사항 저장 버튼을 클릭해야 설정이 저장됩니다.

컨텍스트 변수

리소스의 메서드 생성 및 플러그인 설정 시 아래 정의된 변수를 사용할 수 있습니다.

컨텍스트 변수 설명
${request.clientIp} API를 요청한 클라이언트의 IP
${request.path.variable-name} 리소스에서 선언한 단일 경로 변수 {variable-name} 값 참조
${request.path.variable-name+} 리소스에서 선언한 하위 경로를 포함한 경로 변수 {variable-name+} 값 참조

[주의] 경로 변수 선택된 경로와 상위 경로에 선언된 경로 변수만 사용할 수 있습니다.

플러그인

CORS

Cross-Site 방식 내에서 XMLHttpRequest API 호출을 할 수 있게 합니다.

  • 플러그인 적용 가능한 위치: 리소스 경로
  • 플러그인 적용 단계: 백엔드 사전 요청 작업
  • CORS 플러그인 설정
    • Access-Control-Allow-Credentials: 자격 증명으로 요청하는 경우 True로 설정해야 합니다.
    • Access-Control-Max-Age: 사전 전달 요청(Preflight)에 대한 응답을 얼마 동안 캐시할지 초 단위로 입력합니다. -1~86400 사이의 값을 입력할 수 있습니다.
    • Access-Control-Allow-Origin: 리소스에 액세스할 수 있는 원본 서버의 도메인을 입력합니다.
      • *로 입력하면 모든 도메인을 허용합니다.(단, *로 지정할 경우 자격 증명을 지원하지 않으므로 허용 원본(allowed origin)에 구체적인 도메인을 지정하셔야 합니다.)
      • 여러 도메인을 허용하기 위해서는 ,(쉼표)로 구분해 입력합니다.
      • 도메인은 URI(스킴, 도메인, 포트) 형식으로 입력해야 합니다(예: http://example.nhncloudservice.com:8080).
    • Access-Control-Allow-Methods: 리소스 접근에 허용할 메서드를 설정합니다. 여러 메서드를 지정할 경우 ','로 구분해 입력합니다.
    • Access-Control-Allow-Headers: 요청에서 사용할 수 있는 HTTP 헤더를 설정합니다. 여러 헤더를 설정할 경우 ','로 구분해 입력합니다.
    • Access-Control-Expose-Headers: 브라우저(클라이언트)가 접근할 수 있는 헤더를 설정합니다. 여러 헤더를 설정할 경우 ','로 구분해 입력합니다.
    • 자세한 CORS 규약은 https://www.w3.org/TR/cors/를 참고해 주세요.

[주의] CORS 플러그인 - CORS 플러그인을 등록하면 선택된 경로의 메서드에 OPTIONS 메서드가 등록됩니다. 하위 경로와 메서드에 덮어쓰기 옵션을 체크한 경우에는 하위 경로에도 등록됩니다. OPTIONS 메서드가 이미 등록되어 있는 경우, CORS에 의해 자동 생성되는 OPTIONS 메서드로 대체됩니다. - CORS 플러그인을 통해 등록된 OPTIONS 메서드는 리소스 트리에서 선택이 불가하며, 수정과 삭제를 할 수 없습니다. - CORS 플러그인을 삭제하면 CORS 플러그인에 의해 자동 생성된 OPTIONS 메서드는 일괄적으로 삭제됩니다.

요청 헤더 변경

요청 헤더를 추가하거나 변경합니다.

  • 플러그인 적용 가능한 위치: 리소스 경로, 메서드
  • 플러그인 적용 단계: 백엔드 요청 사전 작업
  • 요청 헤더 변경 설정
    • + 버튼을 클릭하면 헤더 목록을 추가할 수 있습니다.
    • 헤더 이름과 값을 입력합니다.
    • 헤더값에는 리소스에서 선언한 컨텍스트 변수를 설정할 수 있습니다. (자세한 컨텍스트 변수는 컨텍스트 변수를 참고하세요.)

[참고] 요청 헤더 추가와 변경 - 원본 요청에 없는 헤더는 추가됩니다. - 원본 요청에 있는 헤더는 요청 헤더 변경 플러그인에 설정된 헤더값으로 대체됩니다. - 원본 요청에 있는 헤더의 삭제는 불가합니다.

응답 헤더 변경

응답 헤더 변경 플러그인은 백엔드 응답에 헤더를 추가하거나 변경합니다.

  • 플러그인 적용 가능한 위치: 리소스 경로, 메서드
  • 플러그인 적용 단계: 프런트엔드 응답 사전 작업
  • + 버튼을 클릭하면 헤더 목록을 추가할 수 있습니다.
  • 헤더 이름과 값을 입력합니다.
  • 헤더값에는 리소스에서 선언된 컨텍스트 변수를 설정할 수 있습니다. (자세한 컨텍스트 변수는 컨텍스트 변수를 참고하세요.)

[참고] 응답 헤더 추가와 변경 - 백엔드 엔드포인트의 응답에 없는 헤더는 추가됩니다. - 백엔드 엔드포인트의 응답에 있는 헤더는 요청 헤더 변경 플러그인에 설정된 헤더값으로 대체됩니다.

요청 쿼리 문자열 파라미터 추가

백엔드 엔드포인트 요청에 쿼리 문자열 파라미터를 추가합니다.
예: 파라미터 이름과 값을 name, value로 설정하면 name=value 쿼리 문자열 파라미터가 백엔드 엔드포인트 요청 시 추가됩니다.

  • 플러그인 적용 가능한 위치: 리소스 경로, 메서드
  • 플러그인 적용 단계: 백엔드 요청 사전 작업
  • + 버튼을 클릭하면 파라미터 목록을 추가할 수 있습니다.
  • 파라미터 이름과 값을 입력합니다.
  • 파라미터 값에는 리소스에서 선언된 컨텍스트 변수를 설정할 수 있습니다. (자세한 컨텍스트 변수는 컨텍스트 변수 를 참고하세요.)

[참고] 요청 쿼리 문자열 파라미터 - '원본 요청의 쿼리 문자열 파라미터'와 같은 키를 갖는 '요청 쿼리 문자열 파라미터'는, '원본 요청의 쿼리 문자열'을 대체하지 않고 추가됩니다. - 쿼리 문자열 파라미터의 값은 인코딩되어 백엔드 엔드포인트로 전달됩니다.

스테이지

스테이지는 리소스를 배포하는 단계입니다.

  • 스테이지별로 고유한 스테이지 URL 이 발급됩니다.
  • 스테이지는 서비스별 또는 환경(Profile)별로 서비스를 구분하거나 그 외 용도로 활용이 가능합니다.

스테이지 생성

  1. API Gateway 서비스 목록에서 스테이지 설정을 클릭합니다.
  2. 스테이지 탭에서 스테이지 생성 버튼을 클릭합니다.
  3. 스테이지 정보를 입력한 후 생성 버튼을 클릭합니다.
    • 스테이지 이름
      • 숫자와 영문 소문자만 입력 가능하며, 최대 30자 이내로 작성할 수 있습니다.
      • 스테이지 이름은 스테이지 URL에 포함됩니다.
      • 기본 스테이지는 스테이지 이름을 작성하지 않으면 생성되는 스테이지입니다. 기본 스테이지의 스테이지 URL에는 스테이지 이름이 포함되지 않습니다.
    • 스테이지 URL: API Gateway로 통합 요청이 가능한 스테이지 URL입니다.
      • API 요청 클라이언트는 스테이지 URL을 통해 API를 요청할 수 있습니다.
      • 스테이지 URL은 다음과 같은 형식으로 발급됩니다.
        • 기본 스테이지: {region}-{api-gateway-service-id}.api.nhncloudservice.com
          • {region}: 판교 리전(kr1)
          • {api-gateway-service-id}: API Gateway 서비스 ID
        • 일반 스테이지: {region}-{api-gateway-service-id}-{stage-name}.api.nhncloudservice.com
          • {region}: 판교 리전(kr1)
          • {api-gateway-service-id}: API Gateway 서비스 ID
          • {stage-name}: 입력된 스테이지 이름
    • 백엔드 엔드포인트 URL
      • API Gateway로 수신된 요청을 전달할 백엔드 엔드포인트 URL을 작성합니다.
      • 스킴(http:// 또는 https://)을 포함하여 URL을 작성해야 합니다.
      • 도메인 주소만 입력하거나 하위 경로를 포함하여 작성할 수 있습니다.
        • 예: https://api.nhn.com , https://api.nhn.com/apis

[참고] 스테이지 - 스테이지를 생성하려면 리소스 메서드가 하나 이상 등록돼 있어야 합니다. - 스테이지는 API Gateway 서비스당 최대 10개까지 생성 가능합니다. - API Gateway로 수신된 요청을 백엔드 엔드포인트로 전달할 때 기본으로 스테이지에 정의된 백엔드 엔드포인트 URL로 요청을 전달합니다.

스테이지 수정

  1. 수정할 스테이지를 선택합니다.
  2. 스테이지 수정 버튼을 클릭합니다.
  3. 스테이지 정보를 수정합니다. 수정 가능한 항목은 스테이지 설명, 백엔드 엔드포인트 URL입니다.
  4. 설정을 변경한 후 수정 버튼을 클릭합니다.

[주의] 스테이지 배포 수정된 백엔드 엔드포인트 URL을 API Gateway 서비스에 적용하려면 스테이지를 배포해야 합니다.

스테이지 삭제

  1. 삭제할 스테이지를 선택합니다.
  2. 스테이지 삭제 버튼을 클릭합니다.
  3. 삭제 확인 창에서 확인을 클릭하면 삭제됩니다. 이 작업은 취소 할 수 없습니다.

[주의] 스테이지 삭제 - 서비스에서 사용 중인 스테이지를 삭제하면 더 이상 API Gateway로 요청이 인입되지 않습니다. - 삭제된 스테이지는 복구가 불가하므로 반드시 서비스에서 사용중인지 확인 후 삭제를 진행하세요. - 스테이지와 연결된 사용량 계획이 존재하면 스테이지를 삭제할 수 없습니다.

리소스 가져오기

리소스를 변경한 후 스테이지에 변경된 리소스를 적용하려면 스테이지 관리화면에서 리소스 가져오기를 진행합니다.

  1. 변경된 리소스를 스테이지에 적용하려면 리소스 가져오기 버튼을 클릭합니다.

[주의] 리소스 가져오기 - 스테이지에 리소스가 적용된 후에는 기존 리소스로 복구가 불가합니다. - 리소스에 변경된 사항이 없는 경우 리소스 가져오기 버튼이 비활성화됩니다.

스테이지 배포

스테이지에 설정된 리소스와 설정을 API Gateway 서비스에 적용하려면 스테이지를 배포해야 합니다.

  1. 스테이지 탭에서 배포할 스테이지를 선택합니다.
  2. 스테이지 배포 버튼을 클릭합니다.
  3. 스테이지 배포 화면이 표시됩니다.
  4. 스테이지 배포에 대한 설명을 작성합니다(선택 사항).
  5. 스테이지 배포 버튼을 클릭합니다.
  6. 스테이지 배포 상태를 통해 배포 상태를 확인할 수 있습니다.
    • 배포 성공 상태이면 정상적으로 배포된 상태입니다.
    • 배포 실패 상태이면 배포 중 작업 오류가 발생한 상태입니다. 배포 실패가 발생하면 배포를 재시도해 주시기 바랍니다. 지속적으로 실패하는 경우 고객센터로 문의해주시기 바랍니다.

스테이지 배포 이력

스테이지 배포 이후 배포된 이력들을 확인할 수 있으며, 이전 배포 설정으로 스테이지를 되돌릴 수 있습니다.

  1. 스테이지 탭에서 스테이지를 선택합니다.
  2. 배포 이력 탭을 선택합니다.
  3. 스테이지 배포 이력을 확인할 수 있습니다.
    • 배포된 스테이지: 현재 API Gateway 서비스에 적용되어 있는 배포 이력을 의미합니다.
    • 기반 스테이지: 현재 스테이지 설정의 기반이 되는 배포 이력을 의미합니다. 스테이지 배포와 스테이지 되돌리기를 수행할 경우 변경됩니다.
    • 스테이지 되돌리기: 해당 배포 이력의 스테이지 설정으로 현재 스테이지 설정이 변경됩니다.
    • 삭제: 불필요한 배포 이력을 삭제합니다.

[주의] 이전 배포 이력으로 스테이지 되돌리기 - 스테이지 되돌리기를 사용할 경우, 이를 API Gateway 서비스에 적용하려면 스테이지를 배포해야 합니다.

스테이지 내보내기

  1. 스테이지 탭에서 스테이지를 선택합니다.
  2. 스테이지 내보내기 탭을 선택합니다.
  3. 스테이지 내보내기 버튼을 클릭하여 선택된 스테이지의 리소스를 Swagger 파일로 저장합니다.

IP ACL

IP ACL을 통해 지정된 클라이언트 IP에 대해 API Gateway 요청을 허용/거부할 수 있습니다.

  1. 스테이지 탭에서 스테이지를 선택합니다.
  2. 설정 탭을 선택합니다.
  3. 스테이지 트리 화면에서 스테이지의 루트(/) 경로를 선택합니다.
  4. IP ACL을 활성화(On)합니다.
  5. IP ACL을 설정합니다.
    • IP 접근 제어 타입
      • 허용: 지정된 IP만 접근을 허용하고 나머지 IP는 모두 거부합니다. (화이트리스트 방식)
      • 거부: 지정된 IP만 접근을 거부하고 나머지 IP는 모두 허용합니다. (블랙리스트 방식)
    • IP 접근 대상
      • 단건 입력 또는 대량 입력 방식을 선택하여 IP 목록을 쉽게 등록할 수 있습니다.
      • IP 접근 대상은 IPv4의 단일 IP 또는 CIDR 로 입력할 수 있습니다.
        • 단일 IP: 10.0.0.1
        • CIDR 예시: 10.0.0.1/24

[참고] IP ACL 등록 개수 제한 및 클라이언트 IP 체크 - IP ACL의 IP 접근 대상은 최대 100개까지 입력 가능합니다. - 네트워크 주소 변환(NAT: Network Address Translation)에 의해 클라이언트의 Source IP가 변경된 경우, 변경된 IP를 기준으로 IP ACL을 체크하므로 주의하시기 바랍니다.

인증 > HMAC

HMAC 인증을 사용하면 API Gateway로 수신된 요청이 중간 공격자에 의해 변조되는 것을 방지하며, 요청 유효 시간을 설정하여 Reply Attack 공격을 예방합니다.

  1. 스테이지 탭에서 스테이지를 선택합니다.
  2. 설정 탭을 선택합니다.
  3. 스테이지 트리 화면에서 스테이지의 루트(/) 경로를 선택합니다.
  4. 인증에서 HMAC을 선택합니다.
  5. HMAC 설정을 입력합니다.
    • 비밀키: SignToString을 암호화할 비밀키입니다. 외부에 유출되지 않도록 유의합니다.
    • 요청 유효 시간(초): 설정된 유효 시간의 양방향 시간(요청 시간의 과거/미래 시간 전 후)을 초과한 요청을 거부합니다. 요청 유효 시간을 0초로 설정할 경우 API Gateway는 유효 시간 체크를 하지 않습니다.
    • 필수 검증 헤더 목록: API 요청 검증에 필수로 포함할 헤더 목록을 작성합니다. 여러 개를 입력하려면 콤마(,)로 구분하여 입력합니다.

[참고] HMAC 인증 실패 응답 HMAC 인증 실패 시 401 Unauthorized 응답이 반환됩니다.

[주의] 요청 유효 시간 - 0초로 설정할 경우, 요청 유효 시간을 체크하지 않습니다. 이 경우 Reply Attack 공격에 취약할 수 있습니다. - 유효 시간을 너무 작게 설정하면 API Gateway가 요청을 검증하기 전 유효 시간이 초과되어 요청이 거부될 수 있습니다. 기대하는 요청 유효 시간보다 10초 이상 크게 설정하기를 권장합니다. - API 클라이언트는 시간 동기화 설정 NTP(Network Time Protocol)이 유효한지 반드시 검증하시기 바랍니다. 동기화되지 않은 시간 정보로 인해 요청이 거부될 수 있습니다.

[참고] 필수 검증 헤더 필수 검증 헤더를 설정한 경우, API 요청 검증 시 필수 검증 헤더가 요청에 포함되었는지와 signature에도 해당 헤더가 포함된 값인지 검증합니다. 설정 시 필수 검증 헤더가 요청과 singature 생성 시 포함되었는지 확인하시기 바랍니다.

HMAC 인증을 위한 API 클라이언트 작업

HMAC 인증을 하려면 API 요청 클라이언트는 다음의 인증 헤더와 요청 시간 헤더를 포함하여 요청해야 합니다.

헤더 이름 헤더값
Authorization hmac algorithm="<encrypt_algorithm>", headers="<validation_headers>", signature="<base64_digest>"
x-nhn-date ISO8601 형식의 시간

[참고] x-nhn-date의 ISO8601 형식 - UTC 표기: yyyy-MM-dd'T'HH:mm:ssZ - UTC 기준 타임 오프셋 표기: yyyy-MM-dd'T'HH:mm:ss±hh:mm

  • Authorization 또는 x-nhn-date 헤더가 요청에 포함되지 않은 경우 HMAC 인증에 실패합니다.

  • Authorization 헤더값은 다음과 같이 생성합니다.

Credential 이름
algorithm HmacSHA256 또는 HmacSHA1
headers HMAC 인증 시 검증할 헤더 목록
콘솔에서 HMAC 필수 검증 헤더에 등록한 헤더는 반드시 포함해야 합니다.
signature SiginToString 문자열을 암호화한 후 Base64 인코딩한 값

SignToString 형식

[HTTP Method]\n
[Request URL]\n
[Request datetime]\n
[header1-name]:[value1]\n
[header2-name]:[value1,value2...]\n
...

SignToString 예시

  • HTTP 요청 원문
GET /members?isEnable=false&type=public HTTP/1.1
Host: http://kr1-example.api.nhncloudservice.com
x-nhn-date: 2021-02-23T00:00:00+09:00
x-nhn-client-id: nhn
x-nhn-client-ip: 10.0.0.1,10.0.0.2
  • HTTP 요청 원문에 대한 SignToString
GET
/members?isEnable=false&type=public
2021-02-23T00:00:00+09:00
host:kr1-example.api.nhncloudservice.com
x-nhn-client-id: nhn
x-nhn-client-ip: 10.0.0.1,10.0.0.2
  • signature 생성 코드 예시(Java): SignToString을 HMAC 암호화 후 Base64 인코딩 한 값
String secretKey = "HMAC에 설정한 비밀키";
// 암호화 알고리즘 HmacSHA1 또는 HmacSHA256
SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");  
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(signingKey);

String message = "StringToSign";
byte[] rawHmac;
rawHmac = mac.doFinal(message.getBytes());
String authorization = new String(Base64.encodeBase64(rawHmac));
  • 완성된 HMAC 인증 헤더
Authorization:hmac algorithm="HmacSHA256", headers="host,x-nhn-client-id,x-nhn-client-ip" , signature="V5Dye9kgG3tvZOOZertd5LXE0q8CcJGXCxEFCR71hUE="
x-nhn-date:2021-02-23T00:00:00+09:00

[주의] SignToString 생성 주의 사항 - SignToString 각 필드는 개행 문자(\n)로 구분합니다. - headers에 정의된 헤더는 SignToString 생성 시 포함되어야합니다. - headers에 정의한 헤더가 없는 경우, [header name]과 [header value]은 SignToString 생성에 포함하지 않습니다. - headers에 정의한 헤더 순서대로 SignToString을 생성해야 합니다. - 예: headers="header1,header2" 라면, SignToString을 생성할 때도 header1, header2 순서대로 헤더를 추가해야 합니다. - SignToString의 헤더 이름은 영소문자(lowercase) 로 통일한 후 생성합니다. - 예: X-NHN-Header → x-nhn-header - 헤더값이 여러 개인 경우, 콤마(,)로 구분하여 헤더값을 작성합니다. - 예: header1-name:header1-value1,header1-value2 - 헤더 이름과 값은 콜론(:)으로 구분하며, 값 구분 시 중간에 공백 문자를 포함하지 않습니다.

인증 > JWT

JWT 토큰의 서명과 클레임을 검증합니다. 사용자 서비스에서는 토큰을 검증하지 않고 토큰값을 사용할 수 있습니다.

  1. 스테이지 탭에서 스테이지를 선택합니다.
  2. 설정 탭을 선택합니다.
  3. 스테이지 트리 화면에서 스테이지의 루트(/) 경로를 선택합니다.
  4. 인증에서 JWT를 선택합니다.
  5. JWT 설정을 입력합니다.
    • 토큰 암호화 알고리즘: 토큰을 서명할 때 이용한 암호화 알고리즘을 선택합니다. 암호화 알고리즘은 HS256, RS256 을 지원합니다.
      • HS256 토큰 알고리즘
        • 비밀키: 토큰을 서명하는데 사용한 비밀키를 입력합니다. 비밀키의 길이가 256이상인 비밀키의 사용을 권장합니다.
      • RS256 토큰 알고리즘
        • 공개키(PEM): 토큰을 검증할 수 있는 공개키를 입력합니다. PEM 형식으로 입력해야합니다.
        • JWKS URI: API Gateway가 토큰 서명 검증과 암호화에 필요한 Json Web Key Sets Json객체를 가져올 HTTP JWKS(Json Web Key Sets) URI를 입력합니다.
    • 클레임 검증 조건
      • 토큰의 페이로드(payload)의 등록된 클레임(registered claim)에 대한 클레임 검증 조건을 입력합니다.
      • 등록된 클레임에 대한 자세한 내용은 RFC7519-4.1.Registered Claim Names을 참고합니다.
      • 클레임 검증 조건 중 하나라도 일치하지 않는 경우, 인증에 실패합니다.
      • 클레임: 토큰의 페이로드(payload)의 등록된 클레임(registered claim) 이름 입니다.
      • 데이터 타입과 클레임 값:
        • Array: 복수 개의 문자열을 콤마(,)로 분리하여 입력합니다. 입력된 문자열 배열에 요청 토큰의 클레임 값 중 하나라도 포함되면 검증을 통과합니다.
        • String: 단일 문자열을 입력합니다. 요청 토큰의 클레임 값과 일치하면 검증을 통과합니다.
      • 필수: 선택시 요청 토큰에 클레임이 존재하지 않으면 검증에 실패합니다. 비활성화된 체크박스는 선택 변경이 불가합니다.
      • 값 검증: 선택시 요청 토큰에 클레임이 존재하면 설정된 클레임 값에 포함되거나 일치하는지 검증합니다. 비활성화된 체크박스는 선택 변경이 불가합니다.
    • 검증 유효 시간(초): 요청 토큰의 nbp, exp 클레임 검증시 검증 유효 시간을 적용하여 검증합니다. 0~86400(초)까지 입력할 수 있습니다.
  6. 스테이지를 배포합니다.
  7. API Gateway 요청시 Authorization 헤더에 JWT 토큰을 추가하여 요청합니다.
헤더 이름 헤더값
Authorization Bearer "<jwt-token>"

[참고] JWT 토큰 인증 실패 응답 JWT 토큰 인증 실패시 401 Unauthorized 응답이 반환됩니다. 자세한 내용은 오류 코드 문서를 참고합니다.

[참고] JWT 토큰 생성 API Gateway는 JWT 토큰의 서명과 클레임 조건과 일치하는지만 검증합니다. JWT 토큰 생성은 사용자의 애플리케이션 또는 인증 서비스 제공자를 통해 생성해야합니다. 개발 및 테스트목적의 JWT 토큰 생성은 JWT 토큰 디버거를 참고합니다.

[참고] JWKS(Json Web Key Sets) URI 설명 및 주의사항 JWKS은 API Gateway가 토큰 서명을 검증하기 위해 필요한 JWK(Json Web Key) 암호화 키에 대한 JSON 데이터입니다. JWK에 대한 자세한 내용과 사양은 RFC7515 문서를 참고합니다. 설정된 JWKS URI는 API Gateway가 접근할 수 있도록 공개되어 있어야 하며, 네트워크, 방화벽 등에 의해 차단되지 않도록 합니다. 설정된 JWKS URI는 API Gateway가 항상 접근이 가능하도록 운영되어야 합니다.

[주의] JWKS 캐싱 API Gateway는 JWKS URI의 응답을 5분간 캐싱합니다. API Gateway의 캐싱으로 인해 JWKS 변경 사항이 API Gateway에 반영되기까지 최대 5분 이상 소요될 수 있습니다.

사전 호출 API(Pre-call API)

사전 호출 API는 백엔드 엔드포인트를 호출하기 전에 사용자가 지정한 API를 호출하여 호출의 응답 코드에 따라 백엔드 엔드포인트 호출 여부를 결정합니다. API Gateway를 통해 들어온 요청 헤더를 포함하여 사전 호출 API를 호출하고, 사전 호출 API에서는 전달받은 헤더 내용에 따라 응답 코드를 반환합니다.

사전 호출 API의 응답 코드가 200이면 백엔드 엔드포인트를 호출하고, 응답 코드가 200이 아니면 사전 호출 API의 응답 결과를 반환합니다. 만약, 사전 호출 API 호출에 실패하면 오류를 반환합니다.

백엔드 엔드포인트를 호출하기 전에 별도 API 호출을 통한 인증이 필요하거나 먼저 호출되어야하는 API가 존재하는 등의 경우에 활용이 가능합니다.

  1. 스테이지 탭에서 스테이지를 선택합니다.
  2. 설정 탭을 선택합니다.
  3. 스테이지 트리 화면에서 사전 호출 API를 적용할 경로나 메서드를 선택합니다.
  4. 경로에서 설정한 사전 호출 API는 하위 정의된 모든 하위 경로와 메서드 호출에 대해서 적용됩니다.
  5. 메서드에서 설정한 사전 호출 API는 해당 메서드를 호출 시 적용되며, 루트 경로에서 설정된 사전 호출 API는 적용되지 않습니다.
  6. 사전 호출 API를 활성화(on)합니다.
  7. 사전 호출 API의 메서드 타입과 URL을 입력합니다.
  8. 캐시 유효 시간은 최대 86400초까지 입력할 수 있으며, 입력된 숫자(초)만큼 사전 호출 API(Pre-call API)의 응답 결과가 캐싱됩니다.
  9. 캐시 유효 시간을 0으로 입력할 경우 사전 호출 API(Pre-call API)의 응답 결과가 캐싱되지 않으며, 매 요청마다 사전 호출 API(Pre-call API)를 호출합니다.

[참고] 사전 호출 API의 응답 결과 캐싱 사전 호출 API의 응답 결과 코드가 200일 경우에만 응답 결과가 캐싱됩니다. 응답 결과 코드가 200이 아닌 경우, 캐시 유효 시간이 설정되어 있더라도 응답 결과가 캐싱되지 않습니다.

백엔드 엔드포인트 URL 재정의

API Gateway로 수신된 요청을 백엔드 엔드포인트로 전달할 때 기본으로 스테이지에 정의된 백엔드 엔드포인트 URL로 요청을 전달합니다. 특정 경로 또는 메서드에 대해 백엔드 엔드포인트 URL을 재정의하려면 백엔드 엔드포인트 URL 재정의를 설정합니다.

  1. 스테이지 탭에서 스테이지를 선택합니다.
  2. 설정 탭을 선택합니다.
  3. 스테이지 트리 화면에서 백엔드 엔드포인트 URL을 재정의할 경로 또는 메서드를 선택합니다.
  4. 백엔드 엔드포인트 URL의 재정의를 활성화(on)합니다.
    • API Gateway로 수신된 요청을 전달할 백엔드 엔드포인트 URL을 작성합니다.
    • 하위 경로를 포함하여 작성할 수 있습니다.
      • 예: https://api.nhn.com , https://api.nhn.com/apis

요청 수 제한

요청 수 제한을 통해 API Gateway로 수신되는 요청들의 초당 요청 수를 조절할 수 있으며, 이를 통해 백엔드 엔드포인트를 보호할 수 있습니다.

  1. 스테이지 탭에서 스테이지를 선택합니다.
  2. 설정 탭을 선택합니다.
  3. 스테이지 트리 화면에서 스테이지의 루트(/) 경로 또는 메서드를 선택합니다.
    • 루트 경로에 설정하면 스테이지에 요청 수 제한이 적용됩니다.
    • 메서드에 설정하면 각 메서드마다 요청 수 제한이 적용됩니다. 상위 경로에 설정한 요청 수 제한은 무시됩니다.
  4. 요청 수 제한을 활성화(On) 합니다.
  5. 요청 수 제한을 설정합니다.
    • 초당 요청 수: 초당 호출 가능한 최대 요청 수를 입력합니다.
    • 요청 제한 키: 기본 요청 제한 키는 루트에 설정된 경우 스테이지이고, 메서드에 설정된 경우 선택된 메서드입니다. 기본 요청 제한 키에 요청 제한 키를 추가할 수 있습니다.
      • None: 기본 요청 제한 키로 요청을 제한합니다.
      • 경로 변수: 기본 요청 제한 키와 경로 변수값 별로 요청을 제한합니다. 선택된 메서드의 경로에 경로 변수가 있는 경우에만 설정 가능합니다.
      • IP: 기본 요청 제한 키와 요청 클라이언트 IP 별로 요청을 제한합니다.
      • 헤더: 기본 요청 제한 키와 설정한 헤더 이름의 값별로 요청을 제한합니다.

[참고] 요청 수 제한 응답 초당 요청 수 초과 시 429 Too Many Requests 응답이 반환됩니다.

[주의] 요청 제한 키 요청 제한 키를 사용하는 경우, 요청에 지정한 키가 포함되어야 합니다. 예를 들어 요청 제한 키로 헤더를 선택하고, X-NHN-CLOUD 값을 입력했다면, 요청 헤더에는 X-NHN-CLOUD가 포함되어야 합니다.
요청에서 요청 제한 키를 찾을 수 없는 경우, 요청 수 제한이 적용되지 않습니다.

[주의] 초당 요청 수 정확도 - 설정된 초당 요청 수와 허용되는 실제 요청 수는 요청이 API Gateway에 수신된 시간, 요청 처리 시간 및 기타 요인에 따라 정확히 일치하지 않을 수 있습니다.

API Key

API Gateway에 API 요청 시 지정된 API Key만 요청할 수 있도록 제한합니다.

[참고] API Key 실패 응답 API Key 값이 요청 헤더에 포함되지 않거나 유효하지 않거나 사용량 한도를 초과할 경우 API 요청이 거부됩니다. 자세한 내용은 오류 코드 문서를 참고합니다.

  1. 스테이지 탭에서 스테이지를 선택합니다.
  2. 설정 탭을 선택합니다.
  3. 스테이지 트리 화면에서 API Key를 활성화할 경로나 메서드를 선택합니다.
    • 경로에서 설정한 API Key는 하위 정의된 모든 하위 경로와 메서드 호출에 대해서 적용됩니다.
  4. API Key를 활성화(on)합니다.
  5. 스테이지를 배포합니다.
  6. API 요청시 x-nhn-apikey 헤더에 API Key 값을 추가하여 요청합니다.
헤더 이름 헤더값
x-nhn-apikey <primary api key 또는 secondary api key>

API 호출 확인

  1. 스테이지 탭 내 설정 탭에서 스테이지 트리의 메서드를 선택합니다.
  2. 우측의 스테이지 URL을 확인합니다.
  3. 스테이지 URL를 지정된 HTTP 메서드로 API를 호출합니다.
    • 예시:
      • 메서드: GET
      • 스테이지 URL: https://kr1-xxxxx-test.api.nhncloudservice.com/example curl --request GET 'https://kr1-xxxxx-test.api.nhncloudservice.com/example'

[주의] 스테이지 배포 API를 호출하려면 배포 성공 상태의 배포된 스테이지가 있어야 합니다.

[참고] API 호출이 정상적으로 안 되는 경우 - 404 NotFound HTTP 상태 코드가 응답되는 경우 1. 스테이지를 배포 상태가 배포 성공 상태인지 확인합니다. 2. 요청 메서드와 스테이지 URL 및 경로가 올바른지 확인합니다. 3. 백엔드 엔드포인트 서비스에서 백엔드 엔드포인트 URL 경로에 대한 요청 URL이 존재하는지 확인합니다. - 그 외 오류 코드는 오류 코드 문서를 참고합니다.

[주의] API 호출 제약 사항 - Gateway 클라이언트에서 API Gateway로 요청 크기 제한은 최대 10MB입니다. 이 값은 조정할 수 없습니다. - API Gateway에서 Gateway 클라이언트로의 응답 크기 제한은 최대 10MB입니다. 이 값은 조정할 수 없습니다. - 요청에 대한 응답 타임아웃은 최대 60초입니다. 백엔드 엔드포인트 서비스에서 응답이 지연되는 경우 타임아웃이 발생할 수 있습니다.

[주의] API Gateway 요청 차단 정책 - API Gateway 서비스와 백엔드 엔드포인트 서비스를 보호하는 목적으로 백엔드 엔드포인트 서비스가 응답을 하지 않거나 응답 지연(60초 이상)이 지속적으로 발생하는 경우, 해당 백엔드 엔드포인트 서비스에 대한 요청을 일시적으로 거부합니다. - 백엔드 엔드포인트 서비스의 내부 오류(4xx, 5xx 등)에 의해서는 차단되지 않습니다. - 정상적으로 운영 중인 상태가 아니거나 응답 지연(timeout)이 60초 이상이 지연이 발생하는 백엔드 엔드포인트는 연동하지 않는 것을 권장합니다.

대시보드

대시보드를 통해 API Gateway 서비스, API Key별 API 통계 지표를 확인할 수 있습니다.

스테이지 탭

  1. 대시보드 탭으로 이동합니다.
  2. 스테이지 탭으로 이동합니다.
  3. 통계를 확인할 API Gateway 서비스를 선택합니다.
  4. 통계를 확인할 스테이지를 목록에서 선택합니다.
  5. 하단의 스테이지 통계 탭에서는 스테이지의 통계 지표를 확인할 수 있습니다.
  6. 하단의 리소스 통계 탭에서는 HTTP 메서드와 경로별 통계 지표를 확인할 수 있습니다.

통계 데이터 참고 사항

  • 최대 검색 기간
    • 최근 3개월간의 통계 데이터만 조회가 가능합니다.
  • 통계 데이터 생성 주기
    • 모든 시간 단위(1분, 10분, 1시간, 1일)의 통계 데이터는 매 분 갱신됩니다.
    • 통계 데이터는 수집되는 데이터 크기에 따라 생성이 지연될 수 있습니다.

스테이지 통계

  • 그래프 표시 기준
    • 검색 기간에 따라 통계의 단위는 다음과 같이 표시됩니다.
      • 1시간 이하: 1분 단위
      • 1시간 초과~1일 이하: 10분 단위
      • 1일 초과~1주 이하: 1시간 단위
      • 1주 초과: 1일 단위
  • 통계 그래프
    • API 호출 성공 수: 응답된 HTTP 상태 코드가 2XX, 3XX인 API 호출 수
    • API 호출 실패 수: 응답된 HTTP 상태 코드가 4XX, 5XX인 API 호출 수
    • 평균 응답 시간(ms): API Gateway로 요청이 인입된 후, API 요청 클라이언트에게 응답을 주기까지 소요된 평균 시간(ms)
    • 네트워크 아웃바운드 트래픽: API Gateway에서 API 요청 클라이언트로 응답된 데이터의 바이트 크기

리소스 통계

리소스 경로와 HTTP 메서드별로 구분된 상세한 통계 지표를 확인할 수 있습니다.

  • HTTP 메서드: 요청된 HTTP 메서드
  • 경로: 요청과 매핑된 리소스 경로
  • API 호출 성공 수: 응답된 HTTP 상태 코드가 2XX, 3XX인 API 호출 수
  • API 호출 실패 수: 응답된 HTTP 상태 코드가 4XX, 5XX 인 API 호출 수
  • HTTP 2XX~5XX 코드: 상태 코드 그룹별 API 호출 수
  • API Gateway에서 바로 응답된 수: 백엔드 엔드포인트 서비스로 요청을 전달하지 않고 API Gateway에서 응답이 된 API 호출 수
  • 평균 응답 시간(ms): API Gateway로 요청이 인입된 후 API 요청 클라이언트에게 응답을 주기까지 소요된 평균 시간(ms)
  • 네트워크 아웃바운드 트래픽: API Gateway에서 API 요청 클라이언트로 응답된 데이터의 바이트 크기

API Key 통계

각 API Key별 호출 수를 일 단위 그래프로 확인할 수 있습니다.

  1. 대시보드 탭으로 이동합니다.
  2. API Key 탭으로 이동합니다.
  3. 통계를 확인할 API Key를 선택합니다.
    • 그래프 표시 기준
      • 검색 기간 설정은 일 단위로 할 수 있으며, 1일 단위로 표시됩니다.
    • 통계 그래프
      • API 호출 수: API Key가 사용된 모든 API 호출 수
      • API Gateway에서 바로 응답된 수: API Gateway 플러그인이나 사용량 제한을 통과하지 못하고 API Gateway에서 응답이 된 API 호출 수

사용량 계획

사용량 계획의 스테이지에 연결된 API Key만 스테이지 API를 요청할 수 있도록 제한할 수 있으며, 사용량 제어 설정을 통해 연결된 API Key마다 공통 사용량 제한을 적용할 수 있습니다.

  • 사용량 계획을 API Gateway 서비스에 적용하기 위해서는 다음의 과정이 필요합니다.
  • 사용량 계획 생성 -> 사용량 계획에 스테이지 연결 -> 사용량 계획이 연결된 스테이지에 API Key 연결 -> 스테이지 설정에서 API Key 활성화
  • 사용량 계획 생성 및 스테이지, API Key 연결 과정에 대한 자세한 내용은 아래를 참고하세요.

사용량 계획 생성

  1. 사용량 계획 목록에서 사용량 계획 생성 버튼을 클릭합니다.
  2. 사용량 계획 정보를 입력한 후 생성 버튼을 클릭합니다.
    • 사용량 계획 이름: 사용량 계획의 이름입니다.
    • 사용량 계획 설명: 사용량 계획의 설명입니다(선택 사항).
    • 초당 요청 수 제한: 초당 호출 가능한 최대 요청 수를 입력합니다(선택 사항).
    • 할당량 기간 단위: 일/월별 호출 가능한 최대 요청 수를 입력합니다(선택 사항).
    • 요청 할당량: 할당량 기간 단위를 설정하면 입력할 수 있으며, 지정된 할당량 기간 동안 호출 가능한 최대 요청 수를 입력합니다.

[참고] 요청 할당량 한도 재설정 요청 할당량은 매월 1일(월별 기간), 매일(일별 기간) UTC 00:00:00에 재설정됩니다.

사용량 계획 수정

  1. 사용량 계획 목록에서 수정할 사용량 계획을 선택합니다.
  2. 수정 버튼을 클릭합니다.
  3. 사용량 계획 정보를 수정합니다.
  4. 설정을 변경한 후 수정 버튼을 클릭합니다.

[주의] 사용량 계획 요청 제어 설정 수정 사용량 계획에서 초당 요청 수 제한, 요청 할당량을 수정할 경우, 별도 배포 절차 없이 연결된 API에 반영됩니다. 할당량 기간 단위를 '일' 또는 '월'으로 수정하면, 연결된 API Key 요청 할당량의 사용량은 유지됩니다. 요청 할당량 한도를 낮추면 사용량이 초과될 수 있습니다. 할당량 기간 단위를 '없음'으로 수정하면 연결된 API Key들의 요청 할당량 사용량은 초기화됩니다.

사용량 계획 삭제

  1. 사용량 계획 목록에서 삭제할 사용량 계획을 선택합니다.
  2. 삭제 버튼을 클릭하면 삭제 확인 창이 표시됩니다.
  3. 확인 창이 나타나면 확인 버튼을 클릭합니다. 삭제된 데이터는 복구할 수 없습니다.

[참고] 연결된 스테이지가 있는 경우 사용량 계획 삭제 불가 사용량 계획과 연결된 스테이지들을 모두 해제한 후 사용량 계획을 삭제할 수 있습니다.

사용량 계획에 스테이지 연결

API Key가 요청 가능한 스테이지들을 정의하기 위해 사용량 계획에 스테이지를 연결합니다.

  1. 사용량 계획 목록에서 사용량 계획 이름 열의 이름 링크를 클릭합니다.
  2. 스테이지 연결 버튼을 클릭합니다.
  3. 연결할 API Gateway 서비스와 스테이지를 선택한 후 확인 버튼을 클릭합니다.

[참고] 이미 연결된 스테이지 이미 연결된 스테이지는 선택 목록에 노출되지 않습니다.

사용량 계획에 연결된 스테이지 해제

  1. 사용량 계획 목록에서 사용량 계획 이름 열의 이름 링크를 클릭합니다.
  2. 연결된 스테이지 목록에서 연결 해제할 스테이지를 선택합니다.
  3. 스테이지 연결 해제 버튼을 클릭합니다.
  4. 확인 창이 나타나면 확인 버튼을 클릭합니다.

[참고] 연결된 API Key가 있는 경우 스테이지 해제 불가 사용량 계획에 연결된 스테이지를 해제하기 위해서는 스테이지에 연결된 모든 API Key를 해제해야 합니다.

API Key 연결

사용량 계획에 연결된 스테이지의 API를 호출하기 위해서 API Key를 연결합니다.

  1. 사용량 계획 목록에서 사용량 계획 이름 열의 이름 링크를 클릭합니다.
  2. 연결된 스테이지 목록에서 API Key를 연결할 스테이지를 선택합니다.
  3. 하단의 API Key 연결 버튼을 클릭합니다.
  4. 추가할 API Key를 선택한 후 확인 버튼을 클릭합니다.

[참고] 다른 사용량 계획의 동일 스테이지에 연결된 API Key는 선택할 수 있는 목록에 노출되지 않으며, 연결할 수 없습니다.

API Key 연결 해제

  1. 사용량 계획 목록에서 사용량 계획 이름 열의 이름 링크를 클릭합니다.
  2. 연결된 스테이지 목록에서 API Key를 연결 해제할 스테이지를 선택합니다.
  3. 하단 목록에서 연결 해제할 API Key를 선택한 후 API Key 연결 해제 버튼을 클릭합니다.
  4. 확인 창이 나타나면 확인 버튼을 클릭합니다.

API Key의 사용량 계획 변경

  1. 사용량 계획 목록에서 사용량 계획 이름 열의 이름 링크를 클릭합니다.
  2. 연결된 스테이지 목록에서 사용량 계획을 변경할 API Key가 존재하는 스테이지를 선택합니다.
  3. 하단 목록에서 사용량 계획을 변경할 API Key를 선택한 후 사용량 계획 변경 버튼을 클릭합니다.
  4. 변경할 사용량 계획을 선택한 후 확인 버튼을 클릭합니다.

[참고] 선택한 스테이지가 연결된 다른 사용량 계획으로만 변경할 수 있습니다.

[주의] 사용량 계획 변경시 API Key 요청 할당량의 사용량 초기화 할당량 기간 단위가 '일' 또는 '월'인 사용량 계획으로 변경하면, 연결된 API Key 요청 할당량의 사용량은 유지됩니다. 요청 할당량 한도가 낮은 사용량 계획으로 변경 시 사용량이 초과될 수 있습니다. 할당량 기간 단위가 '없음'인 사용량 계획으로 변경하면, 연결된 API Key 요청 할당량의 사용량은 초기화됩니다.

API Key

  • API Key에서는 사용량 계획, 스테이지와 연결되어 API Gateway 서비스 API 접근을 위한 문자열 값을 관리합니다.
  • API 요청 시 API Key 값으로 Primary API Key, Secondary API Key를 사용할 수 있습니다.

API Key 생성

  1. API Key 목록에서 API Key 생성 버튼을 클릭합니다.
  2. API Key 정보를 입력한 후 생성 버튼을 클릭합니다.
    • API Key 이름: API Key의 이름입니다.
    • API Key 설명: API Key의 설명입니다. (선택사항)
    • API Key 상태: API Key의 활성화 상태를 선택합니다.
      • ACTIVE: API Key가 활성화되어 사용할 수 있는 상태입니다.
      • INACTIVE: API Key가 비활성화되어 사용할 수 없는 상태입니다.

API Key 수정

  1. API Key 목록에서 수정할 API Key를 선택합니다.
  2. 수정 버튼을 클릭합니다.
  3. API Key 정보를 수정합니다. 수정 가능한 항목은 API Key 이름, API Key 설명, API Key 상태입니다.
  4. 설정을 변경한 후 수정 버튼을 클릭합니다.

[주의] API Key 상태 변경 API Key 상태를 INACTIVE로 변경하면 해당 API Key를 사용할 수 없습니다.

API Key 삭제

  1. API Key 목록에서 삭제할 API Key를 선택합니다.
  2. 삭제 버튼을 클릭하면 삭제 확인 창이 표시됩니다.
  3. 확인 창이 나타나면 확인 버튼을 클릭합니다. 삭제된 데이터는 복구할 수 없습니다.

[참고] 연결된 사용량 계획, 스테이지가 있는 경우 삭제 불가 연결된 사용량 계획, 스테이지가 있는 경우 API Key를 삭제할 수 없습니다.

API Key 재발급

API 요청 시 API Key 값으로 사용되는 Primary API Key, Secondary API Key는 각각 재발급할 수 있습니다.

  1. API Key 목록에서 API Key를 선택합니다.
  2. 하단의 API Key 탭을 선택합니다.
  3. Primary API Key, Secondary API Key 항목 옆 재발급 버튼을 클릭하면 확인 창이 표시됩니다.
  4. 확인 창이 나타나면 확인 버튼을 클릭합니다.
    • 재발급할 경우 이전 API Key 값은 더 이상 유효하지 않게 됩니다.

API Key와 연결된 스테이지

  1. API Key 목록에서 API Key를 선택합니다.
  2. 하단의 연결된 스테이지 탭을 선택합니다.
  3. 연결된 스테이지 목록을 확인할 수 있습니다.
    • 스테이지 URL: 연결되어 있는 스테이지 URL입니다.
    • 사용량 계획: 연결되어 있는 사용량 계획 정보입니다.
TOP