Data API 한도 및 할당량

다음 한도 및 할당량은 Data API에 적용됩니다.

할당량 적용 방법

Google 애널리틱스 Data API v1에 대한 모든 요청에는 Google Cloud 프로젝트가 필요하며 이 페이지에 설명된 할당량이 적용됩니다. 할당량은 호출 프로젝트를 식별하는 데 사용되는 메서드와 관계없이 소진됩니다. 여기에는 다음이 포함됩니다.

• OAuth 2.0 사용자 인증 정보로 인증된 요청
• API 키만 사용하여 인증된 요청

API 키는 할당량 및 청구 목적으로 요청을 특정 Google Cloud 프로젝트와 연결하는 데 사용됩니다. 프로젝트의 사용자 인증 정보 또는 API 키를 사용하여 이루어진 모든 API 호출은 프로젝트 및 Google 애널리틱스 속성의 해당 할당량을 기준으로 계산됩니다.

할당량 카테고리

Data API에는 핵심, 실시간, 유입경로, 채팅의 네 가지 요청 할당량 카테고리가 있습니다.

핵심 메서드에 대한 API 요청은 핵심 할당량을 사용합니다. 실시간 메서드에 대한 API 요청은 실시간 할당량을 사용합니다. 유입경로 메서드에 대한 API 요청은 유입경로 할당량을 사용합니다. 채팅 메서드에 대한 API 요청은 채팅 할당량을 사용합니다. 각 요청은 한 종류의 할당량만 사용합니다.

애널리틱스 속성 할당량

모든 요청은 속성 할당량을 사용합니다.

• 동시 요청은 동시에 실행되는 요청 수로 측정됩니다. 요청 동시성을 줄이려면 이전 요청이 완료될 때까지 기다린 후 추가 요청을 보내세요.
• 서버 오류는 500 및 503 코드입니다. 서버 오류 할당량은 요청으로 인해 서버 오류가 발생하는 경우에만 청구됩니다. 프로젝트 및 속성 쌍의 서버 오류 할당량이 소진되면 프로젝트의 속성에 대한 모든 요청이 차단됩니다. 전체 오류 응답 목록은 Error Responses를 참고하세요.
• 각 요청은 시간당 속성별 토큰과 시간당 속성별 프로젝트당 토큰의 할당량을 모두 사용합니다. 즉, '시간당 속성별 프로젝트당 토큰' 할당량이 소진되기 전에 '시간당 속성별 토큰' 할당량이 소진되려면 3개 이상의 프로젝트에서 하나의 속성에 액세스해야 합니다.

속성은 시간당 120개의 잠재적으로 기준점이 적용된 요청을 허용합니다. userAgeBracket, userGender, brandingInterest, audienceId, audienceName 측정기준에는 기준점이 적용될 수 있습니다. 기준점은 보고서를 보는 사용자가 개별 사용자의 인구통계 또는 관심분야를 추론하지 못하도록 적용됩니다.

속성 토큰 할당량

토큰은 Google 애널리틱스 Data API v1에 대한 각 요청과 함께 사용됩니다. 청구되는 토큰 수는 요청의 복잡성에 따라 다릅니다. 대부분의 요청에는 10개 이하의 토큰이 청구되지만 더 복잡한 요청 (예: Ask Advisor chat 쿼리)에는 더 많은 토큰이 사용됩니다.

토큰 소비에 영향을 미치는 요인

요청의 정확한 토큰 비용은 실행 시점에 결정되므로 정확한 사전 계산이 어렵습니다. 비용은 요청 자체와 Google 애널리틱스 속성의 기본 데이터와 관련된 여러 요인의 영향을 받습니다. 이러한 요인으로 인해 비용이 높아질 수 있습니다.

• 행 수: 더 많은 행을 요청합니다.
• 측정기준 및 측정항목 수: 더 많은 측정기준과 측정항목을 포함합니다.
• 필터 복잡성: 복잡한 필터 표현식을 사용합니다.
• 기간 길이: 더 긴 기간에 대해 쿼리합니다.
• 데이터 카디널리티: 카디널리티가 높은 측정기준 (예: pagePath, 맞춤 측정기준과 같이 고유한 값이 많음)은 토큰 비용을 크게 늘릴 수 있습니다.
• 속성 이벤트 볼륨: 이벤트 볼륨이 더 높은 속성에 대한 쿼리는 데이터가 더 적은 속성에 대한 동일한 쿼리보다 더 많은 토큰을 사용할 수 있습니다.

토큰 사용량 모니터링

특정 API 호출의 토큰 비용을 확인하는 가장 효과적인 방법은 요청 본문에 "returnPropertyQuota": true 매개변수를 포함하는 것입니다 (runReport, batchRunReports, runPivotReport, batchRunPivotReports, runRealtimeReport, 및 runFunnelReport에서 지원됨). 그러면 API 응답에 해당 특정 요청에서 사용된 토큰과 남은 할당량 잔액을 자세히 설명하는 PropertyQuota 객체가 포함됩니다.

returnPropertyQuota가 포함된 요청 예

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ],
  "returnPropertyQuota": true
}

propertyQuota 응답 페이로드 예

"returnPropertyQuota": true가 설정되면 응답에 각 필드에 consumed 및 remaining 정수가 포함된 QuotaStatus가 있는 propertyQuota 객체가 포함됩니다.

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    }
  ],
  "propertyQuota": {
    "tokensPerDay": {
      "consumed": 1,
      "remaining": 199999
    },
    "tokensPerHour": {
      "consumed": 1,
      "remaining": 39999
    },
    "concurrentRequests": {
      "consumed": 0,
      "remaining": 10
    },
    "serverErrorsPerProjectPerHour": {
      "consumed": 0,
      "remaining": 10
    },
    "potentiallyThresholdedRequestsPerHour": {
      "consumed": 0,
      "remaining": 120
    },
    "tokensPerProjectPerHour": {
      "consumed": 1,
      "remaining": 13999
    }
  }
}

propertyQuota의 각 필드는 애널리틱스 속성 할당량의 할당량에 해당합니다. 단일 API 요청의 토큰 요금은 tokensPerDay, tokensPerHour, tokensPerProjectPerHour에서 동시에 차감됩니다. 할당량 버킷의 남은 값이 0에 도달하면 해당 속성에 대한 후속 요청은 429 RESOURCE_EXHAUSTED 오류를 반환합니다.

429 RESOURCE_EXHAUSTED 오류를 방지하기 위한 권장사항

• 잔액을 동적으로 모니터링remaining: 응답에서 propertyQuota.tokensPerProjectPerHour.remaining 및 propertyQuota.tokensPerHour.remaining을 검사하고 남은 토큰이 안전 기준점 아래로 떨어지면 긴급하지 않은 백그라운드 작업을 제한하거나 일시중지합니다.
• 관련 검색어 일괄 처리: batchRunReports 또는 batchRunPivotReports 를 사용하여 최대 5개의 보고서를 단일 HTTP 호출로 그룹화하고 HTTP 왕복 오버헤드를 줄입니다 (일괄 처리의 각 보고서는 토큰 및 concurrentRequests 할당량에 대해 개별적으로 계산됨).
• 쿼리 복잡성 및 카디널리티 줄이기: 필요한 측정기준과 측정항목으로만 요청을 제한하고 가능한 경우 dateRanges를 단축하며 자주 폴링하는 쿼리에서 카디널리티가 높은 여러 측정기준 (예: pagePath 또는 fullPageUrl)을 결합하지 않습니다.
• 요청 동시 실행 제어: 요청을 큐에 넣거나 작업자 풀 크기를 제한하여 진행 중인 요청이 concurrentRequests 한도 (스탠더드의 경우 10, 애널리틱스 360의 경우 50) 미만으로 유지되도록 합니다.
• 재시도 한도가 있는 지수 백오프 구현: 요청이 429 RESOURCE_EXHAUSTED, 500 INTERNAL 또는 503 UNAVAILABLE로 실패하면 오류 응답에 설명된 대로 잘린 지수 백오프를 사용하여 다시 시도합니다.

채팅 토큰 소비 및 모니터링

Ask Advisor chat 요청의 경우 토큰은 모델 계산, 추론, 기본 데이터 검색 비용을 나타냅니다. 채팅 토큰 소비는 다음의 영향을 받습니다.

• 쿼리 및 분석 범위: 요청된 분석의 복잡성과 범위입니다.
• 모델 입력 및 출력 토큰: 처리된 컨텍스트 데이터의 양과 생성된 응답 설명입니다.
• 사고 토큰: 결과를 종합하는 데 필요한 모델 추론 단계입니다.
• 실행 지연 시간: 다단계 데이터 탐색에 필요한 처리 시간입니다.

채팅 토큰 사용량을 모니터링하려면 "returnPropertyQuota": true in your ChatRequest를 설정하세요. 응답에는 사용된 잔액과 남은 잔액이 포함된 PropertyChatQuota 및 tokensPerDay 필드가 포함된 tokensPerHour 객체가 포함됩니다.