Amazon API Gateway
개발자 안내서

Amazon API Gateway 중요 정보

Amazon API Gateway REST API 및 WebSocket API의 중요 정보

  • API Gateway는 와일드카드 하위 도메인 이름(*.domain 형식)을 지원하지 않습니다. 그러나 와일드카드 인증서(와일드카드 하위 도메인 이름에 대한 인증서)를 지원합니다.

  • API Gateway는 REST 및 WebSocket API에서 사용자 지정 도메인 이름 공유를 지원하지 않습니다.

  • 단계 이름에는 영숫자, 하이픈, 밑줄만 사용할 수 있습니다. 최대 길이는 128자입니다.

  • /ping/sping 경로가 서비스 상태 확인을 위해 예약되어 있습니다. 사용자 지정 도메인이 있는 API 루트 수준의 리소스에서 이를 사용하면 정상적인 결과가 나오지 않습니다.

  • API Gateway는 현재 로그 이벤트를 1,024바이트로 제한합니다. 요청 및 응답 본문과 같이 1,024바이트가 넘는 로그 이벤트는 CloudWatch 로그에 제출되기 전에 API Gateway에서 잘립니다.

  • CloudWatch 지표는 현재 차원 이름 및 값을 유효한 XML 문자 255자로 제한합니다. (자세한 내용은 CloudWatch 사용 설명서를 참조하십시오.) 차원 값은 API 이름, 레이블(스테이지) 이름 및 리소스 이름을 포함하여 사용자가 정의한 이름의 함수입니다. 이 이름을 선택할 때는 CloudWatch 지표 제한을 초과하지 않도록 주의하십시오.

  • 매핑 템플릿의 최대 크기는 300KB입니다.

Amazon API Gateway WebSocket API의 중요 정보

  • API Gateway는 최대 프레임 크기가 32KB인 최대 128KB의 메시지 페이로드를 지원합니다. 메시지가 32KB를 초과하면 32KB 이하의 여러 프레임으로 분할해야 합니다. 이보다 더 큰 메시지가 수신되면 코드 1009와 함께 연결이 해제됩니다.

Amazon API Gateway REST API의 중요 정보

  • 임의의 요청 URL 쿼리 문자열에 대해서는 일반 텍스트 파이프 문자(|)가 지원되지 않으며 URL 인코딩되어야 합니다.

  • 임의의 요청 URL 쿼리 문자열에 대해서는 세미콜론 문자(;)가 지원되지 않으며 세미콜론 문자를 사용할 경우 데이터가 분할됩니다.

  • API Gateway 콘솔을 사용하여 API를 테스트할 때 자체 서명된 인증서를 백엔드에 제시하거나, 인증서 체인에서 중간 인증서가 누락되었거나, 기타 확인되지 않은 인증서 관련 예외가 백엔드에서 발생하는 경우, "알 수 없는 엔드포인트 오류" 응답을 받을 수 있습니다.

  • 프라이빗 통합이 포함된 API Resource 또는 Method 엔터티의 경우, VpcLink의 하드 코드된 참조를 모두 제거한 후 삭제해야 합니다. 그러지 않으면 현수 통합이 되고, Resource 또는 Method 엔터티가 삭제되어도 VPC 링크가 여전히 사용 중이라고 하는 오류를 수신하게 됩니다. 이 동작은 프라이빗 통합이 단계 변수를 통해 VpcLink를 참조할 때는 적용되지 않습니다.

  • 다음 백엔드에서는 API Gateway와 호환되는 방식으로 SSL 클라이언트 인증을 지원하지 않을 수 있습니다.

  • API Gateway는 대부분의 OpenAPI 2.0 사양OpenAPI 3.0 사양을 지원하며, 다음은 예외입니다.

    • 경로 세그먼트에는 영숫자, 하이픈, 점, 쉼표, 중괄호만 사용할 수 있습니다. 경로 파라미터는 별도의 경로 세그먼트여야 합니다. 예를 들어 "resource/{path_parameter_name}"은 유효하지만, "resource{path_parameter_name}"은 유효하지 않습니다.

    • 모델 이름에는 영숫자만 사용할 수 있습니다.

    • 파라미터 입력에는 다음과 같은 속성만 지원됩니다. name, in, required, type, description 다른 속성은 무시됩니다.

    • securitySchemes 유형을 사용할 경우 apiKey여야 합니다. 하지만 OAuth 2 및 HTTP 기본 인증은 Lambda 권한 부여자를 통해 지원되고, OpenAPI 구성은 공급자 확장 기능을 통해 가능합니다.

    • deprecated 필드는 지원되지 않으며 내보낸 API에서 제거됩니다.

    • API Gateway 모델은 OpenAPI가 사용하는 JSON 대신 JSON 스키마 draft 4를 사용하여 정의합니다.

    • additionalProperties 필드와 anyOf필드는 Models에서 지원되지 않습니다.

    • 스키마 객체에서 discriminator 파라미터는 지원되지 않습니다.

    • example 태그는 지원되지 않습니다.

    • exclusiveMinimum은 API Gateway에서 지원되지 않습니다.

    • maxItemsminItems 태그는 단순 요청 확인에 포함되지 않습니다. 이 문제를 해결하려면 확인을 수행하기 전에 가져온 후 업데이트합니다.

    • oneOf은 API Gateway에서 지원되지 않습니다.

    • readOnly 필드는 지원되지 않습니다.

    • OpenAPI 문서 루트에서는 "500": {"$ref": "#/responses/UnexpectedError"} 형식의 응답 정의를 사용할 수 없습니다. 이 문제를 해결하려면 참조를 인라인 스키마로 바꿉니다.

    • Int32 또는 Int64 유형의 숫자는 지원되지 않습니다. 예를 들면 다음과 같습니다.

      "elementId": { "description": "Working Element Id", "format": "int32", "type": "number" }
    • 10진수 형식 유형("format": "decimal")은 스키마 정의에서 지원되지 않습니다.

    • 메서드 응답에서 스키마 정의는 객체 유형이어야 하며 기본 유형일 수 없습니다. 예를 들어 "schema": { "type": "string"}은 지원되지 않습니다. 그러나 다음 객체 유형을 사용하여 이 문제를 해결할 수 있습니다.

      "schema": { "$ref": "#/definitions/StringResponse" } "definitions": { "StringResponse": { "type": "string" } }
    • API Gateway는 OpenAPI 사양에 정의된 루트 수준 보안을 사용하지 않습니다. 따라서 보안은 적절하게 적용될 수 있는 운영 수준에서 정의되어야 합니다.

  • API Gateway는 Lambda 통합 또는 HTTP 통합으로 메서드를 처리할 때 다음과 같은 제한 및 제약을 적용합니다.

    • 헤더 이름과 쿼리 파라미터는 대/소문자를 구분하여 처리합니다.

    • 다음 표에는 통합 엔드포인트로 헤더를 전송하거나 통합 엔드포인트에서 이를 다시 전송하는 경우, 끊기거나 다시 매핑되거나 수정될 수 있는 헤더가 나열됩니다. 이 표에서

      • Remapped은 헤더 이름이 <string>에서 X-Amzn-Remapped-<string>으로 변경됨을 의미합니다.

        Remapped Overwritten은 헤더 이름이 <string>에서 X-Amzn-Remapped-<string>으로 변경됨을 의미합니다.

      헤더 이름 요청(http/http_proxy/lambda) 응답(http/http_proxy/lambda)
      Age 패스스루 패스스루
      Accept 패스스루 끊김/전달/전달
      Accept-Charset 패스스루 패스스루
      Accept-Encoding 패스스루 패스스루
      Authorization 패스스루 다시 매핑됨
      Connection 전달/전달/끊김 다시 매핑됨
      Content-Encoding 전달/끊김/전달 패스스루
      Content-Length 전달(본문에 기반하여 생성됨) 패스스루
      Content-MD5 끊김 다시 매핑됨
      Content-Type 패스스루 패스스루
      Date 패스스루 재매핑됨 덮어씀
      Expect 끊김 끊김
      Host 5XX/5XX/Lambda에서 덮어씀 끊김
      Max-Forwards 끊김 다시 매핑됨
      Pragma 패스스루 패스스루
      Proxy-Authenticate 끊김 끊김
      Range 패스스루 패스스루
      Referer 패스스루 패스스루
      Server 끊김 재매핑됨 덮어씀
      TE 끊김 끊김
      Transfer-Encoding 끊김/끊김/예외 끊김
      Trailer 끊김 끊김
      Upgrade 끊김 끊김
      User-Agent 패스스루 다시 매핑됨
      Via 끊김/끊김/전달 전달/끊김/끊김
      Warn 패스스루 패스스루
      WWW-Authenticate 끊김 다시 매핑됨
  • API Gateway에서 생성된 API의 Android SDK는 java.net.HttpURLConnection 클래스를 사용합니다. Android 4.4 이전을 실행하는 장치에서 이 클래스는 WWW-Authenticate 헤더를 X-Amzn-Remapped-WWW-Authenticate에 다시 매핑하여 나온 401 응답에 대해 처리되지 않은 예외를 발생시킵니다.

  • API Gateway에서 생성한 Java, Android 및 API의 iOS SDK와 달리, API Gateway에서 생성한 API의 JavaScript SDK는 500 수준 오류에 대한 재시도를 지원하지 않습니다.

  • 메서드의 테스트 호출은 application/json의 기본 콘텐츠 유형을 사용하며 다른 콘텐츠 유형의 사양을 무시합니다.

  • X-HTTP-Method-Override 헤더를 전달하여 API에 요청을 보낼 때 API Gateway는 메서드를 재정의합니다. 따라서 헤더를 백엔드에 전달하려면 헤더를 통합 요청에 추가해야 합니다.

  • 요청의 Accept 헤더에 여러 미디어 유형이 포함되어 있는 경우 API Gateway에서는 첫 번째 Accept 미디어 유형만 인식합니다. Accept 미디어 유형의 순서를 제어할 수 없고 이진 콘텐츠의 미디어 유형이 목록의 맨 앞에 있지 않은 경우 API의 binaryMediaTypes 목록에서 첫 번째 Accept 미디어 유형을 추가할 수 있습니다. 그러면 API Gateway에서 콘텐츠를 이진 유형으로 반환합니다. 예를 들어 브라우저에서 <img> 요소를 사용하여 JPEG 파일을 보내려는 경우 브라우저에서 요청에 Accept:image/webp,image/*,*/*;q=0.8을 전송할 수 있습니다. image/webpbinaryMediaTypes 목록에 추가하여 엔드포인트에서 JPEG 파일을 이진 유형으로 수신합니다.