항목 읽기 파일에서 이전

항목 읽기 파일 (ERF)은 파트너 캠페인 객체의 JSON 표현으로, 요청 시 매일 생성되며 Google Cloud Storage를 통해 제공됩니다.

ERF는 2021년 6월에 지원 중단되었습니다. 2024년 10월 31일부터 ERF가 공식적으로 지원 종료되고 더 이상 생성되지 않습니다. 기존의 모든 항목 읽기 파일 사용자는 Display & Video 360 리소스를 계속 검색하려면 Display & Video 360 API로 이전하는 것이 좋습니다.

이 가이드에서는 다음과 같은 방법으로 항목 읽기 파일에서 Display & Video 360 API로 이전하는 방법을 설명합니다.

  • 두 인터페이스의 차이점에 대한 개요 제공
  • ERF 테이블과 API 서비스 비교
  • API를 통한 항목 검색에 대한 안내 제공
  • 기존 데이터 격차 확인하기
  • 모든 ERF 필드를 비슷한 API 리소스 필드에 매핑

개요

ERF에서 Display & Video 360 API로 이전할 때는 다음과 같은 몇 가지 주요 차이점을 고려해야 합니다.

  • 데이터 최신성. ERF는 API가 최신 버전의 리소스를 검색하는 동안 매일 대량으로 생성됩니다.
  • 리소스 구조. API는 ERF와 다른 JSON 구조를 사용하여 동일한 리소스 유형을 나타냅니다. 공개 타겟팅 설정과 같은 일부 리소스는 다른 ID 공간을 사용할 수 있습니다.
  • 가져오기 방법. ERF에서 제공하는 원시 JSON 파일과 달리 Display & Video 360 API는 개별적으로, 페이지로 나눈 목록에서 또는 BigQuery 데이터 전송을 통해서만 리소스를 가져올 수 있습니다.
  • 범위. 파트너 ID로 범위가 지정되는 ERF와 달리 대부분의 API 리소스는 광고주 ID로 범위가 지정됩니다. 응답에 포함된 리소스는 해당 범위 내의 리소스로 제한됩니다.

API의 ERF 데이터 표현

항목 읽기 파일은 '공개' 테이블과 '비공개' 테이블로 구분됩니다. 공개 테이블은 타겟팅 값과 같이 모든 사용자에게 사용 가능하고 적용 가능한 정보를 제공합니다. 비공개 테이블은 광고 소재 또는 광고 항목 리소스와 같이 파트너별 데이터를 제공합니다.

Display & Video 360 API는 이러한 이분법을 사용하지 않고 다양한 서비스와 다양한 JSON 구조를 사용하여 모든 정보를 가져올 수 있습니다. 이 섹션에서는 공개 및 비공개 ERF 테이블을 통해 제공되는 정보를 Display & Video 360 API 리소스 및 서비스를 통해 제공되는 정보와 비교합니다.

공개 정보

ERF 공개 테이블은 사용자가 가져온 비공개 리소스의 타겟팅 설정을 해석하고 UI를 통해 업로드된 구조화된 데이터 파일 (SDF) 버전의 하위 집합을 통해 타겟팅을 할당할 때 사용할 수 있는 참조 자료를 제공합니다. 이러한 참조 자료는 모든 사용자에게 동일하며 매핑에 사용되는 숫자 ID와 보다 설명적인 세부정보(예: 표시 이름)로 구성됩니다.

Display & Video 360 API를 사용할 때는 targetingTypes.targetingOptions 서비스를 통해 타겟팅 참조 정보를 가져올 수 있습니다. 공개 테이블과 마찬가지로 이 서비스는 특정 타겟팅 유형의 타겟팅 옵션 ID와 세부정보를 제공합니다. 타겟팅 옵션 ID 검색을 보여주는 코드 예는 기존 타겟팅 설정 페이지를 참고하세요.

공개 테이블 및 SDF

SDF v7 이전에는 항목 읽기 파일과 구조화된 데이터 파일이 타겟팅 설정에 동일한 ID 공간을 사용합니다. SDF를 사용하여 타겟팅 설정을 해석하거나 할당하기 위해 ERF 공개 테이블을 사용하는 SDF 사용자인 경우 Display & Video 360 UI를 통해 이 참조 자료를 CSV 형식으로 다운로드할 수 있습니다.

v7부터 구조화된 데이터 파일 열의 하위 집합에서 사용되는 ID 공간이 ERF에서 SDF를 분리하고 Display & Video 360 API에 더 부합하도록 업데이트되었습니다. 자세한 내용은 v7 이전 가이드 및 참조 문서를 확인하세요.

비공개 리소스

ERF 비공개 테이블은 파트너가 소유한 비공개 리소스의 현재 설정에 대한 일일 스냅샷을 제공합니다. 단일 파트너에서 만들 수 있는 리소스의 엄청난 볼륨으로 인해 이러한 파일은 크기가 매우 커지고 다운로드 및 처리하기가 어려울 수 있습니다.

API에서 각 비공개 테이블에는 해당 리소스 유형의 검색 및 관리를 위한 엔드포인트를 제공하는 해당 서비스가 있습니다. 리소스는 각 서비스의 해당 list 메서드를 사용하여 일괄적으로 검색할 수 있습니다. 각 리소스의 JSON 구조는 API에서 ERF와 비교하여 다르며 다른 필드 이름과 공유 리소스를 사용합니다.

리소스의 할당된 타겟팅 설정 또는 채널의 사이트와 같이 리소스의 ERF 표현에서 사용할 수 있는 특정 정보는 API에서 원래 리소스의 하위 요소로 표시되며 추가 API 요청을 통해 검색해야 합니다.

API에서의 항목 검색

Display & Video 360 리소스는 직접적인 API 요청 또는 BigQuery로 자동 가져오기를 통해 검색할 수 있습니다.

직접 API 요청

각 리소스 유형은 다른 API 서비스를 통해 가져올 수 있습니다. 리소스는 각각 적절한 서비스의 get 또는 list 메서드를 사용하여 개별적으로 또는 일괄적으로 검색할 수 있습니다. Display & Video 360 API 목록 메서드의 중요한 속성은 다음과 같습니다.

  • 필수 범위. 파트너가 범위를 지정하는 ERF와 달리 API의 리소스 대부분은 광고주에 의해 범위가 지정됩니다. 파트너 아래에서 광고 항목과 같은 모든 리소스 유형을 검색하려면 해당 파트너의 각 하위 광고주에 대한 개별 목록 요청이 필요할 수 있습니다. 광고주 및 파트너 소유 채널과 같은 파트너의 직계 하위 요소는 예외입니다.
  • 페이지로 나누기. API 목록 메서드는 페이지 나누기를 사용하여 응답이 합리적인 크기 내에 있도록 보장하고 대부분의 개별 요청 응답 또는 페이지를 리소스 100개로 제한합니다. 관련 리소스 수가 페이지 크기보다 큰 경우 전체 목록 응답의 후속 페이지를 검색하려면 연속된 목록 호출이 필요합니다. 목록 응답을 페이징하는 코드 예는 사용 가능한 타겟팅 옵션 검색에 관한 타겟팅 가이드 페이지의 섹션 에 제공됩니다.
  • 타겟팅 검색을 위해 추가 요청이 필요합니다. 리소스의 타겟팅 설정은 API JSON 객체에 포함되지 않고 할당된 타겟팅 옵션이라고 하는 하위 리소스입니다. 이러한 하위 리소스는 별도의 요청을 통해 검색해야 합니다. 예를 들어 advertisers.lineItems.list 요청을 통해 검색된 각 광고 항목의 경우 모든 타겟팅 정보를 검색하려면 advertisers.lineItems.bulkListAssignedTargetingOptions 요청을 별도로 실행해야 합니다.

리소스 검색 최적화

Display & Video 360 API는 단일 항목 읽기 파일에서 사용할 수 있는 것과 동일한 양의 정보를 검색하기 위해 여러 요청을 요구할 수 있습니다. 리소스 검색 방법을 최적화하면 필요한 데이터를 더 효율적으로 검색할 수 있습니다.

  • API에 동시 요청을 수행합니다. Display & Video 360 API는 프로젝트당 광고주당 요청 비율 제한을 사용하여 인프라를 보호합니다. 이러한 할당량 구조를 사용하면 여러 광고주에 걸쳐 멀티스레드 솔루션을 구현하여 필요한 모든 리소스를 검색하는 데 걸리는 총 시간을 줄일 수 있습니다. 페이지로 나누기를 사용하려면 특정 범위 내에 있는 유형의 모든 리소스를 연속 호출을 통해 가져와야 하지만, 다른 범위 내 또는 다른 유형의 리소스 검색은 동시에 실행할 수 있습니다.
  • 목록 호출에서 필터를 활용하고 매개변수별로 정렬하여 관련 리소스만 가져옵니다. 예를 들어 마지막 날에 업데이트된 광고 항목에만 관심이 있는 경우 advertisers.lineItems.list 메서드의 filter 매개변수를 사용하여 updateTime가 지정된 타임스탬프보다 큰 광고 항목만 반환할 수 있습니다. 이렇게 하면 실행해야 하는 요청 수를 크게 줄일 수 있습니다.
  • 정기적으로 사용되는 ID를 캐시하여 불필요한 API 요청을 방지합니다. 타겟팅 옵션 ID 및 Google 잠재고객 ID와 같은 특정 참조 정보는 비교적 안정적이며, 사용할 때마다 검색할 필요가 없도록 안전하게 저장할 수 있습니다. 하지만 드물게 변경되거나 지원 중단되는 경우를 고려하여 캐시된 값은 매주 확인해야 합니다.

Display & Video 360 API에 효율적으로 액세스하는 방법에 대한 자세한 내용은 할당량 최적화 가이드를 참조하세요.

BigQuery로 가져오기

Display & Video 360 API BigQuery 커넥터를 사용하면 Display & Video 360 리소스 구성을 매일 BigQuery로 직접 자동으로 가져올 수 있습니다. 구성은 Display & Video 360 API 리소스 설계를 사용하여 BigQuery에 저장됩니다. API 리소스의 하위 집합이 지원됩니다.

Display & Video 360 API BigQuery 커넥터 사용에 대한 자세한 내용은 다음 클라우드 문서를 참조하세요.

알려진 API 데이터 격차

ERF에서 Display & Video 360 API로 이전할 때 다음과 같은 중요한 데이터 공백이 발생할 수 있습니다.

  • 스토리 게재 신청서. 스토리 게재 신청서는 API를 통해 가져올 수 없으며 Display & Video 360 UI를 통해 가져와야 합니다.
  • 리소스 필드의 하위 집합입니다. ERF 객체에 있는 일부 리소스 필드는 Display & Video 360 API를 통해 검색된 해당 리소스에서 사용할 수 없습니다.

부록: ERF 필드를 API에 매핑

공개 테이블 매핑

아래 표는 ERF 공개 테이블의 필드를 Display & Video 360 API의 기존 타겟팅 유형 및 타겟팅 옵션 필드에 매핑합니다. 한 필드의 값이 다른 필드에 매핑될 수 있지만, 그렇다고 해서 동일한 데이터 유형, enum 값 또는 ID 공간이 사용된다는 보장은 없습니다.

앱 컬렉션

타겟팅 유형 TARGETING_TYPE_APP_CATEGORY에서 가져올 수 있습니다.

ERF 필드 이름DV360 API 사용 가능 여부
id TargetingOption.targetingOptionId 필드
이름 TargetingOption.appCategoryDetails.displayName 필드

브라우저

타겟팅 유형 TARGETING_TYPE_BROWSER에서 가져올 수 있습니다.

ERF 필드 이름DV360 API 사용 가능 여부
id TargetingOption.targetingOptionId 필드
is_mobile 사용할 수 없음.
이름 TargetingOption.browserDetails.displayName 필드

DataPartner

Display & Video 360 API에서 사용할 수 있는 동등한 리소스 또는 필드는 없습니다.

DeviceCriteria

타겟팅 유형 TARGETING_TYPE_OPERATING_SYSTEM, TARGETING_TYPE_DEVICE_MAKE_MODEL, TARGETING_TYPE_DEVICE_TYPE에서 가져올 수 있습니다.

ERF 필드 이름DV360 API 사용 가능 여부
id TargetingOption.targetingOptionId 필드 또는 DeviceType enum입니다.
is_mobile 사용할 수 없음.
이름 타겟팅 유형에 따라 TargetingOption.operatingSystemDetails.displayName 필드, TargetingOption.deviceMakeModelDetails.displayName 필드 또는 DeviceType enum입니다.
criteria_type TargetingOption.targetingType 필드
operating_system_id 사용할 수 없음.
mobile_brand_name 사용할 수 없음.
mobile_model_name 사용할 수 없음.
mobile_make_model_id 사용할 수 없음.
device_type DeviceType 열거형.

GeoLocation

타겟팅 유형 TARGETING_TYPE_GEO_REGION에서 가져올 수 있습니다.

ERF 필드 이름DV360 API 사용 가능 여부
id TargetingOption.targetingOptionId 필드
canonical_name TargetingOption.geoRegionDetails.displayName 필드
geo_name 사용할 수 없음.
country_code 사용할 수 없음.
region_code 사용할 수 없음.
city_name 사용할 수 없음.
postal_name 사용할 수 없음.
dma_code 사용할 수 없음.

Isp

타겟팅 유형 TARGETING_TYPE_CARRIER_AND_ISP에서 가져올 수 있습니다.

ERF 필드 이름DV360 API 사용 가능 여부
id TargetingOption.targetingOptionId 필드
is_mobile 사용할 수 없음.
이름 TargetingOption.carrierAndIspDetails.displayName 필드
secondary_criteria_id TargetingOption.targetingOptionId 필드

언어

타겟팅 유형 TARGETING_TYPE_LANGUAGE에서 가져올 수 있습니다.

ERF 필드 이름DV360 API 사용 가능 여부
id TargetingOption.targetingOptionId 필드
이름 사용할 수 없음. 언어의 전체 표시 이름은 TargetingOption.languageDetails.displayName 필드에서 확인할 수 있습니다.

SiteToPlacementId

Display & Video 360 API에서 사용할 수 있는 동등한 리소스 또는 필드는 없습니다.

SupportedExchange

타겟팅 유형 TARGETING_TYPE_EXCHANGE에서 가져올 수 있습니다.

ERF 필드 이름DV360 API 사용 가능 여부
id Exchange 열거형.
이름 Exchange 열거형.

UniversalSite

Display & Video 360 API에서 사용할 수 있는 동등한 리소스 또는 필드는 없습니다. 개별 사이트와 앱은 타겟팅 유형 TARGETING_TYPE_URL 및 TARGETING_TYPE_APP 아래에서 직접 타겟팅할 수 있습니다. Display & Video 360에서는 모든 앱 또는 URL을 타겟팅할 수 있지만 모든 앱 또는 URL을 보고할 수는 없습니다. 보고할 수 없는 앱과 URL을 지출에서 삭제하려면 DV360 고객센터의 안내를 따르세요.

비공개 테이블 필드 매핑

아래 표는 ERF 비공개 테이블의 필드를 Display & Video 360 API의 기존 필드 또는 서비스에 매핑합니다. 한 필드의 값이 다른 필드에 매핑될 수 있지만, 이것이 동일한 데이터 유형, enum 값 또는 ID 공간을 활용한다는 보장은 없습니다.

광고주

ERF 필드 이름DV360 API 사용 가능 여부
common_data.id Advertiser.advertiserId 필드
common_data.name Advertiser.displayName 필드
common_data.active Advertiser.entityStatus 필드
common_data.integration_code Advertiser.integrationDetails.integrationCode 필드
partner_id Advertiser.partnerId 필드
currency_code Advertiser.generalConfig.currencyCode 필드
timezone_code Advertiser.generalConfig.timeZone 필드
landing_page_url Advertiser.generalConfig.domainUrl 필드
available_channel_ids advertisers.channels.list 메서드를 통해 가져올 수 있습니다.
blacklist_channel_id 타겟팅 유형 TARGETING_TYPE_CHANNEL 에서 advertisers.targetingTypes.assignedtargetingOptions.list 메서드를 통해 가져올 수 있습니다. AssignedTargetingOption.channelDetails.negative 이 true이면 채널이 제외 타겟팅됩니다.
dcm_configuration 사용할 수 없음.
dcm_network_id Advertiser.adServerConfig.cmHybridConfig.cmAccountId 필드
dcm_advertiser_id Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds 필드에 CM360 플러드라이트 구성을 공유하는 CM360 광고주 ID가 표시됩니다.
dcm_floodlight_group_id Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId 필드
dcm_syncable_site_ids Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds 필드
enable_oba_tags 사용할 수 없음.

Campaign

ERF 필드 이름DV360 API 사용 가능 여부
common_data.id Campaign.campaignId 필드
common_data.name Campaign.displayName 필드
common_data.active Campaign.entityStatus 필드
common_data.integration_code 사용할 수 없음.
advertiser_id Campaign.advertiserId 필드
budget Campaign.campaignFlight 및 Campaign.campaignBudgets 필드.
frequency_cap Campaign.frequencyCap 필드
default_target_list advertisers.campaigns.bulkListCampaignAssignedTargetingOptions 메서드를 통해 가져올 수 있습니다.
uses_video_creatives 사용할 수 없음.
uses_display_creatives 사용할 수 없음.
uses_audio_creatives 사용할 수 없음.
목표 Campaign.campaignGoal.campaignGoalType 필드
측정항목 Campaign.campaignGoal.performanceGoal.performanceGoalType 필드
objective_description Campaign.campaignGoal.performanceGoal.performanceGoalString 필드
metric_amount_micros Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros 필드

광고 소재

ERF 필드 이름DV360 API 사용 가능 여부
common_data.id Creative.creativeId 필드
common_data.name Creative.displayName 필드
common_data.active Creative.entityStatus 필드
common_data.integration_code Creative.integrationCode 필드
advertiser_id Creative.advertiserId 필드
dcm_placement_id Creative.cmPlacementId 필드
width_pixels Creative.dimensions.widthPixels 필드
height_pixels Creative.dimensions.heightPixels 필드
approval_status Creative.reviewStatus 필드
expanding_direction Creative.expandingDirection 필드
creative_type Creative.creativeType 필드

CustomAffinity

ERF 필드 이름DV360 API 사용 가능 여부
id CustomList.customListId 필드
이름 CustomList.displayName 필드
설명 사용할 수 없음.
advertiser_id 사용할 수 없음.

FloodlightActivity

ERF 필드 이름DV360 API 사용 가능 여부
common_data.id FloodlightActivity.floodlightActivityId 필드
common_data.name FloodlightActivity.displayName 필드
common_data.active FloodlightActivity.servingStatus 필드
common_data.integration_code 사용할 수 없음.
advertiser_id FloodlightActivity.advertiserIds 필드에는 지정된 파트너의 플러드라이트 활동에 액세스할 수 있는 모든 광고주가 나열됩니다.
partner_id floodlightGroups.floodlightActivities 서비스에 요청할 때 사용자가 제공합니다.
remarketing_enabled FloodlightActivity.remarketingConfigs 필드에는 지정된 파트너의 플러드라이트 활동에 액세스할 수 있는 각 광고주에 대한 이 구성이 나열됩니다.
ssl_required FloodlightActivity.sslRequired 필드

InsertionOrder

ERF 필드 이름DV360 API 사용 가능 여부
common_data.id InsertionOrder.insertionOrderId 필드
common_data.name InsertionOrder.displayName 필드
common_data.active InsertionOrder.entityStatus 필드
common_data.integration_code InsertionOrder.integrationDetails.integrationCode 필드
advertiser_id InsertionOrder.advertiserId 필드
campaign_id InsertionOrder.campaignId 필드
overall_budget 사용할 수 없음. InsertionOrder.budget.budgetSegments 필드의 콘텐츠를 사용하여 계산할 수 있습니다.
scheduled_segments InsertionOrder.budget.budgetSegments 필드
frequency_cap InsertionOrder.frequencyCap 필드
default_partner_costs InsertionOrder.partnerCosts 필드
default_target_list advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions 메서드를 통해 가져올 수 있습니다.

InventorySource

ERF 필드 이름DV360 API 사용 가능 여부
id InventorySource.inventorySourceId 필드
미분류 사용할 수 없음.
inventory_name InventorySource.displayName 필드
exchange_id InventorySource.exchange 필드
accessing_advertisers InventorySource.readWriteAccessors 및 InventorySource.readAdvertiserIds 필드.
external_id InventorySource.dealId 필드
min_cpm_micros InventorySource.rateDetails.rate.nanos 필드( InventorySource.rateDetails.inventorySourceRateType 필드 값에 따라 다름)
min_cpm_currency_code InventorySource.rateDetails.rate.currencyCode 필드

LineItem

ERF 필드 이름DV360 API 사용 가능 여부
common_data.id LineItem.lineItemId 필드
common_data.name LineItem.displayName 필드
common_data.active LineItem.entityStatus 필드
common_data.integration_code LineItem.integrationDetails.integrationCode 필드
line_item_type LineItem.lineItemType 필드
insertion_order_id LineItem.insertionOrderId 필드
creative_ids LineItem.creativeIds 필드
max_cpm_advertiser_micros 사용된 전략 스키마에 따라 LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros 또는 LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros 필드
performance_goal 사용된 전략 스키마에 따라 LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType 또는 LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType 필드
goal_advertiser_micros LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros 필드
partner_revenue_model LineItem.partnerRevenueModel 필드
cost_tracking_pixels LineItem.conversionCounting.floodlightActivityConfigs 필드
budget.start_time_usec LineItem.flight.dateRange.startDate 필드
budget.end_time_usec LineItem.flight.dateRange.endDate 필드
budget.max_impressions LineItem.budget.budgetUnit 가 BUDGET_UNIT_IMPRESSIONS 인 경우 LineItem.budget.maxAmount 필드
budget.max_spend_advertiser_micros LineItem.budget.budgetUnit 가 BUDGET_UNIT_CURRENCY 인 경우 LineItem.budget.maxAmount 필드
budget.pacing_type LineItem.pacing.pacingPeriod 필드
budget.pacing_max_impressions LineItem.pacing.dailyMaxImpressions 필드
budget.pacing_max_spend_advertiser_micros LineItem.pacing.dailyMaxMicros 필드
budget.pacing_distribution LineItem.pacing.pacingType 필드
frequency_cap LineItem.frequencyCap 필드
partner_costs LineItem.partnerCosts 필드
target_list advertisers.lineItems.bulkListLineItemAssignedTargetingOptions 메서드를 통해 가져올 수 있습니다.

NegativeKeywordList

ERF 필드 이름DV360 API 사용 가능 여부
id NegativeKeywordList.negativeKeywordListId 필드
이름 NegativeKeywordList.displayName 필드
advertiser_id NegativeKeywordList.advertiserId 필드

파트너

ERF 필드 이름DV360 API 사용 가능 여부
common_data.id Partner.partnerId 필드
common_data.name Partner.displayName 필드
common_data.active Partner.entityStatus 필드
common_data.integration_code 사용할 수 없음.
currency_code Partner.generalConfig.currencyCode 필드
exchange_settings Partner.exchangeConfig.enabledExchanges 필드
default_partner_costs 사용할 수 없음.
default_partner_revenue 사용할 수 없음.
default_target_list 사용할 수 없음.

Pixel

Display & Video 360 API에서 사용할 수 있는 동등한 리소스 또는 필드는 없습니다.

UniversalChannel

ERF 필드 이름DV360 API 사용 가능 여부
id Channel.channelId 필드
이름 Channel.displayName 필드
site_ids owner 유형에 따라 advertisers.channels.sites.list 및 partners.channels.sites.list 메서드를 통해 가져올 수 있습니다.
accessing_advertisers 사용할 수 없음.
is_deleted 사용할 수 없음.
is_brand_safe_channel 사용할 수 없음.

UserList

ERF 필드 이름DV360 API 사용 가능 여부
id FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId 필드
이름 FirstAndThirdPartyAudience.displayName 필드
data_partner_id 사용할 수 없음.
accessing_advertisers 사용할 수 없음.
partner_pricing 사용할 수 없음.
advertiser_pricings 사용할 수 없음.