권장사항 및 제한사항

BatchJobService을 사용할 때는 다음 가이드라인을 고려하세요.

처리량 개선

  • 작업이 많은 것보다 큰 작업이 적은 것이 좋습니다.

  • 업로드된 작업을 작업 유형별로 정렬합니다 (원자적 하위 배치에서 연속으로 그룹화해야 하는 상호 종속 작업 제외). 예를 들어 작업에 표준 캠페인, 광고 그룹, 광고 그룹 기준을 추가하는 작업이 포함된 경우 업로드에서 모든 캠페인 작업이 먼저 오고, 그 뒤에 모든 광고 그룹 작업이 오고, 마지막으로 모든 광고 그룹 기준 작업이 오도록 작업을 정렬합니다.

  • 동일한 유형의 작업 내에서 상위 리소스별로 그룹화하면 성능이 향상될 수 있습니다. 예를 들어 AdGroupCriterionOperation 객체가 여러 개 있는 경우 다양한 광고 그룹의 광고 그룹 기준에 영향을 미치는 작업을 혼합하는 것보다 광고 그룹별로 작업을 그룹화하는 것이 더 효율적입니다.

일괄 분할의 원자성

Google Ads API는 제출된 일괄 작업의 작업을 처리하기 위해 더 작은 하위 일괄 작업으로 분할합니다. 표준 하위 배치는 부분 실패가 사용 설정된 상태로 실행되지만, 상호 종속적인 특정 작업의 하위 배치는 단일 트랜잭션으로 원자적으로 처리됩니다.

AssetGroup 및 실적 최대화 캠페인 Campaign 생성 하위 일괄 처리 (하위 일괄 처리당 총 작업 수 최대 1,000개, 999개를 초과하는 하위 create 작업은 다음 비원자적 하위 일괄 처리로 유출됨)의 경우:

  • 상위 create 작업 (AssetGroup 또는 Campaign의 resource_name)과 연속되는 하위 create 작업 (AssetGroupAsset의 asset_group 또는 CampaignAsset의 campaign)은 동일한 음수 임시 ID를 지정해야 합니다.
  • 새 Asset 리소스의 모든 필수 AssetOperation(create) 작업을 상위 AssetGroupOperation 또는 CampaignOperation(create) 앞에 배치합니다. 상위 create와 하위 링크 create 작업 사이에는 배치하지 마세요. 이렇게 하면 원자적 하위 일괄 처리가 즉시 닫히고 상위 리소스 생성이 연결된 애셋에서 분리됩니다.

원자적 하위 일괄 처리가 실패하면 문제가 있는 작업의 BatchJobResult.status에 기본 검증 오류가 포함되고 해당 하위 일괄 처리의 나머지 작업은 해당 하위 일괄 처리의 해당 트랜잭션 오류로 롤백됩니다. 동일한 AdGroup, AssetGroup 또는 Campaign ID를 공유하는 인접한 BatchJobResult 항목을 검사하여 근본 원인 오류를 식별합니다.

이러한 그룹의 관련 작업이 연속으로 추가되지 않으면 Google Ads API에서 별도의 하위 일괄 처리로 분할하여 수정이 최소 애셋 요구사항을 충족하지 못하거나 등록정보 그룹 트리가 불완전하게 됩니다. 자세한 내용은 일괄 작업에서 등록정보 그룹 필터 사용 및 실적 최대화 캠페인 일괄 처리를 참고하세요.

논리적 그룹화

제품 타겟팅 계층 구조(실적 최대화 캠페인의 경우 AssetGroupListingGroupFilterOperation, 쇼핑 캠페인의 경우 AdGroupCriterionOperation)를 수정하거나 새 AssetGroup 또는 실적 최대화 캠페인 Campaign을 만들 때는 동일한 상위 리소스 (AssetGroup, AdGroup 또는 Campaign)를 타겟팅하는 모든 작업을 연속으로 그룹화합니다. 이렇게 하면 백엔드 잠금 경합이 줄어들고 상호 종속적인 트리가 함께 유지됩니다.

데이터 일관성

등록정보 그룹 필터 트리와 실적 최대화 애셋 요구사항은 각 원자 하위 일괄 트랜잭션이 끝날 때 검증되므로 작업에서 불연속 범위에 걸쳐 동일한 상위 리소스에 대한 업데이트를 분할하거나 동시 작업에 걸쳐 분할하지 마세요.

동시 실행 문제 방지

  • 동일한 계정에 여러 동시 작업을 제출할 때는 작업 크기를 크게 유지하면서 동시에 동일한 객체에서 작업이 실행될 가능성을 줄입니다. 동일한 객체 집합을 변경하려고 하는 RUNNING 상태의 미완료 작업이 많으면 교착 상태와 유사한 조건이 발생하여 심각한 속도 저하와 작업 실패가 발생할 수 있습니다.

  • 결과를 예측할 수 없으므로 동일한 작업에서 동일한 객체를 변경하는 여러 작업을 제출하지 마세요.

결과를 최적으로 검색

  • 작업 상태를 너무 자주 폴링하면 속도 제한 오류가 발생할 수 있습니다.

  • ListBatchJobResults를 호출할 때 page_size를 설정하지 않은 상태로 두거나 (또는 1000 최댓값으로 설정) 페이징 왕복을 최소화하고 애플리케이션이 resource_name를 넘어 반환된 리소스 필드를 검사하는 경우에만 response_content_type을 MUTABLE_RESOURCE로 설정하세요.

  • 결과 순서는 업로드 순서와 동일합니다.

추가 사용 안내

  • 취소되기 전에 일괄 작업이 실행될 수 있는 시간의 상한을 설정할 수 있습니다. 새 일괄 작업을 만들 때 metadata.execution_limit_seconds 필드를 원하는 시간 제한(초)으로 설정합니다. metadata.execution_limit_seconds가 설정되지 않은 경우 기본 시간 제한은 없습니다.

  • 프로토콜 한도는 요청당 10,000개 작업이지만 AddBatchJobOperationsRequest당 1,000개 이하의 작업을 추가하고 sequence_token을 사용하여 나머지 작업을 동일한 작업에 업로드하는 것이 좋습니다. 작업의 크기에 따라 단일 AddBatchJobOperationsRequest에서 너무 많은 작업을 전송하면 BatchJobError.REQUEST_TOO_LARGE 오류가 발생할 수 있습니다. 작업 수를 줄이고 AddBatchJobOperationsRequest를 다시 시도하여 이 오류를 처리할 수 있습니다.

제한사항

  • 각 BatchJob은 최대 100만 개의 작업을 지원합니다. AddBatchJobOperations를 호출할 때 이 한도를 초과하면 ResourceCountLimitExceededError.RESOURCE_LIMIT 오류가 반환됩니다(ErrorDetails.resource_count_details에 ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB 포함).

  • 각 계정에는 동시에 최대 100개의 활성 또는 대기 중인 작업이 있을 수 있습니다. MutateBatchJob로 일괄 작업을 만들 때 이 한도를 초과하면 ResourceCountLimitExceededError.RESOURCE_LIMIT 오류(ErrorDetails.resource_count_details에 ResourceLimitType.BATCH_JOBS_PER_CUSTOMER 포함)가 반환됩니다.

  • 7일이 지난 대기 중인 작업은 자동으로 삭제됩니다.

  • 각 AddBatchJobOperationsRequest에는 요청당 변이 작업이 10,000개로 제한됩니다. 단일 요청에서 10,000개를 초과하는 작업을 수행하면 BatchJobError.REQUEST_TOO_LARGE 오류가 반환됩니다.

  • ListBatchJobResultsRequest의 page_size 필드의 경우:

  • 각 AddBatchJobOperationsRequest의 최대 크기는 41,937,920바이트입니다. 이 한도를 초과하면 BatchJobError.REQUEST_TOO_LARGE 오류가 표시됩니다 (전송 계층에서 거부된 경우 INTERNAL_ERROR). 제출하기 전에 요청의 직렬화된 크기를 확인하고 너무 큰 경우 적절한 조치를 취할 수 있습니다.

    자바

    
static final int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.getSerializedSize();

    C#

    
const int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.CalculateSize();

    PHP

    
const MAX_REQUEST_BYTES = 41937920;

// ... (code to get the AddBatchJobOperationsRequest object)

$size_in_bytes = $request->byteSize();

    Python

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = type(request).pb(request).ByteSize()

    Ruby

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = request.to_proto.bytesize

    Perl

    
use JSON::XS;
use constant MAX_REQUEST_BYTES => 41937920;

# ... (code to get the AddBatchJobOperationsRequest object)

# The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
# conservative upper-bound estimate of the serialized request size.
my $json_encoder = JSON::XS->new->utf8->convert_blessed;
my $size_in_bytes = length($json_encoder->encode($request));

단일 변경 작업 크기

전체 요청은 최대 41,937,920바이트까지 가능하지만 배치 내 단일 MutateOperation의 직렬화된 크기는 10,484,504바이트 (10MiB에서 1,256바이트를 뺀 값)로 제한됩니다. 이 한도를 초과하면 BatchJobError.REQUEST_TOO_LARGE 오류가 반환됩니다. BatchJobError.REQUEST_TOO_LARGE의 참조 문서에는 10,484,504바이트 기준점이 명시되어 있지만, AddBatchJobOperations는 세 가지 요청 기준점 (총 요청 바이트 41,937,920개, 단일 작업 바이트 10,484,504개, 호출당 작업 10,000개) 중 하나를 초과하면 동일한 오류 코드를 반환하며, 오류의 message 필드에는 위반된 한도가 명시됩니다.

이전
등록정보 그룹 필터