임시 ID 사용

임시 리소스 이름

BatchJobService는 동일한 일괄 작업 내의 후속 작업에서 참조할 수 있는 임시 리소스 이름을 지원합니다. 여기에는 sequence_token를 사용하여 업로드된 여러 순차적 AddBatchJobOperations 요청이 포함됩니다. 이렇게 하면 서버 측 ID가 할당되기 전에 단일 일괄 작업으로 캠페인과 캠페인에 종속된 광고 그룹, 광고, 기준을 만들 수 있습니다. 다음 일반 규칙 및 예시에서 단일 요청은 모든 AddBatchJobOperations 업로드에서 전체 BatchJob를 나타냅니다.

동일한 mutate 요청 또는 일괄 작업 내에서 새로 생성된 리소스를 참조하려면 새 리소스의 resource_name 필드에 음의 정수 ID (예: -1 또는 -2, 0 제외)를 지정합니다. 예를 들어 일괄 요청에서 캠페인을 만들 때 리소스 이름을 customers/CUSTOMER_ID/campaigns/-1로 설정합니다. 동일한 요청 내에서 이후 작업에서 광고 그룹을 만들 때 customers/CUSTOMER_ID/campaigns/-1를 상위 캠페인으로 참조합니다. API는 -1를 생성 시 생성된 실제 캠페인 ID로 자동으로 바꿉니다.

사용 제약 조건

임시 리소스 이름을 사용할 때는 다음 규칙에 유의하세요.

  • 순서가 중요함: 임시 리소스 이름은 정의한 후에만 참조할 수 있습니다. 작업 목록에서 종속 작업 (예: 광고 그룹 만들기)은 상위 리소스를 만드는 작업 (예: 캠페인 만들기) 뒤에 표시되어야 합니다.
  • 단일 요청 또는 일괄 작업 범위: 임시 리소스 이름은 별도의 작업 또는 mutate 요청에서 유지되지 않습니다. 이전 작업 또는 mutate 요청에서 생성된 리소스를 참조하려면 시스템에서 생성된 실제 리소스 이름을 사용합니다.
  • 전역 고유성: 단일 작업 또는 mutate 요청 내에서 각 임시 리소스 이름은 모든 리소스 유형에서 고유한 음의 정수를 사용해야 합니다. 예를 들어 동일한 요청에서 캠페인과 광고 그룹 모두에 -1를 할당할 수 없습니다. 동일한 요청 또는 일괄 작업 내에서 임시 ID를 재사용하면 NewResourceCreationError.DUPLICATE_TEMP_IDS 오류가 반환됩니다.

페이로드 예시

단일 API 요청 또는 일괄 작업에 캠페인, 광고 그룹, 광고를 추가한다고 가정해 보겠습니다. 다음 REST JSON 예시와 같이 GoogleAdsService.Mutate 또는 BatchJobService.AddBatchJobOperations 요청 페이로드에서 mutateOperations 배열을 구조화할 수 있습니다 (간단히 하기 위해 다른 필수 리소스 필드는 생략됨).

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

이 예시에서는 다음과 같은 주요 세부정보를 보여줍니다.

  • -1가 이미 캠페인에 할당되어 있으므로 광고 그룹은 새 임시 ID (-2)를 사용합니다.
  • 광고 그룹은 customers/CUSTOMER_ID/campaigns/-1를 참조하여 이전 작업에서 만든 캠페인에 연결합니다.
  • adGroupAdOperation는 customers/CUSTOMER_ID/adGroups/-2를 참조하고 resourceName를 생략합니다. 요청의 후속 작업이 새 광고를 참조하지 않기 때문입니다.

일괄 작업의 오류 처리

일괄 작업의 표준 작업은 부분 실패가 사용 설정된 상태로 실행되므로(원자적 하위 배치 내 제외) 임시 ID가 있는 상위 리소스의 유효성 검사가 실패하면 해당 임시 ID를 참조하는 모든 종속 하위 작업이 NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS와 함께 실패합니다. 동일한 일괄 작업 내에서 여러 create 작업에 동일한 음수 ID를 재사용하면 NewResourceCreationError.DUPLICATE_TEMP_IDS가 반환됩니다. 임시 ID는 리소스를 만들거나 (create) 새로 만든 상위 리소스를 참조할 때만 유효합니다. 예를 들어 AddBatchJobOperations를 호출할 때 AdGroupCriterionOperation.remove에 음수 임시 ID를 전달하면 RequestError.RESOURCE_NAME_MALFORMED가 반환됩니다.

이전
사용 흐름
다음
등록정보 그룹 필터