민하즈 카지, Google 애널리틱스 Developer Advocate – 2023년 2월
Google 애널리틱스 Data API를 사용하여 애플리케이션을 개발하는 경우 API의 할당량 및 한도가 작동하는 방식을 이해해야 합니다. 애플리케이션이 잘 디자인되면 사용자가 할당량 한도에 도달할 가능성이 작습니다. 또한 일부 관련 권장사항을 따르면 API 쿼리의 성능이 향상됩니다. 이에 따라 애플리케이션의 보고서와 대시보드가 빨라지고 더 바람직한 사용자 경험을 제공할 수 있습니다. 이 도움말에서는 할당량 시스템과 Google 애널리틱스 Data API 구현을 위한 권장사항을 설명합니다.
Google 애널리틱스 Data API의 할당량 시스템 이해
수백만 명의 개발자와 사용자가 Google 애널리틱스를 사용하므로 API 요청에 할당량을 설정하면 시스템에서 처리할 수 있는 것보다 더 많은 데이터를 처리하지 않아도 되도록 하면서 시스템 리소스의 균등한 분배를 보장할 수 있습니다. Google 애널리틱스 4 속성용 Data API는 API 할당량을 관리하기 위해 토큰 버킷 시스템을 사용합니다. 개념을 이해하려면 버킷이 최대 토큰 수를 넣을 수 있는 버킷이 있다고 가정해 보세요. 모든 API 요청은 먼저 버킷을 확인합니다. 남은 토큰이 없으면 요청이 실패합니다. 그렇지 않으면 요청이 실행되고 요청의 복잡도에 따라 버킷에서 하나 이상의 토큰을 사용합니다. 토큰은 고정된 시간 간격에 따라 버킷에 최대로 보충됩니다.
사용 중인 Data API 메서드에 따라 세 가지 별도 할당량 카테고리가 있습니다.
- 실시간(
runRealtimeReport) - 유입경로(
runFunnelReport) - 핵심(기타 모든 메서드)
또한 Data API 메서드는 여러 버킷의 할당량 토큰을 확인합니다.
- 일일 속성별
- 시간당 속성별
- 시간당 속성별 프로젝트당
- 속성당 동시 요청
- 시간당 속성별 프로젝트당 서버 오류
이 다섯 개의 버킷은 속성에 대해 Data API 요청이 수신될 때마다 확인됩니다. 버킷 중 하나라도 비어 있으면 요청이 즉시 실패하고 429 오류가 반환됩니다. 비어 있는 버킷이 없으면 속성당 동시 요청 버킷에서 단일 토큰이 사용된 다음 API 요청이 실행됩니다. 요청의 복잡도에 따라 실행이 완료된 후 처음 세 개의 각 버킷에서 일정량의 토큰이 사용됩니다. 이 때 속성당 동시 요청도 토큰을 보충합니다.
시간당 속성별 프로젝트당 토큰이 할당되므로 사용자 한 명 이상의 할당량이 소진되어도 애플리케이션의 다른 사용자에게 영향을 미치지 않습니다. 여기에서 프로젝트는 애플리케이션의 GCP 프로젝트를 의미합니다. 시간당 속성별 할당량은 일반적으로 시간당 속성별 프로젝트당 할당량의 네 배입니다. 따라서 최종 사용자의 경우 네 개 이상의 서로 다른 프로젝트에서 속성에 액세스해야 시간당 속성별 할당량이 소진됩니다. 프로젝트 수준과 속성 수준에서 모두 할당량을 적용하면 할당량 문제가 단일 속성으로 제한되고 애플리케이션에서 액세스하는 다른 속성에 영향을 미치지 않습니다.
서버 오류 할당량은 500 또는 503 코드가 있는 API 응답을 의미합니다. 속성에 액세스하는 동안 애플리케이션에서 너무 많은 오류가 발생하면 시간당 속성별 프로젝트당 서버 오류 할당량이 소진됩니다.
모든 할당량 토큰은 명시된 간격으로 한도까지 보충됩니다. 업데이트된 할당량 정보는 Google 애널리틱스 Data API 할당량을 참고하세요. 예를 들어 핵심 메서드는 시간당 속성별 프로젝트당 버킷에서 할당량 토큰을 1,250개 받습니다. 애플리케이션의 평균 요청이 10개의 할당량 토큰을 사용한다고 가정하면, 애플리케이션에서 표준 속성에 대해 시간당 125개의 핵심 요청을 할 수 있고 애널리틱스 360 속성에 이의 10배(1250개의 핵심 요청)의 요청을 할 수 있습니다. 더 높은 할당량 토큰 한도는 애널리틱스 360 속성의 주요 이점 중 하나입니다.
처음 세 버킷의 토큰 사용량은 요청의 복잡도에 따라 달라지므로 요청 실행 전에 정확한 토큰 사용량을 예측하기는 어렵습니다. 다음과 같은 경우 일반적으로 요청의 복잡성이 증가하므로 토큰 사용량이 증가합니다.
- 추가 측정기준 요청
- 더 넓은 시간 범위 쿼리
- 카디널리티가 높은 측정기준 포함
- 이벤트 수가 더 많은 속성 쿼리
따라서 두 속성에 동일한 쿼리를 사용해도 측정기준의 카디널리티가 다르거나 트래픽의 양이 다를 수 있으므로 하면 토큰 사용량이 완전히 다를 수 있습니다. 하지만 트래픽 수준과 구성이 유사한 속성의 토큰 사용량은 비슷할 것으로 예상됩니다. 이러한 가정을 사용하여 계획 및 애플리케이션 설계 단계에서 고객 토큰 사용량을 예측할 수 있습니다.
할당량 사용량 모니터링
할당량 사용량을 모니터링하고 최종 사용자에게 해당 정보를 전달하려면 API 요청 본문에 "returnPropertyQuota": true를 추가하세요. 이렇게 하면 API 응답과 함께 PropertyQuota 객체가 반환됩니다. PropertyQuota 객체에는 다섯 개 버킷 모두의 사용량과 남은 할당량 상태가 포함됩니다. 다음은 요청 본문과 응답의 예입니다.
요청
{
"dimensions": [
{
"name": "medium"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "yesterday"
}
],
"returnPropertyQuota": true
}
응답
{
"dimensionHeaders": [
{
"name": "medium"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
...
"propertyQuota": {
"tokensPerDay": {
"consumed": 1,
"remaining": 24997
},
"tokensPerHour": {
"consumed": 1,
"remaining": 4997
},
"concurrentRequests": {
"consumed": 0,
"remaining": 10
},
"serverErrorsPerProjectPerHour": {
"consumed": 0,
"remaining": 10
},
"potentiallyThresholdedRequestsPerHour": {
"consumed": 0,
"remaining": 120
},
"tokensPerProjectPerHour": {
"consumed": 1,
"remaining": 1247
}
},
"kind": "analyticsData#runReport",
...
}
따라서 각 Data API 요청 성공 후 요청에서 사용한 할당량과 속성에 대해 남은 할당량을 확인할 수 있습니다. 애플리케이션 인터페이스를 통해 이 정보를 사용자에게 표시할 수도 있습니다.
할당량 관리
Data API를 최대한 활용하려면 아래에 설명된 할당량 관리 권장사항을 구현하는 것이 좋습니다. 또한 속성을 360으로 업그레이드하면 API를 통해 액세스하는 데이터의 양이 증가할 수 있습니다.
권장사항
애플리케이션의 할당량 사용량을 줄이는 데는 크게 두 가지 방법이 있습니다.
- 더 적은 수의 API 요청 전송
- 덜 복잡한 API 요청 전송
이 두 가지 원칙을 염두에 두고 다음 권장사항을 구현해 보세요.
- 캐싱: 캐싱 레이어를 구현하면 애플리케이션의 사용성과 할당량 관리에 모두 도움이 됩니다. Google 애널리틱스 자체는 API 요청을 캐시하지만 요청이 반복되면 여전히 할당량 토큰이 발생합니다. API 응답을 캐시하면 반복 요청의 수를 크게 줄일 수 있습니다. 예를 들어 표준 속성의 일중 데이터는 캐시 만료 시간이 4시간 이상일 수 있습니다. Google 애널리틱스의 데이터 업데이트 빈도를 참고하세요.
- 요청 병합: 여러 API 요청을 단일 요청으로 병합해 봅니다. 예를 들어 2일 동안 데이터를 5번 요청할 경우 10일 동안 1번 요청할 때보다 3배의 할당량 토큰을 사용할 수 있습니다. 단일 측정기준별로만 다른 여러 요청은 단일 요청으로 병합하는 것이 좋습니다.
- 요청 간소화: 애플리케이션과 사용자가 요청하는 최소 데이터 양으로 요청을 제한합니다. 행/열이 많거나 복잡한 필터 기준은 할당량 토큰을 더 많이 사용합니다. 기간이 길수록 일반적으로 비용이 더 많이 듭니다(예: 기간을 28일에서 365일로 변경하면 세 배의 할당량 토큰이 사용될 수 있습니다). 가능하면 카디널리티가 낮은 측정기준을 사용할 수도 있습니다(예:
dateHourMinute대신dateHour요청). - 효과적인
limit사용: 반환되는 행 수를 줄이기 위해 API 요청에서limit를 변경해도 사용되는 할당량 토큰의 수에 큰 영향을 미치지 않습니다. 예를 들어 행 10,000개가 한도인 요청 5개는 한도가 50,000개인 요청 1개에 비해 다섯 배의 할당량 토큰을 사용할 수 있습니다. - 올바른 메서드 카테고리 사용: 위에서 언급한 바와 같이 할당량 한도는 세 메서드 카테고리로 분산됩니다. 적절한 사용 사례에 적합한 메서드를 사용하면 다른 카테고리의 할당량을 줄일 수 있습니다. 예를 들어 핵심 메서드의 데이터를 사용하여 애플리케이션에 자체 유입경로를 만드는 대신
runFunnelReport메서드를 사용하여 유입경로를 만들 수 있습니다. - 기본 설정 업데이트: 사용자가 플랫폼에서 보고서를 작성하거나 맞춤설정할 때 애플리케이션에 표시된 기본 옵션을 업데이트하지 않고 런타임 시에만 변경할 수도 있습니다. 애플리케이션의 기본 기간은 365일이고 사용자는 일반적으로 28일 보고서를 확인하는 경우 정기적으로 필요한 것보다 더 많은 할당량이 사용됩니다. 기본 설정에서 범위와 선택 항목을 제한하고 사용자가 사용 사례에 가장 적합한 설정을 선택하도록 해 보세요. 또는 경우에 따라 사용자가 변경할 수 있는 기본값을 제한할 수도 있습니다.
- 큐에 요청 저장 및 지연 로드: 속성당 동시 요청 토큰 한도에 유의하세요. 애플리케이션에서 동시에 너무 많은 요청을 전송하면 안 됩니다. 애플리케이션에 UI 요소가 많아 API 요청이 상당히 많으면 UI를 페이지로 나누고 지연 로드를 사용하고 재시도를 위해 지수 백오프로 요청을 큐에 추가해 보세요.
returnPropertyQuota메서드를 사용하여 애플리케이션의 속성당 동시 요청 토큰 사용을 적극적으로 모니터링합니다.
사용자 경험 및 기대치 관리
- 토큰을 많이 사용할 가능성이 있는 쿼리를 실행하기 전에 사용자에게 의견을 제공합니다. 예를 들어 카디널리티가 높은 측정기준이 여러 개이거나 기간이 긴 쿼리는 많은 수의 토큰을 사용할 수 있습니다. 이러한 쿼리에 대한 경고와 확인 메시지를 제공하면 사용자가 보고서를 불필요하게 변경하지 못하도록 하고 쿼리 범위를 제한할 수 있습니다.
- 맞춤설정된 보고 솔루션의 경우 사용자가 보고서에 있는 각 요소의 쿼리 사용량을 파악할 수 있는 방법을 제공합니다. 예를 들어 각 보고서 요소의 할당량 토큰 사용량이 나열된 디버그 보기를 제공할 수 있습니다.
- 특정 유형의 할당량 오류에 관한 의견을 제공하고 사용자 액션을 규정합니다.
- Google 애널리틱스 360 속성의 할당량 한도가 표준 속성에 비해 5~10배 높으므로 Google 애널리틱스 360 속성을 더 유연하게 사용할 수 있습니다.
Google 애널리틱스 4용 Data API에서는 API 할당량을 기본 한도 이상으로 늘릴 수 없습니다. Google 애널리틱스 360은 Google 애널리틱스 4 속성보다 높은 할당량을 제공합니다. 사용자가 권장사항을 구현한 후에도 할당량 한도에 도달하는 경우 속성을 360으로 업그레이드하는 것을 고려해야 합니다. 사용자를 위한 또 다른 옵션은 Google 애널리틱스 BigQuery Export를 사용하는 것입니다. 이렇게 하면 사용자가 이벤트 수준 데이터를 BigQuery로 내보내고 자체 분석을 실행할 수 있습니다.
Data API 할당량과 관련하여 추가 질문이 있으면 GA Discord로 이동하거나 Stack Overflow에 문의하세요. Data API와 관련하여 구체적인 기능 요청이 있는 경우 Issue Tracker에 게시할 수 있습니다.