API 한도 및 할당량

Google Ads API는 단일 mutate 요청에서 전송할 수 있는 작업 수와 같은 API 작업에 제한을 적용합니다. 다음 표에는 알아두어야 할 몇 가지 중요한 제한사항과 할당량이 요약되어 있습니다.

요청 유형, 제한사항, 오류 코드
테스트 액세스 수준의 작업 테스트 계정에 대한 일일 API 작업 15,000개 RESOURCE_EXHAUSTED
탐색기 액세스 수준의 작업 프로덕션 계정에 대한 일일 API 작업 2,880개
테스트 계정에 대한 일일 API 작업 15,000개 		RESOURCE_EXHAUSTED
기본 액세스 수준의 작업 테스트 계정 및 프로덕션 계정에 대한 일일 API 작업 15,000개 RESOURCE_EXHAUSTED
일반 액세스 수준의 작업 테스트 계정 및 프로덕션 계정에 대한 무제한 일일 API 작업 해당 사항 없음
mutate 요청 요청당 변경 작업 10,000개 TOO_MANY_MUTATE_OPERATIONS
계획 서비스 요청 1 QPS RESOURCE_EXHAUSTED
전환 업로드 서비스 요청 요청당 전환 2,000개 TOO_MANY_CONVERSIONS_IN_REQUEST
결제 및 계정 예산 서비스 요청 mutate 요청당 작업 1개 TOO_MANY_MUTATE_OPERATIONS

일일 API 작업 한도

일일 API 사용량 한도는 Google Cloud 프로젝트에서 수행한 API 작업 수를 기준으로 합니다. API 작업은 Search 및 SearchStream 요청, 개별 변경 작업, 기타 서비스 요청의 총합입니다. 일일 API 작업 한도는 Google Cloud 프로젝트의 API 액세스 수준에 따라 다릅니다. 액세스 수준 및 허용되는 사용 가이드에는 각 액세스 수준의 구체적인 API 작업 한도가 나와 있습니다.

이러한 한도를 위반하는 요청은 오류와 함께 거부됩니다. RESOURCE_EXHAUSTED.

gRPC 제한사항

모든 Google Ads API 클라이언트 라이브러리는 gRPC를 사용하여 요청과 응답을 생성합니다. 기본적으로 gRPC의 메시지 크기는 4MB이지만 클라이언트 라이브러리는 효율성을 높이기 위해 최대 메시지 크기를 64MB 로 설정합니다.

응답은 이 한도를 초과해서는 안 됩니다. 예를 들어 많은 필드가 포함된 검색 요청은 크기가 64MB를 초과하는 응답을 생성할 수 있습니다. 이 한도를 피하려면 선택한 필드 수를 줄이거나 스트리밍을 사용하면 됩니다. 변경의 경우 요청당 작업 수를 줄여서 보내세요.

이 제한사항을 위반하는 요청은 않고 GoogleAdsError를 생성하지 RESOURCE_EXHAUSTED (gRPC 코드 8 / HTTP 429) 오류를 생성합니다. gRPC 오류 코드 및 메시지 목록을 참고하세요. .

mutate 요청

변경 요청은 사용자의 일일 작업 할당량에 포함되는 것 외에도 요청당 변경 작업이 10,000 개를 초과할 수 없습니다. 이 제한사항을 위반하는 요청은 오류와 함께 거부됩니다. TOO_MANY_MUTATE_OPERATIONS.

특정 서비스 및 요청 유형에 대한 추가 제한사항과 고려사항은 다음에 설명되어 있습니다.

요청 검색

Search 또는 SearchStream 요청은 사용자의 일일 작업 할당량에 대해 하나의 작업으로 계산됩니다. SearchStream 요청 하나는 일괄 처리 수와 관계없이 하나의 API 작업으로 계산됩니다.

페이지가 나뉜 요청

페이지가 나뉜 요청 (예: 유효한 next_page_token이 포함된 요청)은 사용자의 일일 작업 할당량에 포함되지 않습니다. 하지만 만료되었거나 유효하지 않은 페이지 토큰이 포함된 페이지 나누기 요청은 예외를 생성하고 일일 작업 할당량에 포함됩니다.

페이지 나누기에 관한 자세한 내용은 결과 페이지 나누기를 참고하세요.

기타 요청 유형

Mutate, Search, 또는 SearchStream 요청이 아닌 요청은 사용자의 일일 작업 할당량에 대해 하나의 작업으로 계산됩니다.

이러한 요청의 몇 가지 예는 다음과 같습니다.

API 예외를 반환하는 요청

GoogleAdsFailure로 거부된 요청은 여전히 사용자의 일일 작업 할당량에 포함됩니다.

네트워크 수준의 오류와 같이 실패했지만 GoogleAdsFailure를 반환하지 않는 요청은 요청이 서비스에 도달하지 않으므로 사용자의 일일 작업 할당량에 포함되지 않습니다. 네트워크 연결 실패가 그 예입니다.

키워드 플래너 서비스

비용과 복잡성으로 인해 다음 키워드 계획 서비스 메서드는 다른 유형의 요청과 별도의 제한사항이 적용됩니다.

키워드 계획을 만들 때 이러한 제한사항에 유의하세요.

키워드 계획 객체 최대 개수
KeywordPlan 계정당 10,000
KeywordPlan당 KeywordPlanAdGroup 200
KeywordPlan당 KeywordPlanAdGroupKeyword 10,000
KeywordPlan당 KeywordPlanCampaignKeyword (제외 키워드) 1,000
KeywordPlanCampaign당 KeywordPlan 1

잠재고객 통계 서비스

다음 메서드AudienceInsightsService에는 특정 할당량 제한사항이 적용됩니다.

전환 업로드 서비스

전환 조정 업로드 서비스

전환 가치 규칙

ConversionValueRuleSet에 attachment_type이 CUSTOMER인 계정에 이미 있는 경우 활성화되도록 새 전환 가치 규칙을 해당 세트에 추가해야 합니다. 이러한 전환 가치 규칙 세트가 없는 경우 규칙 세트 만들기에 설명된 대로 전환 가치 규칙 세트를 만들고 전환 가치 규칙을 추가해야 합니다.

결제 및 계정 예산 서비스

  • 변경은 월별 인보이스로 구성된 계정에 대해서만 실행할 수 있습니다.

    이 제한사항을 위반하는 요청은 오류와 함께 거부됩니다. MUTATE_NOT_ALLOWED.

  • 변경 요청에는 1 개의 작업만 허용됩니다.

    이 제한사항을 위반하는 요청은 오류와 함께 거부됩니다. TOO_MANY_MUTATE_OPERATIONS.

  • 동일한 계정에 대한 계정 예산 (AccountBudget 또는 AccountBudgetProposal) 변경사항 간에는 최소 12 시간의 간격을 두어야 합니다. 12시간이 지나기 전에 변경하면 Google Ads 계정 담당자만 해결할 수 있는 복구 불가능한 오류가 발생할 수 있습니다.

고객 계정 초대

신규 사용자는 CustomerUserAccessInvitationService를 사용하여 기존 고객 계정에 초대할 수 있습니다. 이 기능은 다른 사용자에게 초대 이메일을 보내므로 악용될 가능성이 있어 동작에 제한사항이 있습니다.

  • 사용자는 동일한 고객 계정에 대해 대기 중인 초대를 두 개 이상 받을 수 없습니다. 대기 중인 초대가 이미 있는 사용자에게 초대를 보내는 후속 요청이 이루어지면 다음 오류가 반환됩니다. EMAIL_ADDRESS_ALREADY_HAS_PENDING_INVITATION.

  • 고객 계정에는 한 번에 대기 중인 초대가 70 개를 초과할 수 없습니다. 이 값을 초과하는 요청이 전송되면 이 오류 가 반환됩니다. PENDING_INVITATIONS_LIMIT_EXCEEDED.

사용자 데이터

사용자 데이터는 UserDataService 및 OfflineUserDataJobService로 관리됩니다.

각 UserData 객체는 create 또는 remove 작업에서 단일 최종 사용자와 관련이 있습니다. user_identifiers 필드는 단일 UserData 객체 내에서 최대 20개의 식별자로 제한됩니다. 단일 UserData 객체에서 이 한도를 초과하면 OfflineUserDataJobError.TOO_MANY_USER_IDENTIFIERS 또는 UserDataError.TOO_MANY_USER_IDENTIFIERS 오류가 발생합니다.

식별자가 20개를 초과하는 사용자 처리

단일 최종 사용자에게 업로드해야 하는 식별자가 20개를 초과하는 경우 이러한 식별자를 여러 UserData 객체에 분산해야 합니다. Google에서 이러한 모든 식별자를 동일한 최종 사용자와 연결할 수 있도록 하려면 해당 사용자의 각 UserData 객체에 동일한 hashed_email, hashed_phone_number 또는 third_party_user_id와 같은 공통 user_identifier가 하나 이상 포함되어야 합니다. Google은 이러한 공유 식별자를 사용하여 별도의 UserData 작업의 정보를 올바른 최종 사용자 프로필에 연결하고 병합합니다.

해시된 이메일 또는 전화번호와 같은 PII를 사용하는 경우 연결 실패를 방지하기 위해 Google Ads API 요구사항 (SHA-256, 소문자, 공백 없음)에 따라 정규화되고 해시되었는지 확인하세요.

예를 들어 사용자에게 이메일 주소가 30개 있는 경우 공통 third_party_user_id를 공유하는 두 개의 UserData 객체를 보낼 수 있습니다 (첫 번째 객체에 thirdPartyUserId와 이메일 1~19를 넣어 식별자 20개 한도 내에 유지하고 두 번째 객체에 thirdPartyUserId와 이메일 20~30을 넣음).

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_1" },
    // Hashed emails 2 through 18 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_19" }
  ]
}

{
  "userIdentifiers": [
    { "thirdPartyUserId": "user123" },
    { "hashedEmail": "SHA256_OF_EMAIL_20" },
    // Hashed emails 21 through 29 are omitted here.
    { "hashedEmail": "SHA256_OF_EMAIL_30" }
  ]
}

단일 AddOfflineUserDataJobOperationsRequest의 모든 작업에서 user_identifiers의 총 한도는 100,000개입니다 (OfflineUserDataJob은 작업당 권장 최대 1,000,000개의 작업까지 여러 AddOfflineUserDataJobOperationsRequest 호출을 허용할 수 있음). UploadUserDataRequest (UserDataService.UploadUserData)를 사용하는 동기 업로드의 경우 각 요청은 전체 요청에서 최대 10 개의 작업과 100 user_identifiers로 제한됩니다.

기타 유형의 한도

요청에 항목이 너무 많은 작업 목록과 같은 반복되는 입력란은 오류를 발생시킬 수 있습니다. REQUEST_SIZE_LIMIT_EXCEEDED 이 동일한 오류 메시지는 다른 문제로 인해 발생할 수도 있습니다.

이 제한사항이 발생하고 반복되는 입력란을 사용하는 요청을 하는 경우 여러 mutate 요청에 작업 목록을 분할하여 반복되는 입력란의 항목 수를 줄여보세요.

GAQL 쿼리를 실행할 때 절IN 내의 최대 항목 수는 20,000개입니다. 이 한도를 초과하면 FILTER_HAS_TOO_MANY_VALUES 오류가 반환됩니다.

이전
개요
다음
시스템 제한