응답 오류 문제해결

이 페이지에서는 API에 대한 요청의 응답에서 수신되는 오류의 문제해결 방법을 설명합니다.

BAD_GATEWAY

오류 코드 13와 BAD_GATEWAY 메시지가 수신되면 확장 가능 서비스 프록시(ESP)가 서비스의 백엔드에 연결할 수 없는 경우입니다. 다음을 확인하세요.

  • 백엔드 서비스가 실행 중인지 확인합니다. 수행 방법은 백엔드에 따라 달라집니다.

  • 백엔드 서비스의 올바른 IP 주소 포트가 지정되었는지 확인합니다.
    • GKE의 경우 배포 매니페스트 파일(일반적으로 deployment.yaml)에서 ESP --backend 플래그 값(단축 옵션은 -a)을 확인합니다.
    • Compute Engine의 경우 docker run 명령어로 ESP --backend 플래그 값(단축 옵션은 -a)을 확인합니다.

reset reason: connection failure

HTTP 코드 503 또는 gRPC 코드 14와 upstream connect error or disconnect/reset before headers. reset reason: connection failure 메시지를 받은 경우 ESPv2가 서비스의 백엔드에 연결할 수 없음을 나타냅니다.

문제를 해결하려면 아래 항목을 다시 확인하세요.

백엔드 주소

ESPv2를 올바른 백엔드 주소로 구성해야 합니다. 일반적인 문제는 다음과 같습니다.

  • 백엔드 주소 스키마는 백엔드 애플리케이션 유형과 일치해야 합니다. OpenAPI 백엔드는 http://이고 gRPC 백엔드는 grpc://여야 합니다.
  • Cloud Run에 배포된 ESPv2의 경우 백엔드 주소 스키마가 https:// 또는 grpcs://여야 합니다. s는 ESPv2에 백엔드로 TLS를 설정하도록 지시합니다.

DNS 조회

기본적으로 ESPv2는 도메인 이름을 IPv6 주소로 확인하려고 시도합니다. IPv6 확인이 실패하면 ESPv2가 IPv4 주소로 돌아갑니다.

일부 네트워크에서는 대체 메커니즘이 의도한 대로 작동하지 않을 수 있습니다. 대신 ESPv2가 --backend_dns_lookup_family 플래그를 통해 IPv4 주소를 사용하도록 강제할 수 있습니다.

이 오류는 Cloud Run에 배포된 ESPv2의 서버리스 VPC 커넥터를 구성하는 경우에 일반적으로 나타납니다. VPC는 IPv6 트래픽을 지원하지 않습니다.

API is not enabled for the project

요청에 API 키를 전송한 경우 'API my-api.endpoints.example-project-12345.cloud.goog가 프로젝트에 사용 설정되지 않았습니다.'와 같은 오류 메시지는 해당 API와 다른 Google Cloud 프로젝트에서 API 키를 만들었음을 나타냅니다. 이 문제를 해결하려면 API가 연결된 것과 동일한 Google Cloud 프로젝트에서 API 키를 생성하거나 API 키가 생성된 Google Cloud 프로젝트에서 API를 사용 설정하면 됩니다.

Service control request failed with HTTP response code 403

오류 코드 14와 Service control request failed with HTTP response code 403 메시지가 수신되면 프로젝트에서 Service Control API(servicecontrol.googleapis.com)가 사용 설정되지 않은 경우입니다.

  1. 필수 서비스 확인을 참조하여 Endpoints 및 ESP에 필요한 서비스가 프로젝트에서 모두 사용 설정되었는지 확인하세요.

  2. ESP 실행 인스턴스와 연관된 서비스 계정에 필요한 모든 권한을 확인하려면 필요한 권한 확인을 참조하세요.

Method doesn't allow unregistered callers

OpenAPI 문서의 security 섹션에 API 키를 지정했지만 API 요청에서 key라는 쿼리 매개변수에 API 키가 할당되어 있지 않으면 ESP가 Method doesn't allow unregistered callers 오류로 응답합니다.

API를 호출하기 위해 API 키를 생성해야 하는 경우 API 키 만들기를 참조하세요.

Method does not exist

Method does not exist 응답은 지정된 URL 경로에서 GET, POST 등의 HTTP 메서드를 찾을 수 없다는 의미입니다. 문제해결을 위해서는 배포한 서비스 구성을 비교하여 요청으로 전송 중인 메서드 이름과 URL 경로가 일치하는지 확인합니다.

  1. Google Cloud Console에서 프로젝트의 Endpoints 서비스 페이지로 이동합니다.

    Endpoints 서비스 페이지로 이동

  2. API가 2개 이상인 경우 요청을 전송한 API를 선택합니다.

  3. 배포 기록 탭을 클릭합니다.

  4. 최신 배포를 선택해서 서비스 구성을 확인합니다.

OpenAPI 문서의 paths 섹션에서 지정하여 호출한 메서드가 표시되지 않으면 메서드를 추가하거나 파일의 최상위 수준에 x-google-allow 플래그를 추가합니다.

x-google-allow: all

이 플래그는 OpenAPI 문서의 백엔드에서 지원되는 모든 메소드를 나열할 필요가 없음을 나타냅니다. all을 사용하면 API 키 또는 사용자 인증 유무에 관계없이 모든 호출이 ESP를 통해 API로 전달됩니다. 자세한 내용은 x-google-allow을 참조하세요.

App Engine 가변형 환경 관련 오류

이 섹션에서는 App Engine 가변형 환경에 배포된 API의 오류 응답에 대해 설명합니다.

오류 코드 502 또는 503

App Engine이 요청에 성공적으로 응답하는 데 몇 분 정도 걸릴 수 있습니다. 요청을 보내고 HTTP 502, 503, 기타 서버 오류가 수신된 경우에는 1분 정도 기다린 후 다시 요청을 시도하세요.

오류 메시지 BAD_GATEWAY

메시지에 BAD_GATEWAY가 포함된 오류 코드 502는 일반적으로 메모리 부족으로 인해 App Engine에서 애플리케이션이 종료되었음을 나타냅니다. 기본 App Engine 가변형 VM에는 메모리가 1GB만 포함되며, 애플리케이션 컨테이너를 위해 600MB만 사용할 수 있습니다.

오류 코드 502 문제를 해결하는 방법은 다음과 같습니다.

  1. Google Cloud Console에서 Logging 페이지로 이동합니다.

    로그 탐색기 페이지로 이동

  2. 페이지 상단에서 해당 Google Cloud 프로젝트를 선택합니다.

  3. Google App Engine 애플리케이션을 선택하고 vm.syslog를 엽니다.

  4. 다음과 같은 로그 항목을 찾습니다.

    kernel: [  133.706951] Out of memory: Kill process 4490 (java) score 878 or sacrifice child
kernel: [  133.714468] Killed process 4306 (java) total-vm:5332376kB, anon-rss:2712108kB, file-rss:0kB

    로그에 Out of memory 항목이 표시되면 다음 안내를 따르세요.

    1. 기본 VM 크기를 늘리려면 app.yaml 파일에 다음을 추가합니다.

      resources:
  memory_gb: 4

    2. API를 다시 배포합니다.

      gcloud app deploy

app.yaml 파일의 endpoints_api_service 섹션에 rollout_strategy: managed 옵션이 지정된 경우 다음 명령어를 사용하여 API를 재배포합니다.

  gcloud app deploy

자세한 내용은 API 및 ESP 배포를 참조하세요.

Cloud Logging 로그 확인

응답 오류 문제해결을 돕기 위해 Cloud Logging 로그를 사용하려면 다음 안내를 따르세요.

  1. Google Cloud Console에서 Logging 페이지로 이동합니다.

    로그 탐색기 페이지로 이동

  2. 페이지 상단에서 Google Cloud 프로젝트를 선택합니다.

  3. 왼쪽의 드롭다운 메뉴를 사용하여 생성된 API > [YOUR_SERVICE_NAME]을 선택합니다.

  4. 응답 오류가 표시되는 행이 보일 때까지 시간 범위를 조정합니다.

  5. JSON 페이로드를 확장하고 error_cause를 찾습니다.

    • error_cause가 application으로 설정된 경우 코드에서의 문제를 나타냅니다.

    • error cause가 다르고 문제를 해결할 수 없으면 로그를 내보내고 Google에 문의할 때 해당 로그를 보냅니다.

자세한 내용은 다음을 참조하세요.

  • 로그 탐색기에 표시되는 로그 구조에 대한 자세한 내용은 Endpoints 로그 참조를 참조하세요.

  • 로그 탐색기 사용 시작하기

  • 지연 시간이 300밀리초 이상인 모든 요청 가져오기 등 고급 필터링을 위해 고급 로그 쿼리를 사용합니다.

Invoke-WebRequest 예와 관련된 문제

일부 버전의 Windows PowerShell에서는 가이드의 Invoke-WebRequest 예시가 실패합니다. 또한 응답에 문자로 변환해야 하는 부호 없는 바이트 목록이 포함되어 있음이 보고되었습니다. Invoke-WebRequest 예시가 예상된 결과를 반환하지 않으면 다른 애플리케이션을 사용하여 요청을 전송해 보세요. 다음은 이와 관련된 몇 가지 권장사항입니다.

  • Cloud Shell을 시작하고 사용 중인 가이드의 Linux 단계에 따라 요청을 전송합니다.

  • Chrome 브라우저 확장 프로그램 Postman(www.getpostman.com에서 제공됨)과 같은 타사 애플리케이션을 설치합니다. Postman에서 요청을 만들려면 다음 단계를 따릅니다.

    • HTTP 동사로 POST를 선택합니다.
    • 헤더에 키 content-type 및 값 application/json을 선택합니다.
    • 본문에 {"message":"hello world"}를 입력합니다.

    • URL에 환경 변수가 아닌 실제 API 키를 사용합니다. 예를 들면 다음과 같습니다.

      • App Engine 가변형 환경: https://example-project-12345.appspot.com/echo?key=AIza...
      • 다른 백엔드: http://192.0.2.0:80/echo?key=AIza...

  • 명령어 프롬프트에서 실행되는 curl을 다운로드하여 설치합니다. Windows에서는 작은따옴표 안에 중첩된 큰따옴표가 처리되지 않으므로 예시의 --data 옵션을 다음과 같이 변경해야 합니다.

    --data "{\"message\":\"hello world\"}"