Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

문제해결 개요

이 페이지에서는 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 \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

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

API 오류 응답의 소스 확인

배포된 API에 대한 요청으로 오류 (HTTP 상태 코드 400~599)가 발생하면 응답 자체에서 오류가 게이트웨이에서 발생했는지 아니면 백엔드에서 발생했는지 명확하지 않을 수 있습니다. 이를 확인하려면 다음 단계를 따르세요.

로그 탐색기 페이지로 이동하여 프로젝트를 선택합니다.

로그 탐색기로 이동
다음 로그 쿼리를 사용하여 관련 게이트웨이 리소스로 필터링합니다.
```
resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"
```
각 항목의 의미는 다음과 같습니다.
- GATEWAY_ID는 게이트웨이의 이름을 지정합니다.
- GCP_REGION은 배포된 게이트웨이의 Google Cloud 리전입니다.
조사하려는 HTTP 오류 응답과 일치하는 로그 항목을 찾습니다. 예를 들어 httpRequest.status로 필터링합니다.
jsonPayload.responseDetails 필드의 콘텐츠를 검사합니다.

jsonPayload.responseDetails 필드의 값이 "via_upstream"이면 오류 응답이 백엔드에서 발생한 것이므로 백엔드를 직접 문제 해결해야 합니다. 다른 값이면 오류 응답이 게이트웨이에서 발생한 것입니다. 추가 문제 해결 팁은 이 문서의 다음 섹션을 참고하세요.

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

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

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

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

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

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

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

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

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

실패한 요청의 백엔드가 다른 Google Cloud API (bigquery.googleapis.com 등)인 경우 게이트웨이 로그에 jsonPayload.responseDetails 필드가 "via_upstream"으로 설정된 401 HTTP 응답이 표시됩니다. 이는 API 게이트웨이가 ID 토큰으로 백엔드를 인증하는 반면 다른 Google Cloud API에는 액세스 토큰이 필요하기 때문입니다.

API 요청으로 할당량이 적용된 메서드에 대해 HTTP 500 오류가 반환됨

다음 오류가 표시되면 게이트웨이에서 요청에 할당량을 할당할 수 없는 것입니다.

HTTP/2 500
{"code":500,"message":"Failed to call Service Control Quota."}

이 오류는 일반적으로 할당량이 구성된 메서드를 호출하지만 API에 더 이상 할당량 측정항목이 없는 경우에 발생합니다. gRPC 게이트웨이에서는 동일한 실패가 gRPC 상태 코드 Internal로 반환됩니다.

게이트웨이 로그에서 원인 확인

로그 탐색기 페이지로 이동하여 프로젝트를 선택합니다.

로그 탐색기로 이동
다음 로그 쿼리를 실행합니다.
```
resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
jsonPayload.responseDetails="service_control_quota_error"
httpRequest.status=500
```
여기서 GATEWAY_ID는 게이트웨이의 이름을 지정합니다.

API 게이트웨이는 모든 할당량 거부에 동일한 responseDetails 값을 사용하므로 쿼리는 상태 코드와 jsonPayload.responseDetails를 모두 필터링합니다. 할당량을 합법적으로 초과한 요청은 httpRequest.status가 429인 동일한 값을 생성합니다.
일치하는 항목의 jsonPayload.apiConfig 및 jsonPayload.apiMethod 필드를 검사합니다. 이러한 필드는 할당량 구성이 잘못된 API 구성과 메서드를 식별합니다.

API 구성에 잘못된 할당량 구성이 있을 수 있는 이유

API 구성에서 할당량 측정항목과 한도를 정의하지만 API Gateway는 이를 전체 API에 적용합니다. API 구성을 만들 때마다 선언하는 측정항목과 한도는 API의 이전 API 구성에서 선언한 측정항목과 한도를 대체 합니다. 가장 최근에 만든 API 구성의 값만 적용됩니다.

반대로 각 메서드에서 사용하는 측정항목은 게이트웨이가 제공하는 API 구성에 정의됩니다. 게이트웨이가 이전 API 구성을 실행하는 경우 자체 구성에 있지만 API에는 없을 수 있는 측정항목에 대해 할당량을 할당하도록 Service Control에 요청합니다. 측정항목이 없으면 할당 호출이 실패하고 게이트웨이가 요청을 거부합니다.

예를 들어 다음 시퀀스에서는 첫 번째 게이트웨이가 중단됩니다.

측정항목 quota-metric-v1을 선언하는 API 구성 config-v1을 만들고 gateway-1에 배포합니다.
측정항목 quota-metric-v2를 선언하는 동일한 API의 API 구성 config-v2를 만들고 gateway-2에 배포합니다.

gateway-2 는 작동하지만 gateway-1의 할당량이 적용된 메서드에 대한 요청은 실패하기 시작합니다. 이는 API에 더 이상 quota-metric-v1이 정의되지 않기 때문입니다.

다음 변경사항은 이전 API 구성으로 여전히 배포된 모든 게이트웨이에 오류를 일으킬 수 있습니다.

측정항목 이름 바꾸기 또는 삭제
할당량 한도가 적용되는 측정항목 변경
메서드별 할당량 비용(x-google-quota(OpenAPI 문서) 또는 quota.metric_rules(gRPC 서비스 구성))에 지정된 측정항목 변경

한도의 값 만 변경해도 오류가 발생하지 않습니다. 하지만 한도는 API 수준에서도 적용되므로 이전 API 구성으로 배포된 게이트웨이를 포함하여 해당 API의 모든 게이트웨이에 새 값이 적용됩니다.

배포된 할당량 구성 비교

게이트웨이와 각 게이트웨이가 제공하는 API 구성을 나열합니다.
```
gcloud api-gateway gateways list \
 --format="table(name.basename(),apiConfig)"
```
영향을 받는 API의 API 구성을 나열합니다. 가장 최근에 만든 API 구성이 먼저 표시됩니다.
```
gcloud api-gateway api-configs list --api=API_ID \
 --format="table(name.basename(),createTime:sort=1:reverse)"
```
첫 번째 항목은 전체 API에 할당량 측정항목과 한도가 적용되는 API 구성입니다. 표시된 대로 --format 플래그로 정렬합니다. 이 명령어는 --sort-by 플래그를 지원하지 않으며 예측 가능한 순서로 API 구성을 반환하지 않습니다.
API 구성이 생성된 API 정의를 표시합니다.
```
gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID \
 --view=FULL --format="value(openapiDocuments[0].document.contents)" \
 | tr '_-' '/+' | base64 --decode
```
tr 명령어가 필요합니다. contents 필드는 base64url로 인코딩되므로 base64 --decode에서 직접 읽을 수 없기 때문입니다.

gRPC API의 경우 할당량 구성은 OpenAPI 문서가 아닌 서비스 구성에 있으므로 openapiDocuments[0].document.contents를 managedServiceConfigs[0].contents로 바꿉니다.
2단계의 목록 상단에 있는 API 구성과 1단계에서 게이트웨이에 여전히 배포된 것으로 표시된 다른 API 구성 각각에 대해 3단계의 명령어를 실행합니다.
결과를 비교합니다. 이전 API 구성이 메서드에 대해 청구하는 모든 측정항목은 가장 최근에 만든 API 구성에도 정의되어야 합니다. 해당 구성에 측정항목이 없으면 이전 API 구성을 제공하는 게이트웨이가 실패합니다.

유효한 할당량 구성 복원

할당량 측정항목과 한도를 감사하여 모든 활성 구성에서 일관성을 유지합니다. 이렇게 하려면 다음 작업 중 하나를 수행합니다.

게이트웨이 업데이트에 설명된 대로 가장 최근에 만든 API 구성을 사용하도록 API의 모든 게이트웨이를 업데이트합니다. 게이트웨이 업데이트
여전히 배포된 API 구성에서 사용하는 모든 측정항목을 선언하는 새 API 구성을 만들고 기존 게이트웨이를 현재 API 구성에 유지합니다.

할당 오류를 방지하려면 API의 API 구성에서 측정항목 이름을 일관되게 유지합니다. 할당량을 변경할 때는 측정항목의 이름이 아닌 한도의 값을 변경합니다.

지연 시간이 높은 API 요청

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

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

로그 정보를 볼 수 없음

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

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

이름	서비스 이름
API Gateway API	`apigateway.googleapis.com`
Service Management API	`servicemanagement.googleapis.com`
Service Control API	`servicecontrol.googleapis.com`

필수 서비스를 사용 설정하려면 다음 안내를 따르세요.

Google Cloud 콘솔

Google Cloud 콘솔에서 API 및 서비스 > API 라이브러리 페이지로 이동합니다.

API 라이브러리로 이동
API 라이브러리 페이지의 검색창에 필요한 API 이름을 입력합니다.
검색 결과에서 API 페이지를 선택합니다.
API 페이지에서 사용 설정 을 클릭합니다.
이전 표에 나열된 각 서비스에 대해 이러한 단계를 반복합니다.

Google Cloud CLI

다음 명령어를 사용하여 서비스를 사용 설정합니다.

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

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