415 지원되지 않는 미디어 유형 - 지원되지 않는 인코딩

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

증상

클라이언트 애플리케이션은 API 호출에 대한 응답으로 오류 코드 protocol.http.UnsupportedEncoding 와 함께 HTTP 상태 코드 415 Unsupported Media Type를 가져옵니다.

오류 메시지

클라이언트 애플리케이션은 다음 응답 코드를 가져옵니다. 

HTTP/1.1 415 Unsupported Media Type

또한 아래와 유사한 오류 메시지가 표시될 수 있습니다. 

{
   "fault":{
      "faultstring":"Unsupported Encoding \"UTF-8\"",
      "detail":{
         "errorcode":"protocol.http.UnsupportedEncoding"
      }
   }
}

가능한 원인

이 오류는 클라이언트가 Apigee로 전송하는 HTTP 요청 또는 백엔드 서버가 Apigee로 보낸 HTTP 응답에 지정된 Content-Encoding 헤더의 값에 RFC 7231, 섹션 6.5.13: 415 지원되지 않는 미디어 유형 사양에 따라 Apigee에서 지원하는 인코딩이 포함되지 않은 경우에 발생합니다.

이 오류가 발생할 수 있는 원인은 다음과 같습니다.

원인 설명 다음에 관한 문제 해결 안내
요청에 지원되지 않는 인코딩이 사용됨 요청 헤더 Content-Encoding에 Apigee Edge에서 지원하지 않는 인코딩이 포함되어 있습니다. Edge 퍼블릭 및 프라이빗 클라우드 사용자
응답에 지원되지 않는 인코딩이 사용됨 백엔드 서버 응답 헤더 Content-Encoding에 Apigee Edge에서 지원하지 않는 인코딩이 포함되어 있습니다. Edge 퍼블릭 및 프라이빗 클라우드 사용자

일반적인 진단 단계

오류를 진단하려면 다음 방법 중 하나를 사용하면 됩니다.

API 모니터링

API 모니터링을 사용하여 오류를 진단하려면 다음 안내를 따르세요.

  1. Apigee Edge 계정에 로그인합니다.

  2. 문제를 조사하려는 조직으로 전환합니다.

    UI 조직 드롭다운
  3. 분석 > API 모니터링 > 조사 페이지로 이동합니다.
  4. 오류를 관찰한 특정 기간을 선택합니다.
  5. 프록시 필터가 모두로 설정되어 있는지 확인합니다.
  6. 시간을 기준으로 결함 코드를 표시합니다.

  7. 아래와 같이 오류 코드가 protocol.http.UnsupportedEncoding인 셀을 선택합니다.

    오류 코드 셀 선택됨

  8. 오류 코드 protocol.http.UnsupportedEncoding에 관한 정보가 아래와 같이 표시됩니다.

  9. 로그 보기 를 클릭하고 415 오류와 함께 실패한 요청 중 하나를 펼쳐 자세한 정보를 확인합니다.

  10. 로그 창에서 다음 세부정보를 확인합니다.
    • Fault Source(오류 소스): apigee 또는 target에서 오류가 반환되었음을 표시합니다.
    • 오류 코드: protocol.http.UnsupportedEncoding와 일치해야 합니다.
  11. 오류 소스가 apigee이면 요청의 Content-Encoding 헤더에 지원되지 않는 인코딩이 포함되어 있음을 나타냅니다.
  12. 오류 소스가 target이면 백엔드 서버 응답의 Content-Encoding 헤더에 지원되지 않는 인코딩이 포함되어 있음을 나타냅니다.

추적 도구

Trace 도구를 사용하여 오류를 진단하려면 다음 단계를 따르세요.

  1. 트레이스 세션을 사용 설정하고 다음 중 하나를 사용 설정합니다.
    • 415 Unsupported Media Type 오류가 발생할 때까지 기다립니다.
    • 문제를 재현할 수 있는 경우 API를 호출하여 415 Unsupported Media Type 오류를 재현합니다.

  2. Show all FlowInfos(모든 FlowInfos 표시)가 사용 설정되어 있는지 확인합니다.

    뷰 옵션 창, 모든 흐름 정보 표시
  3. 실패한 요청 중 하나를 선택하고 트레이스를 검사합니다.
  4. trace의 여러 단계를 살펴보고 실패가 발생한 위치를 찾습니다.

  5. 일반적으로 이 오류는 아래와 같이 요청이 대상 서버로 전송 단계 후의 흐름에서 찾을 수 있습니다.

  6. 트레이스에서 오류 값을 기록해 둡니다.

    위의 샘플 trace는 오류를 Unsupported Encoding "utf-8"로 보여줍니다. 요청이 백엔드 서버로 전송된 후 Apigee에서 오류가 발생하므로 백엔드 서버가 Apigee에서 지원되는 인코딩이 아닌 "utf-8" 값과 함께 응답 헤더 Content-Encoding을 전송했음을 나타냅니다.

  7. 추적에서 AX (애널리틱스 데이터 기록됨) 단계로 이동하여 클릭합니다.

  8. 단계 세부정보 패널의 오류 / 응답 헤더 섹션까지 아래로 스크롤하고 아래와 같이 X-Apigee-fault-code 및 X-Apigee-fault-source의 값을 확인합니다.

  9. X-Apigee-fault-code 및 X-Apigee-fault-source의 값은 protocol.http.UnsupportedEncoding 및 target로 표시됩니다. 이는 지원되지 않는 인코딩 값 "utf-8"이 응답 헤더 Content-Encoding의 백엔드 서버에 의해 전달되었기 때문에 이 오류가 발생했음을 나타냅니다.

    응답 헤더 값
    X-Apigee-fault-code protocol.http.UnsupportedEncoding
    X-Apigee-fault-source target

  10. 프록시 체인을 사용 중인지 확인합니다. 즉, 대상 서버/대상 엔드포인트가 Apigee에서 다른 프록시를 호출하고 있는지 확인합니다.

    1. 이를 확인하려면 Request sent to target server로 돌아갑니다. Curl 표시를 클릭합니다.

    2. 대상 서버 호스트 별칭을 확인할 수 있는 대상 서버에 전송된 요청에 대한 Curl 창이 열립니다.
    3. 대상 서버 호스트 별칭이 가상 호스트 별칭을 가리키는 경우 프록시 체이닝이 됩니다. 이 경우 실제로 415 Unsupported Media Type 오류를 일으키는 원인을 확인할 때까지 연결된 프록시에 위의 모든 단계를 반복해야 합니다.
    4. 대상 서버 호스트 별칭이 백엔드 서버를 가리키면 백엔드 서버가 지원되지 않는 인코딩을 Apigee에 전달하고 있음을 나타냅니다.

Nginix 액세스 로그

NGINX 액세스 로그를 사용하여 오류를 진단하려면 다음 안내를 따르세요.

  1. Private Cloud 사용자는 NGINX 액세스 로그를 사용하여 HTTP 415 오류에 대한 주요 정보를 확인할 수 있습니다.

  2. NGINX 액세스 로그를 확인합니다.

    /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

  3. 특정 기간 (과거에 문제가 발생한 경우) 또는 415와 함께 여전히 실패하는 요청이 있는 경우 415 오류를 검색합니다.

  4. protocol.http.UnsupportedEncoding 값과 일치하는 X-Apigee-fault-code 가 포함된 415 오류가 있으면 X-Apigee-fault-code 의 값을 확인합니다.

    NGINX 액세스 로그의 샘플 415 오류:

    NGINX 액세스 로그의 위 샘플 항목은 X- Apigee-fault-code 및 X-Apigee-fault-source에 대한 값이 다음과 같습니다.

    응답 헤더 값
    X-Apigee-fault-code protocol.http.Response405WithoutAllowHeader
    X-Apigee-fault-source MP

    X-Apigee-fault-source 는X-Apigee-fault-source 값X-Apigee-fault-source 을 가질 수 있습니다.

원인: 요청에 지원되지 않는 인코딩

진단

  1. 일반적인 진단 단계에 설명된 대로 API Monitoring 또는 NGINX 액세스 로그를 사용하여 관찰된 오류의 오류 코드 및 오류 소스를 확인합니다.
  2. 오류 코드가 protocol.http.UnsupportedEncoding이고 오류 소스의 값이 apigee 또는 MP이면 클라이언트 애플리케이션에서 전송한 요청의 요청 헤더 Content-Encoding에 지원되지 않는 인코딩이 포함되어 있음을 나타냅니다.
  3. 다음 메서드 중 하나를 사용하여 HTTP 요청의 일부로 전달된 지원되지 않는 인코딩 값을 확인할 수 있습니다.

    오류 메시지

    오류 메시지 사용:

    1. Apigee Edge에서 받은 전체 오류 메시지에 액세스할 수 있는 경우 faultstring를 참조하세요. faultstring에는 지원되지 않는 종료 값이 포함되어 있습니다.

      오류 메시지 예:

      "faultstring":"Unsupported Encoding \"UTF-8\""

    2. 위의 오류 메시지에서 지원되지 않는 인코딩 값은 faultstring에 표시된 대로 “UTF-8”입니다.

      “UTF-8”는 Apigee Edge에서 지원되는 인코딩이 아니므로 이 요청은 415 Unsupported Media Type 오류와 함께 실패하고 오류 코드는 protocol.http.UnsupportedEncoding입니다.

    실제 요청

    실제 요청 사용:
    1. 클라이언트 애플리케이션에서 보낸 실제 요청에 액세스할 수 없는 경우 해결 방법으로 이동합니다.
    2. 클라이언트 애플리케이션에서 보낸 실제 요청에 액세스할 수 있는 경우 다음 단계를 따르세요.
      1. 요청 헤더 Content-Encoding.에 전달되는 값을 결정합니다.
      2. 요청 헤더 Content-Encoding에 전달된 값이 지원되는 인코딩에 나열된 값 중 하나가 아닐 경우, 이로 인해 이 오류가 발생합니다.

        샘플 요청:

        curl -v "https://HOSTALIAS/v1/testgzip" -H "Content-Encoding: UTF-8" -X POST -d @request_payload.gz

        위 샘플 요청은 "UTF-8" 값을 Content- Encoding 헤더로 전송합니다. 이 헤더는 Apigee Edge의 지원되는 인코딩이 아닙니다. 따라서 이 요청은 실패하고 415 Unsupported Media Type 오류(오류 코드: protocol.http.UnsupportedEncoding)가 표시됩니다.

해상도

  1. 지원되는 인코딩에서 Apigee에서 지원하는 인코딩 목록을 참조하세요.
  2. 클라이언트 애플리케이션이 항상 다음을 전송하는지 확인합니다.
    • 요청의 Content-Encoding 헤더 값으로 지원되는 인코딩만
    • Apigee Edge에 지원되는 형식의 요청 페이로드이며 Content-Encoding 헤더에 지정된 형식과 일치합니다.

  3. 위 예시에서 요청 페이로드에는 콘텐츠가 gzip여야 함을 나타내는 gz 확장 프로그램이 있습니다. 요청 헤더를 Content-Encoding: gzip으로 전송하고 요청 페이로드를 gzip 형식으로 전송하면 문제를 해결할 수 있습니다.

    curl -v "https://HOSTALIAS/v1/testgzip" -H "Content-Encoding: gzip" -X POST -d @request_payload.gz

원인: 응답에 지원되지 않는 인코딩

진단

  1. 일반적인 진단 단계에 설명된 대로 API 모니터링, Trace 도구 또는 NGINX 액세스 로그를 사용하여 관찰된 오류의 오류 코드 및 오류 소스를 확인합니다.
  2. 오류 소스의 값이 target이면 백엔드 서버에서 전송한 응답의 Content-Encoding 헤더에 지원되지 않는 인코딩이 포함되어 있음을 나타냅니다.
  3. 다음 방법 중 하나를 사용하여 백엔드 서버에서 HTTP 응답의 일부로 전달된 지원되지 않는 인코딩 값을 확인할 수 있습니다.

    오류 메시지

    오류 메시지 사용:

    1. Apigee Edge에서 받은 전체 오류 메시지에 액세스할 수 있는 경우 faultstring를 참조하세요. faultstring에 지원되지 않는 인코딩 값이 포함되어 있습니다.

      오류 메시지 샘플:

      "faultstring":"Unsupported Encoding \"UTF-8\""

    2. 위의 오류 메시지에서 지원되지 않는 인코딩 값은 faultstring에 표시된 대로 “UTF-8”입니다.

      “UTF-8”는 Apigee Edge에서 지원되는 인코딩이 아니므로 415 Unsupported Media Type 오류와 함께 이 요청이 실패하고 오류 코드는 protocol.http.UnsupportedEncoding입니다.

    추적 도구

    Trace 사용:
    1. 실패한 요청에 대한 트레이스가 없으면 해결 방법으로 이동합니다.
    2. 실패에 대한 trace를 캡처한 경우 Trace 도구에 설명된 대로 Content-Encoding 응답 헤더의 일부로 백엔드 서버에서 전달한 지원되지 않는 인코딩을 확인할 수 있습니다.

해상도

  1. 지원되는 인코딩에서 Apigee에서 지원하는 인코딩 목록을 참조하세요.
  2. 백엔드 서버에서 항상 다음을 전송하는지 확인합니다.
    • 요청의 Content-Encoding 헤더 값으로 지원되는 인코딩만
    • Apigee Edge에 지원되는 형식의 응답 페이로드이며 Content-Encoding 헤더에 지정된 형식과 일치합니다.

지원되는 인코딩

다음 표에는 Apigee Edge에서 지원하는 인코딩 형식이 나와 있습니다.

헤더 인코딩 설명
Content-Encoding gzip Unix gzip 형식
deflate 이 형식은 zlib 구조를 deflate 압축 알고리즘과 함께 사용합니다.

사양

Apigee는 다음 RFC 사양에 따라 415 Unsupported Media Type 오류 응답으로 응답합니다.

사양
RFC 7231, 섹션 6.5.13: 415 지원되지 않는 미디어 유형

핵심 사항

다음에 유의하세요.

  • API 요청의 일부로 Content-Encoding 헤더에 전달된 지원되지 않는 인코딩으로 인해 Apigee에서 415 오류를 반환하는 경우 다음을 충족해야 합니다.
    • 이러한 요청에 대한 트레이스는 캡처할 수 없습니다.

    • RaiseFault, AssignMessage와 같은 정책을 사용하면 Apigee Edge에서 전송한 오류 응답의 형식 또는 내용을 수정할 수 없습니다.

    이는 이 오류가 정책이 실행되기 전 메시지 프로세서의 초기 단계에서 발생하기 때문입니다.

  • 백엔드 서버의 응답 헤더에 지원되지 않는 인코딩이 전달되어 Apigee에서 415 오류를 반환하는 경우 백엔드 서버에서 이 오류를 수정해야 이 오류가 발생하지 않습니다. 백엔드팀과 적절하게 협력하여 이 문제를 해결하세요.

Apigee Edge 지원의 지원이 더 필요한 경우 진단 정보를 수집해야 하는 경우를 참조하세요.

진단 정보 수집 필요

Apigee 지원에서 지원이 더 필요한 경우 다음 진단 정보를 수집한 다음 Apigee Edge 지원팀에 문의하세요.

Public Cloud 사용자인 경우 다음 정보를 제공합니다.

  • 조직 이름
  • 환경 이름
  • API 프록시 이름
  • 415 오류를 재현하는 데 사용된 전체 curl 명령어
  • API 요청에 대한 추적 파일

Private Cloud 사용자인 경우 다음 정보를 제공하세요.

  • 실패한 요청에 대해 발견된 전체 오류 메시지
  • 환경 이름
  • API 프록시 번들
  • API 요청에 대한 추적 파일

  • NGINX 액세스 로그 /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

    여기서 ORG, ENV, PORT#는 실제 값으로 대체됩니다.

  • 메시지 프로세서 시스템 로그 /opt/apigee/var/log/edge-message- processor/logs/system.log