항목 읽기 파일 (ERF)은 Google Cloud Storage를 통해 제공되는 파트너의 캠페인 객체를 JSON으로 표현한 것입니다.
ERF는 2021년 6월에 지원 중단되었으며 2024년 10월 31일에 지원 종료됩니다. ERF가 더 이상 생성되지 않습니다. Display & Video 360 API를 사용하여 Display & Video 360 리소스를 가져옵니다.
이 가이드에서는 다음과 같이 항목 읽기 파일에서 Display & Video 360 API로 이전하는 방법을 설명합니다.
- 두 인터페이스의 차이점에 대한 개요 제공
- ERF 테이블과 API 서비스 비교
- API를 통한 항목 검색에 관한 안내 제공
- 기존 데이터 격차 확인
- 모든 ERF 필드와 비슷한 API 리소스 필드 간의 매핑 표시
개요
ERF에서 Display & Video 360 API로 이전할 때는 다음과 같은 몇 가지 주요 차이점을 고려해야 합니다.
- 데이터 최신성 ERF는 API가 최신 버전의 리소스를 가져오는 동안 매일 일괄 생성됩니다.
- 리소스 구조 API는 동일한 리소스 유형을 나타내기 위해 ERF와 다른 JSON 구조를 사용합니다. 공개 타겟팅 설정과 같은 일부 리소스는 다른 ID 공간을 사용할 수 있습니다.
- 가져오기 방법. Display &Video 360 API는 ERF에서 제공하는 원시 JSON 파일과 달리 페이지로 나눈 목록에서 또는 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 공간이 업데이트되어 SDF를 ERF에서 분리하고 Display & Video 360 API와 더욱 일치하도록 했습니다. 자세한 내용은 v7 이전 가이드 및 참조 문서를 참고하세요.
비공개 리소스
ERF 비공개 테이블은 파트너가 소유한 비공개 리소스의 현재 설정에 대한 일일 스냅샷을 제공합니다. 단일 파트너 아래에서 만들 수 있는 리소스의 양이 많기 때문에 이러한 파일은 매우 커질 수 있으며 다운로드 및 처리하기 어려울 수 있습니다.
API에서 각 비공개 테이블에는 해당 리소스 유형의 검색 및 관리를 위한 엔드포인트를 제공하는 상응하는 서비스가 있습니다. 각 서비스의 각 목록 메서드를 사용하여 리소스를 일괄적으로 검색할 수 있습니다. 각 리소스의 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는 프로젝트당 광고주당 요청 비율 제한을 사용하여 인프라를 보호합니다. 이 할당량 구조를 사용하면 여러 광고주에 걸쳐 필요한 모든 리소스를 검색하는 데 걸리는 총 시간을 줄이는 멀티스레드 솔루션을 구현할 수 있습니다. 페이징을 사용하려면 특정 범위 내의 특정 유형의 모든 리소스를 연속 호출을 통해 검색해야 하지만 다른 범위 또는 다른 유형의 리소스는 동시에 검색할 수 있습니다.
- 목록 호출에서 필터 및 순서 매개변수를 활용하여 관련 리소스만 검색합니다. 예를 들어 지난 1일 동안 업데이트된 광고 항목에만 관심이 있는 경우
advertisers.lineItems.list
메서드의filter
매개변수를 사용하여 지정된 타임스탬프보다 큰updateTime
가 있는 광고 항목만 반환할 수 있습니다. 이렇게 하면 실행해야 하는 요청 수를 크게 줄일 수 있습니다. - 불필요한 API 요청을 방지하기 위해 정기적으로 사용되는 ID를 캐시합니다. 타겟팅 옵션 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의 기존 타겟팅 유형 및 타겟팅 옵션 필드에 매핑합니다. 한 필드의 값이 다른 필드에 매핑될 수 있지만, 동일한 데이터 유형, 열거형 값 또는 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
enum입니다.
|
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
enum.
|
이름 |
Exchange
enum.
|
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 공간을 활용한다고 보장할 수는 없습니다.
광고주
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.inventorySourceRateType
필드의 값에 따라
InventorySource.rateDetails.rate.nanos
필드
|
min_cpm_currency_code |
InventorySource.rateDetails.rate.currencyCode
필드.
|
LineItem
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 | 사용할 수 없음. |