Compute Engine API 권장사항

이 문서에서는 Compute Engine API를 사용하기 위한 권장사항을 설명합니다. 이 문서는 Compute Engine API에 이미 익숙한 사용자를 대상으로 합니다. 초보자의 경우에는 기본 요건 및 Compute Engine API 사용을 참조하세요.

이러한 권장사항을 따르면 시간을 절약하고 오류를 방지하며 비율 할당량의 영향을 완화할 수 있습니다.

클라이언트 라이브러리 사용

클라이언트 라이브러리는 Compute Engine API에 프로그래매틱 방식으로 액세스하기 위한 권장 방법입니다. 클라이언트 라이브러리에서 제공되는 코드를 사용하면 시간을 절약하고 코드 성능을 향상시킬 수 있도록 일반적인 프로그래밍 언어를 통해 API에 액세스할 수 있습니다.

Compute Engine 클라이언트 라이브러리 및 클라이언트 라이브러리 권장사항에 대해 자세히 알아보세요.

Cloud Console을 사용하여 REST 요청 생성

리소스를 만들려면 Google Cloud Console의 리소스 만들기 페이지 또는 세부정보 페이지를 사용해서 REST 요청을 생성합니다. 생성된 REST 요청을 사용하면 시간이 절약되고 구문 오류를 방지하는 데 도움이 됩니다.

REST 요청 생성 방법을 알아보세요.

작업 완료 대기

작업 즉, 리소스를 변경하는 API 요청이 완료되었거나 성공했다고 가정하지 마세요. 대신 Operation 리소스에 대해 wait 메서드를 사용해서 작업이 완료되었는지 확인합니다. (GET HTTP 동사를 사용하는 읽기 요청과 같이, 리소스를 수정하지 않는 요청은 요청이 성공한 경우 API 응답에 표시되기 때문에 이를 확인할 필요가 없습니다. 따라서 이러한 요청에 대해서는 Compute Engine API가 Operation 리소스를 반환하지 않습니다.)

API 요청이 성공적으로 시작될 때마다 HTTP 200 상태 코드가 반환됩니다. 200이 수신되면 서버에서 API 요청이 성공적으로 수신되었음을 나타내지만, 요청된 작업이 성공적으로 완료되었는지 여부는 이 상태 코드로 표시되지 않습니다. 예를 들어 200이 수신되더라도 작업이 아직 완료되지 않았거나 작업이 실패했을 수 있습니다.

장기 실행 작업에 대한 만들기, 업데이트, 삭제 요청은 해당 요청의 상태를 캡처하는 Operation 리소스를 반환합니다. Operation 리소스의 status 필드가 DONE이면 작업이 완료된 것입니다. 상태를 확인하려면 반환된 Operation 리소스의 범위와 일치하는 wait 메서드를 사용합니다.

wait 메서드는 작업이 완료되었거나 요청이 2분 기한에 가까워졌을 때 반환됩니다. wait 메서드를 사용할 때는 클라이언트가 응답을 기다리지 않고 서버에 계속 요청을 수행하는 짧은 폴링을 방지하세요. Operation 리소스에 대해 단기 폴링을 사용하는 get 메서드 대신 지수 백오프를 사용한 재시도 루프에서 wait 메서드를 사용하여 요청의 상태를 확인하는 것이 비율 할당량을 보존하고 지연 시간을 줄이는 데 도움이 됩니다.

wait 메서드 사용에 대한 상세 설명 및 예시는 API 응답 처리를 참조하세요.

요청된 작업의 상태를 확인하려면 작업 상태 확인을 참조하세요.

이 기간이 지나면 완료된 작업이 데이터베이스에서 삭제될 수 있으므로 작업이 완료될 때까지 기다리는 동안 작업 최소 보관 기간을 고려하세요.

list 작업 결과를 페이지로 나누기

list 메서드(예: *.list 메서드, *.aggregatedList 메서드 또는 목록을 반환하는 다른 메서드)를 사용할 때는 전체 응답을 다 읽을 수 있도록 가급적 결과를 페이지로 나누도록 합니다. 페이지로 나누지 않으면 maxResults 쿼리 매개변수에 따라 첫 500개의 요소까지만 받을 수 있습니다.

Google Cloud의 페이지로 나누기에 대한 상세 설명은 목록 페이지 나누기를 참조하세요. 구체적인 세부정보와 예시는 사용할 list 메서드의 참조 문서를 확인하세요(예: instances.list).

또한 클라우드 클라이언트 라이브러리를 사용하여 페이지 나누기를 처리할 수 있습니다.

클라이언트 측 목록 필터를 사용하여 할당량 오류 방지

*.list 또는 *.aggregatedList 메서드로 필터를 사용하는 경우 요청에서 필터링된 리소스가 10,000개를 초과하면 추가 할당량 요금이 발생합니다. 자세한 내용은 비율 할당량의 filtered_list_cost_overhead를 참조하세요.

프로젝트가 이 비율 할당량을 초과하는 경우 rateLimitExceeded 이유와 함께 403 오류가 수신됩니다. 이 오류를 방지하려면 목록 요청에 클라이언트 측 필터를 사용하세요.

오류 메시지 대신 오류 코드 사용

Google API는 google.rpc.Code로 정의된 표준화 오류 코드를 사용해야 합니다. 오류 메시지는 예고 없이 변경될 수 있습니다. 오류 메시지는 일반적으로 프로그램이 아닌 개발자의 편의를 위해 제공됩니다.

API 오류에 대해 자세히 알아보세요.

클라이언트 측 재시도를 최소화하여 비율 할당량 보존

rateLimitExceeded 오류를 방지하고 비율 할당량의 사용률을 극대화하려면 프로젝트의 클라이언트 측 재시도 횟수를 최소화하세요. 다음과 같은 방법으로 프로젝트의 비율 할당량을 보존할 수 있습니다.

  • 단기 폴링을 피합니다.
  • 버스팅은 부득이한 경우에만 선별적으로 사용합니다.
  • 항상 지수 백오프로 재시도 루프에서 호출합니다.
  • 클라이언트 측 비율 제한을 사용합니다.
  • 애플리케이션을 여러 프로젝트에 분할합니다.

단기 폴링 피하기

클라이언트가 응답을 기다리지 않고 계속해서 서버에 요청을 전송하는 단기 폴링을 피하도록 합니다. 단기 폴링을 수행하면 유용한 데이터를 반환하지 않으면서 할당량에 합산되는 잘못된 요청을 포착하기가 더 어려워집니다.

단기 폴링 대신 작업이 완료될 때까지 대기하도록 하세요.

버스팅은 부득이한 경우에만 선별적으로 사용

버스팅은 부득이한 경우에만 선별적으로 사용합니다. 버스팅은 특정 클라이언트가 짧은 시간 내에 많은 API 요청을 수행하도록 허용하는 조치입니다. 일반적으로 버스팅은 애플리케이션이 평소보다 많은 트래픽을 처리해야 하는 경우와 같이 예외적인 시나리오에 대응하기 위해 수행됩니다. 버스팅은 비율 할당량을 빠르게 소진하므로 필요한 경우에만 사용해야 합니다.

버스팅이 필요한 경우에는 가능한 경우 벌크 인스턴스 API 또는 관리형 인스턴스 그룹과 같은 전용 배치 API를 사용합니다.

요청 일괄 처리에 대해 자세히 알아보세요.

항상 지수 백오프로 재시도 루프에서 호출

지수 백오프를 사용하여 요청이 시간 초과되거나 비율 할당량에 도달할 때마다 요청 간격을 점진적으로 늘리세요.

모든 재시도 루프에는 애플리케이션에 대한 과부하 또는 비율 할당량을 초과하지 않도록 지수 백오프가 있어야 합니다. 그렇지 않으면 동일 프로젝트에 있는 다른 모든 시스템에 부정적인 영향을 줄 수 있습니다.

비율 할당량에 도달하여 실패한 작업에 재시도 루프가 필요한 경우 지수 백오프 전략으로 할당량 버킷을 다시 채울 수 있는 충분한 시간(일반적으로 1분마다)을 허용해야 합니다.

또는 작업 대기에서 제한 시간에 도달하면 재시도 루프가 필요한 경우 지수 백오프 전략의 최대 간격이 작업 최소 보관 기간을 초과할 수 없습니다. 그렇지 않으면 작업 Not Found 오류가 발생할 수 있습니다.

지수 백오프 구현 예시는 Identity and Access Management API에 대한 지수 백오프 알고리즘을 참조하세요.

클라이언트 측 비율 제한 사용

클라이언트 측 비율 제한을 사용합니다. 클라이언트 측 비율 제한은 문제가 되는 클라이언트가 할당량 중 일정 부분만 사용해서 어느 한 클라이언트가 할당량을 모두 사용하지 않도록 방지하는 인공적인 제한을 설정합니다.

애플리케이션을 여러 프로젝트에 분할

애플리케이션을 여러 프로젝트로 분할하면 할당량 버킷의 요청 수를 최소화하는 데 도움이 됩니다. 할당량은 프로젝트 수준별로 적용되므로 각 애플리케이션이 고유한 전용 할당량 버킷을 갖도록 애플리케이션을 분할할 수 있습니다.

체크리스트 요약

다음 체크리스트에서는 Compute Engine API 사용 시 권장사항을 요약해서 보여줍니다.

다음 단계