API Gateway HTTP 간접 호출 오류 문제를 해결하려면 어떻게 해야 합니까?

해결 방법

리소스 및 작업 요청을 기록하도록 구성한 REST API에 대한 5xx 오류를 해결하려면 AWSSupport-TroubleshootAPIGatewayHttpErrors 런북을 사용하십시오.

또는 5xx 오류 문제를 수동으로 해결할 수 있습니다.

참고: AWS Command Line Interface(AWS CLI) 명령을 실행할 때 오류가 발생하면 AWS CLI의 오류 해결을 참조하십시오. 또한 최신 AWS CLI 버전을 사용하고 있는지 확인하십시오.

자동 런북을 사용하여 오류 문제 해결

AWSSupport-TroubleshootAPIGatewayHttpErrors 런북은 Amazon CloudWatch Logs를 분석하기 전에 API, 리소스, 작업 및 스테이지를 검증합니다.

필요한 권한 부여

런북을 실행하기 전에 AWS Identity and Access Management(IAM) 사용자 또는 역할에 올바른 권한이 있는지 확인하십시오. IAM 사용자 또는 역할에 런북에 액세스할 수 있는 권한이 있는지 확인하십시오.

또한 자동화를 실행하는 IAM 사용자 또는 수임된 서비스 역할에는 다음 권한이 있어야 합니다.

• apigateway:GET
• logs:GetQueryResults
• logs:StartQuery
• ssm:DescribeAutomationExecutions
• ssm:GetAutomationExecution
• ssm:DescribeAutomationStepExecutions
• ssm:StartAutomationExecution
• ssm:DescribeDocument
• ssm:GetDocument
• ssm:ListDocuments

자동화 실행

다음 단계를 완료하십시오.

1. AWSSupport-TroubleshootAPIGatewayHttpErrors 런북을 엽니다.
2. Execute automation(자동화 실행)을 선택합니다.
   입력 파라미터에 다음을 입력합니다.
   RestApiId: 문제 해결 중인 API의 API ID입니다.
   StageName: 배포된 스테이지의 이름입니다.
   ResourcePath: 작업의 리소스 경로입니다.
   HttpMethod: 구성된 리소스 경로의 메서드입니다.
   StartTime: CloudWatch 로그를 쿼리할 시작 날짜 및 시간입니다. 형식은 yyyy-MM-ddTHH:mm:ss여야 하며 시간대는 UTC여야 합니다.
   EndTime: CloudWatch 로그의 쿼리를 중지할 종료 날짜 및 시간입니다. 형식은 yyyy-MM-ddTHH:mm:ss여야 하며 시간대는 UTC여야 합니다.
   AccessLogs: 런북에서 분석하려는 액세스 로그입니다.
   ExecutionId: 오류가 발생한 요청의 실행 ID입니다.
   AutomationAssumeRole: 자동화가 사용자를 대신하여 작업을 수행할 수 있도록 하는 IAM 역할의 ARN입니다. 역할을 지정하지 않으면 Automation에서는 런북을 시작하는 사용자의 권한을 사용합니다.
   StageName: 배포된 스테이지의 이름입니다.
3. Execute(실행)를 선택합니다.
4. Outputs(출력) 섹션에서 자세한 결과를 검토합니다.
   참고: 런북에서 로그를 찾지 못하는 경우에도 자동화가 성공적으로 완료됩니다.

5xx 상태 코드 오류 문제 수동 해결

참고: 다음 해결 방법은 REST API에만 적용됩니다.

시작하기 전에 API Gateway 오류 문제를 해결하기 위해 Amazon CloudWatch Logs를 활성화하십시오. 실행 로그에서 5xx 오류를 찾으려면 CloudWatch 로그에서 API Gateway REST API 오류를 찾으려면 어떻게 해야 합니까?를 참조하십시오. API Gateway 5XXError 지표는 지정된 기간 동안의 서버 측 오류 수를 캡처합니다.

Lambda 함수 코드의 오류

AWS Lambda와 통합되는 API 엔드포인트 500 오류에 대해서는 Amazon API Gateway 및 AWS Lambda의 오류 처리 패턴을 참조하십시오.

스테이지 변수에 대한 권한 누락

스테이지 변수를 사용하여 Lambda 함수를 간접 호출하도록 API Gateway를 설정하는 경우, 내부 서버 오류가 발생할 수 있습니다. 이 문제를 해결하려면 스테이지 변수를 사용하여 API Gateway에서 Lambda 통합을 정의했습니다. API 메서드를 간접 호출할 때 “내부 서버 오류”와 500 상태 코드가 나타나는 이유는 무엇입니까?를 참조하십시오.

잘못되거나 누락된 HTTP 상태 코드 매핑

이 문제를 해결하려면 API Gateway에서 모의 통합을 설정합니다.

스로틀링 문제

많은 수의 요청이 백엔드 서비스를 제한하는 경우 API Gateway API가 내부 서버 오류를 반환할 수 있습니다. 이 문제를 해결하려면 지수 백오프 및 재시도 메커니즘을 활성화한 다음, 요청을 다시 시도합니다. 여전히 문제가 발생하면 API Gateway 할당량을 확인하십시오. 서비스 할당량을 초과하면 서비스 할당량 증가를 요청할 수 있습니다.

POST의 정의되지 않은 HTTP 메서드

Lambda 통합의 경우 통합 요청에 POST의 HTTP 메서드를 사용해야 합니다. 다음 put-integration AWS CLI 명령을 실행하여 메서드 통합 요청을 업데이트합니다.

aws apigateway put-integration \
    --rest-api-id id \
   --resource-id id \
    --http-method ANY \
    --type AWS_PROXY \
    --integration-http-method POST \
    --uri arn:aws:apigateway:us-east-2:lambda:path//2015-03-31/functions/arn:aws:lambda:us-east-2:account_id:function:helloworld/invocations

참고: rest-api-id를 본인의 REST API ID로, resource-id를 리소스 ID로, 예제 URI를 URI로 바꾸십시오.

그 후, 다음 create-deployment AWS CLI 명령을 실행하여 REST API를 배포하십시오.

aws apigateway create-deployment \
    --rest-api-id id \
    --stage-name stage-resource

참고: rest-api-id를 본인의 REST API ID로, stage-resource를 배포 리소스가 생성할 스테이지 리소스로 바꾸십시오.

Lambda 사용 권한

Lambda 함수 또는 Lambda 권한 부여자의 리소스 기반 정책에 API에 대한 함수 간접 호출 권한이 포함되어 있는지 확인하십시오.

Lambda 함수 출력 JSON 형식 문제

통합된 Lambda 함수의 출력이 REST API에 대해 지정된 JSON 형식을 준수하지 않는 경우 오류가 발생합니다. 프록시 통합을 위한 Lambda 함수 및 Lambda 권한 부여자의 출력에 올바른 JSON 형식을 사용해야 합니다. 다음 예제 JSON 형식을 사용하십시오.

프록시 통합을 위한 Lambda 함수의 예:

{
    "isBase64Encoded": true|false,
    "statusCode": httpStatusCode,
    "headers": { "headerName": "headerValue", ... },
    "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... },
    "body": "..."
}

Lambda 권한 부여자의 예:

{
   "principalId": "user",
  "policyDocument": {
    "Version": "2012-10-17",
    "Statement": [
      { "Action": "execute-api:Invoke",
        "Effect": "Deny",
        "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/"
      }
    ]
  }
}

10MB를 초과하는 백엔드 페이로드 크기

백엔드 페이로드 크기에 대한 최대 HTTP API 할당량은 10MB입니다. 크기를 늘릴 수 없으므로 백엔드 페이로드 크기가 10MB 할당량을 초과하지 않아야 합니다.

프라이빗 엔드포인트 통합

프라이빗 API 엔드포인트를 사용하는 경우 API Gateway 프라이빗 통합도 구성해야 합니다.

내부 서비스 장애

AWS에 내부 서비스 문제가 발생하면 500 오류가 발생할 수 있습니다. AWS 또는 API Gateway 서비스 내에서 문제가 해결될 때까지 기다린 다음, 지수 백오프를 사용하여 요청을 다시 시도합니다.

502 상태 코드 오류: Bad gateway

API Gateway에서 응답을 게이트웨이 또는 프록시로 처리할 수 없는 경우 502 상태 코드 Bad gateway를 받게 됩니다. 이 문제를 해결하려면 Lambda 프록시 통합으로 API Gateway REST API의 HTTP 502 오류를 해결하려면 어떻게 해야 합니까?를 참조하십시오.

참고: API Gateway는 백엔드 서비스 응답을 읽을 때 매핑 템플릿을 사용하여 통합 응답 섹션의 형식을 매핑합니다. 자세한 내용은 API Gateway에서 통합 응답 설정을참조하십시오.

503 상태 코드 오류: Service unavailable

503 상태 코드 오류는 백엔드 통합을 사용할 수 없어 API Gateway API가 응답을 받지 못하기 때문에 발생합니다.

이 오류는 다음과 같은 이유로 발생할 수 있습니다.

• 백엔드 서버가 용량을 초과하여 새 클라이언트 요청을 처리할 수 없습니다.
• 백엔드 서버에서 임시 유지 보수를 완료하고 있습니다.

이 문제를 해결하려면 백엔드 서버에 리소스를 더 추가하고 클라이언트에서 지수 백오프 및 재시도 메커니즘을 활성화할 수 있습니다. 그 후 요청을 다시 시도합니다.

504 상태 코드 오류: Endpoint request timed out

통합 요청이 API Gateway REST API의 최대 통합 시간 제한 파라미터보다 오래 걸리면 API Gateway가 HTTP 504 상태 코드를 반환합니다. 이 문제를 해결하려면 API Gateway의 API HTTP 504 제한 시간 오류를 해결하려면 어떻게 해야 합니까?를 참조하십시오.

관련 정보

AWS Support Automation Workflow(SAW)

Amazon API Gateway의 보안 모범 사례

Amazon CloudWatch 지표를 사용한 REST API 실행 모니터링

API Gateway REST API 또는 WebSocket API의 문제 해결을 위해 CloudWatch Logs를 활성화하려면 어떻게 해야 합니까?