문제 해결 개요

이 페이지에서는 API 게이트웨이의 일반적인 문제 해결 정보를 제공합니다.

'gcloud api-gateway' 명령어를 실행할 수 없음

gcloud api-gateway ... 명령어를 실행하려면 Google Cloud CLI를 업데이트하고 필요한 Google 서비스를 사용 설정해야 합니다. 자세한 내용은 개발 환경 구성을 참조하세요.

'gcloud api-gateway api-configs create' 명령어로 서비스 계정 없음이 표시됨

gcloud api-gateway api-configs create ... 명령어를 실행할 때 다음 형식의 오류가 표시될 수 있습니다.

ERROR: (gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION:
Service Account "projects/-/serviceAccounts/service_account_email" does not exist

그러면 사용할 서비스 계정의 이메일 주소를 명시적으로 지정하는 --backend-auth-service-account 옵션을 사용해서 다음과 같이 명령어를 다시 실행합니다.

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

개발 환경 구성에 설명된 대로 서비스 계정에 필요한 권한이 할당되었는지 확인합니다.

API 요청으로 HTTP 403 오류가 반환됨

배포된 API에 대한 요청으로 API 클라이언트에 HTTP 403 오류가 반환되면 요청된 URL이 올바르지만 다른 이유로 인해 액세스가 금지된 것입니다.

배포된 API에는 API 구성을 만들 때 사용한 서비스 계정에 부여된 역할이 연결된 권한이 포함됩니다. 일반적으로 HTTP 403 오류는 서비스 계정에 백엔드 서비스에 액세스하는 데 필요한 권한이 없을 때 발생합니다.

API와 백엔드 서비스를 동일한 Google Cloud 프로젝트에 정의한 경우 서비스 계정에 Editor 역할이 할당되었는지 또는 백엔드 서비스에 액세스하는 데 필요한 역할이 할당되었는지 확인합니다. 예를 들어 백엔드 서비스가 Cloud Functions를 사용해서 구현된 경우 서비스 계정에 Cloud Function Invoker 역할이 할당되었는지 확인합니다.

API 요청으로 HTTP 401 또는 500 오류가 반환됨

배포된 API에 대한 요청으로 API 클라이언트에 HTTP 401 또는 500 오류가 반환되면 백엔드 서비스 호출을 위해 API 구성을 만들 때 사용한 서비스 계정의 문제 때문일 수 있습니다.

배포된 API에는 API 구성을 만들 때 사용한 서비스 계정에 부여된 역할이 연결된 권한이 포함됩니다. 서비스 계정에서 둘 다 존재하고 API가 배포될 때 API 게이트웨이서 사용될 수 있는지 확인합니다.

게이트웨이를 배포한 후 서비스 계정을 삭제하거나 사용 중지하면 다음과 같은 일련의 이벤트가 발생할 수 있습니다.

서비스 계정이 삭제되거나 사용 중지되면 즉시 게이트웨이 로그에 401 HTTP 응답이 표시될 수 있습니다. response_code_details 필드가 로그 항목의 jsonPayload에서 "via_upstream"으로 설정된 경우에는 서비스 계정 삭제 또는 사용 중지가 이 오류의 원인입니다.
API 게이트웨이 로그에 해당 로그 항목 없이 HTTP 500 오류가 표시될 수도 있습니다. 서비스 계정이 삭제되거나 사용 중지된 후 즉시 게이트웨이에 대해 요청이 없으면 HTTP 401 응답이 표시되지 않을 수 있습니다. 하지만 해당 API 게이트웨이 로그 없이 HTTP 500 오류가 발생하면 게이트웨이 서비스 계정이 더 이상 활성 상태가 아닐 수 있음을 나타냅니다.

지연 시간이 높은 API 요청

Cloud Run 및 Cloud Functions와 같은 API 게이트웨이에는 "콜드 스타트" 지연 시간이 적용됩니다. 게이트웨이가 15~20분 동안 트래픽을 수신하지 않으면 콜드 스타트 중 처음 10`15초 이내에 게이트웨이에 수행된 요청에 3~5초의 지연 시간이 발생합니다.

초기 "워밍업" 기간 이후에도 문제가 지속되면 API 구성에 지정한 백엔드 서비스의 요청 로그를 확인하세요. 예를 들어 백엔드 서비스가 Cloud Functions를 사용해서 구현된 경우 연결된 Cloud Function 요청 로그의 Cloud Logging 항목을 확인합니다.

로그 정보를 볼 수 없음

API가 올바르게 응답하지만 로그에 데이터가 없으면 API 게이트웨이에 필요한 Google 서비스가 모두 사용 설정되지 않았기 때문일 수 있습니다.

API 게이트웨이를 사용하려면 다음 Google 서비스를 사용 설정해야 합니다.

이름	제목
`apigateway.googleapis.com`	API 게이트웨이 API
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

필수 서비스가 사용 설정되어 있는지 확인하려면 다음을 사용하세요.

gcloud services list

필수 서비스가 나열되지 않으면 서비스를 사용 설정하세요.

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

gcloud 서비스에 대한 자세한 내용은 gcloud 서비스를 참조하세요.