이 가이드에서는 Authorized Buyers UI의 RTB 분류 도구를 통해 노출되는 실시간 입찰 캠페인 측정항목에 프로그래매틱 방식으로 액세스할 수 있는 RTB 문제 해결 리소스를 다룹니다. 여기에는 bidders.filterSets, bidders.accounts.filterSets, 그리고 계층적으로 하위에 있는 모든 리소스가 포함됩니다.
RTB 문제 해결 리소스의 측정항목을 사용하면 놓친 기회에 대한 유용한 정보를 얻을 수 있어 실시간 입찰 캠페인을 최적화하는 데 도움이 될 수 있습니다.
API 구조 및 스타일 조정
RTB 문제 해결 리소스에는 소유권과 액세스 권한을 명시적으로 표시하고, API에서 반환하는 데이터를 더욱 세부적으로 제어하며, Google API 설계 권장사항을 준수하는 데 필요한 몇 가지 변경사항이 있습니다.
입찰자 수준 및 계정 수준 리소스
리소스는 bidders 및 bidders.accounts 아래에 모두 구조화됩니다. 이를 통해 API 호출이 입찰자 (상위 계정이라고도 함) 및 연결된 모든 하위 계정을 타겟팅하는지 아니면 개별 Authorized Buyers 계정을 타겟팅하는지 지정할 수 있습니다. RTB 문제 해결의 관점에서 bidders.filterSets에 구조화된 리소스는 지정된 입찰자 및 연결된 모든 하위 계정에 대해 집계된 측정항목을 반환합니다. 반대로, bidders.accounts.filterSets 아래에 있는 앱은 입찰자 계정인지 하위 계정인지에 관계없이 지정된 계정의 측정항목만 반환합니다.
참고: 입찰을 다른 구매자에게 위임하는 계정은 입찰자 계정이 아니므로 입찰자 수준 리소스에 액세스할 수 없습니다. 또한 비입찰자 계정은 계정 수준 impressionMetrics, filteredBidResponses, bidResponseErrors, bidResponsesWithoutBids 리소스에 액세스할 수 없습니다.
리소스 이름을 고유 식별자로 도입
리소스 이름은 정수 또는 문자열 ID가 아닌 고유 식별자로 사용됩니다. 이제 특정 리소스 유형의 새 인스턴스를 만들 때 리소스의 URI 경로와 선호하는 리소스 ID를 차례로 사용하여 상대적 리소스 이름을 지정해야 합니다. 다음은 RTB 문제 해결 리소스와 관련된 이름의 예입니다.
| 리소스 | 이름 예 |
|---|---|
| bidders.filterSets | bidders/12345678/filterSets/fset_1 |
| bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
참고: 이름에서 bidders에 지정된 리소스 ID는 입찰자의 Authorized Buyers 계정 ID여야 합니다. accounts의 경우 리소스 ID는 입찰자의 계정 ID 또는 입찰자가 관리하는 하위 계정이어야 합니다. Google 계정과 연결된 Authorized Buyers 계정을 모르는 경우 accounts.list 메서드를 사용하여 해당 계정을 찾을 수 있습니다.
필터 세트
필터 세트는 사용할 수 있는 필터링 옵션을 나타내며 입찰자 또는 계정 수준에서 만들 수 있습니다. 실시간 입찰 캠페인의 측정항목을 가져오는 RTB 문제 해결 리소스의 목록 결과를 필터링하는 데 사용됩니다.
측정항목을 가져올 때 적용되는 필터는 지정된 필터 세트에 있는 각 필터의 교집합입니다. 목록 필터(예: platforms)는 목록에 있는 각 항목의 합집합으로 해석됩니다.
입찰자와 계정 수준 필터 세트는 구별되며 필터 세트를 만드는 데 사용된 계정과 관계없이 필터 세트가 생성된 수준에서만 액세스할 수 있습니다. 입찰자 및 하위 계정은 계정 수준에서 생성된 필터 세트를 공유하는 반면, 입찰자만 입찰자 수준의 리소스에 액세스할 수 있습니다. 다음 표에는 입찰자와 하위 계정이 각 수준에서 리소스에 액세스할 수 있는 방법이 요약되어 있습니다.
| bidders.filterSets | bidders.accounts.filterSets | |
|---|---|---|
| 입찰자 계정 | 입찰자 수준 필터 세트에만 영향을 미치는 API 호출입니다. | 계정 수준 필터 세트에만 영향을 미치는 API 호출입니다. |
| 자녀 계정 | 이 API 호출은 오류 응답을 반환합니다. | 계정 수준 필터 세트에만 영향을 미치는 API 호출입니다. |
필터 세트 만들기
필터 세트를 만들 때 기간을 relativeDateRange, absoluteDateRange, realtimeTimeRange로 지정해야 합니다. 측정항목을 가져올 때 기본 동작은 전체 기간 동안 모든 데이터가 제공되는 것입니다. 시간 범위에 대한 시계열 분석을 받으려면 timeSeriesGranularity를 지정하여 HOURLY 또는 DAILY 간격을 나타낼 수 있습니다.
짧은 기간 동안만 필터를 설정해야 하는 경우 isTransient 쿼리 매개변수를 true로 설정할 수 있습니다. 이는 필터 세트가 일시적임을 나타내며, 무기한으로 유지되지 않습니다. 일시적인 필터 세트는 생성 후 최소 1시간 동안 사용할 수 있지만 결국 삭제됩니다. 기본적으로 필터 세트는 일시적이지 않습니다.
입찰자 수준 예시
새 입찰자 수준 필터 세트를 만들려면 다음과 같은 형식의 bidders.filterSets 리소스 URI에 POST 요청을 전송합니다.
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
경고: 입찰자 수준 필터 세트는 광고 소재 또는 거래 ID로 필터링할 수 없습니다. 입찰자 수준 필터 세트를 만들 때 이러한 필터를 지정하면 오류 응답이 수신됩니다.
요청다음은 일시적이지 않은 새로운 입찰자 수준 필터 세트를 만드는 POST 요청의 예입니다.
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets
Authorization: Bearer access token here
Content-Type: application/json
{
"name": "bidders/12345678/filterSets/bidder-fs",
"format": "DISPLAY",
"environment": "APP",
"platforms": ["TABLET", "MOBILE"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
응답
요청이 성공하면 서버에서 200 OK 상태 코드로 응답합니다. 응답 본문에는 요청에 제출된 필터 세트와 동일한 생성된 필터 세트 리소스가 포함됩니다.
계정 수준의 예
새 계정 수준 필터 세트를 만들려면 다음과 같은 형식의 bidders.accounts.filterSets 리소스 URI에 POST 요청을 전송합니다.
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
참고: accounts에 지정된 리소스 ID는 입찰자 계정 자체를 포함하여 URI에 지정된 입찰자 계정에 액세스할 수 있는 모든 Authorized Buyers 계정의 계정 ID일 수 있습니다.
다음은 일시적이지 않은 새로운 계정 수준 필터 세트를 만드는 POST 요청의 예입니다.
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets
Authorization: Bearer access token here
Content-Type: application/json
{
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"format": "VIDEO",
"environment": "WEB",
"platforms": ["DESKTOP"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
응답
요청이 성공하면 서버에서 200 OK 상태 코드로 응답합니다. 응답 본문에는 생성된 필터 세트 리소스가 포함되며, 이 리소스는 요청에 제출된 필터 세트와 동일합니다.
필터 세트 가져오기
get 메서드는 생성된 수준에서만 필터 세트를 가져올 수 있습니다. 예를 들어 입찰자 계정은 bidders.accounts.filterSets.get를 사용하여 bidders.filterSets.get 메서드가 아닌 계정 수준에서 생성된 필터 세트를 검색해야 합니다.
입찰자 수준
다음과 같은 형식의 bidders.filterSets 리소스 URI에 HTTP GET 요청을 전송하여 입찰자 수준 필터 세트를 가져올 수 있습니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}
요청
다음 예를 참고하세요.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs응답
요청이 성공하면 서버에서 200 OK HTTP 상태 코드와 검색된 필터 세트를 반환합니다.
{
"name": "bidders/12345678/filterSets/bidder-fs",
"format": "DISPLAY",
"environment": "APP",
"platforms": ["TABLET", "MOBILE"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
계정 수준
다음과 같은 형식의 bidders.accounts.filterSets 리소스 URI에 HTTP GET 요청을 전송하여 계정 수준 필터 세트를 검색할 수 있습니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}
요청
다음 예를 참고하세요.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs응답
요청이 성공하면 서버에서 200 OK HTTP 상태 코드와 검색된 필터 세트를 반환합니다.
{
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"format": "VIDEO",
"environment": "WEB",
"platforms": ["DESKTOP"],
"absoluteDateRange": {
"startDate": {
"month": 11,
"day": 26,
"year": 2017
},
"endDate": {
"month": 12,
"day": 3,
"year": 2017
}
},
"timeSeriesGranularity": "DAILY"
}
필터 세트 나열
list 메서드는 호출 중인 수준에서 액세스할 수 있는 필터 세트만 반환합니다.
예를 들어 입찰자 계정은 bidders.filterSets.list를 호출할 때 bidders.accounts.filterSets.create를 통해 자체적으로 생성된 필터 세트를 볼 수 없습니다.
입찰자 수준
다음과 같은 형식의 bidders.filtersets 리소스 URI로 HTTP GET 요청을 전송하여 지정된 입찰자에 대한 모든 입찰자 수준 필터 세트를 가져올 수 있습니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
요청
다음은 계정 ID가 12345678인 입찰자에 대한 모든 입찰자 수준 필터 세트를 나열한 예입니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets응답
{
"filterSets": [{
"filterSetId": "99994",
"name": "bidders/12345678/filterSets/test-b-1",
"relativeDateRange": {
"durationDays": 30
}
},
{
"realtimeTimeRange": {
"startTimeStamp": "2017-11-15T12:30:30.072831583Z"
},
"filterSetId": "99995",
"name": "bidders/12345678/filterSets/test-b-2",
"timeSeriesGranularity": "HOURLY"
},
{
"absoluteDateRange": {
"endDate": {
"day": 12,
"month": 3,
"year": 2017
},
"startDate": {
"day": 26,
"month": 11,
"year": 2017
}
},
"filterSetId": "99996",
"name": "bidders/12345678/filterSets/bidder-fs",
"timeSeriesGranularity": "DAILY",
"platforms": ["TABLET", "MOBILE"],
"environment": "APP",
"format": "DISPLAY"
}
]
}
계정 수준
다음과 같은 형식의 bidders.accounts.filtersets 리소스 URI에 HTTP GET 요청을 전송하여 특정 계정의 모든 계정 수준 필터 세트를 검색할 수 있습니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
요청
다음은 계정 ID가 87654321인 하위 계정에 대한 모든 계정 수준 필터 조합을 표시하는 예입니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets응답
{
"filterSets": [{
"realtimeTimeRange": {
"startTimeStamp": "2017-11-19T04:24:43.252893487Z"
},
"filterSetId": "99997",
"name": "bidders/12345678/accounts/87654321/filterSets/test-a-1",
"timeSeriesGranularity": "DAILY"
},
{
"absoluteDateRange": {
"endDate": {
"day": 3,
"month": 12,
"year": 2017
},
"startDate": {
"day": 26,
"month": 11,
"year": 2017
}
},
"filterSetId": "99998",
"name": "bidders/12345678/accounts/87654321/filterSets/account-fs",
"timeSeriesGranularity": "DAILY",
"platforms": ["DESKTOP"],
"environment": "WEB",
"format": "VIDEO"
}
]
}
필터 세트 삭제
delete 메서드를 사용하여 더 이상 필요하지 않은 일시적이지 않은 필터 세트를 삭제할 수 있습니다. 호출 중인 수준에서 액세스할 수 있는 필터 세트만 삭제할 수 있습니다. 예를 들어 입찰자 계정은 bidders.filterSets.delete인 bidders.accounts.filterSets.create로 만든 필터 세트를 삭제할 수 없습니다.
입찰자 수준
다음과 같은 형식의 bidders.filtersets 리소스 URI에 HTTP DELETE 요청을 전송하여 특정 계정의 입찰자 수준 필터 세트를 삭제할 수 있습니다.
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}
요청
다음은 입찰자 수준 필터 세트를 삭제하는 예입니다.
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2응답
성공하면 요청 본문이 비어 있습니다. 지정된 필터 세트에 더 이상 액세스할 수 없습니다.
계정 수준
다음과 같은 형식의 bidders.accounts.filtersets 리소스 URI에 HTTP DELETE 요청을 전송하여 특정 계정의 계정 수준 필터 세트를 삭제할 수 있습니다.
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}
요청
다음은 계정 수준 필터 세트를 삭제하는 예입니다.
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1응답
성공하면 요청 본문이 비어 있습니다. 지정된 필터 세트에 더 이상 액세스할 수 없습니다.
RTB 문제 해결 측정항목을 가져옵니다.
측정항목을 수신하는 데 사용되는 모든 RTB 문제 해결 리소스는 비슷한 방식으로 작동합니다. filterSetName 경로 매개변수를 통해 지정된 필터 세트의 측정항목을 나열하는 단일 메서드가 있습니다. 지정된 필터 세트에 따라 측정항목을 쿼리할 때 적용되는 필터와 설정이 결정됩니다. 입찰자 수준에서 이러한 리소스를 호출하면 입찰자 계정 및 연결된 모든 하위 계정에서 집계된 측정항목이 반환되지만, 계정 수준에서 호출하면 개별 계정의 측정항목만 반환됩니다.
입찰 측정항목
bidMetrics 리소스는 입찰 수로 측정되는 측정항목을 검색하는 데 사용됩니다. 예를 들어 이를 사용하여 특정 기간의 총 입찰 수, 입찰에서 필터링되지 않았거나 노출을 획득한 입찰 수 등을 확인할 수 있습니다. 측정항목 수집에 사용되는 다른 모든 RTB 문제 해결 리소스와 마찬가지로 list 메서드만 있습니다.
입찰자 수준 입찰 측정항목 나열
다음과 같은 형식의 bidders.filtersets.bidMetrics 리소스 URI에 HTTP GET 요청을 전송하여 특정 필터 세트의 입찰자 수준 입찰 측정항목을 나열할 수 있습니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetrics
요청
다음은 입찰자 수준 입찰 측정항목을 나열한 예입니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetrics응답
요청이 성공하면 서버에서 200 OK 상태 코드와 지정된 측정기준 및 세부사항에 대한 측정항목 행이 포함된 본문을 반환합니다.
{
"bidMetricsRows": [{
"bids": {
"value": "6160"
},
"bidsInAuction": {
"value": "5698"
},
"billedImpressions": {
"value": "1196"
},
"impressionsWon": {
"value": "2920"
},
"measurableImpressions": {
"value": "1160"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-11-29T08:00:00Z",
"startTime": "2017-11-28T08:00:00Z"
}
},
"viewableImpressions": {
"value": "683"
}
},
{
"bids": {
"value": "104288"
},
"bidsInAuction": {
"value": "94016"
},
"billedImpressions": {
"value": "99"
},
"impressionsWon": {
"value": "125"
},
"measurableImpressions": {
"value": "94"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-11-30T08:00:00Z",
"startTime": "2017-11-29T08:00:00Z"
}
},
"viewableImpressions": {
"value": "87"
}
},
{
"bids": {
"value": "3999"
},
"bidsInAuction": {
"value": "3631"
},
"billedImpressions": {
"value": "618"
},
"impressionsWon": {
"value": "1819"
},
"measurableImpressions": {
"value": "604"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-01T08:00:00Z",
"startTime": "2017-11-30T08:00:00Z"
}
},
"viewableImpressions": {
"value": "369"
}
},
{
"bids": {
"value": "15"
},
"bidsInAuction": {
"value": "3"
},
"billedImpressions": {},
"impressionsWon": {
"value": "3"
},
"measurableImpressions": {},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-02T08:00:00Z",
"startTime": "2017-12-01T08:00:00Z"
}
},
"viewableImpressions": {}
}
]
}
참고: 지정된 측정항목에 대해 0으로 설정된 필드는 응답에 나타나지 않습니다.
위의 빈 billedImpressions 및 measurableImpressions 측정항목은 이러한 값의 값과 분산이 모두 0으로 설정되었음을 나타냅니다.
경고: 응답의 데이터 분류의 경우 0이 아닌 측정항목이 1개 이상 포함되지 않은 행은 응답에 포함되지 않습니다. 예를 들어 timeSeriesGranularity가 지정되면 필터 세트의 지정된 기간 동안 모든 측정항목이 0인 timeInterval의 행은 응답에 포함되지 않습니다.
계정 수준 입찰 측정항목 나열
다음과 같은 형식의 bidders.accounts.filtersets.bidMetrics 리소스 URI에 HTTP GET 요청을 전송하여 특정 필터 세트의 계정 수준 입찰 측정항목을 나열할 수 있습니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetrics
요청
다음은 계정 수준 입찰 측정항목을 보여주는 예입니다.
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetrics응답
요청이 성공하면 서버에서 200 OK 상태 코드와 지정된 측정기준 및 세부사항에 대한 측정항목 행이 포함된 본문을 반환합니다.
{
"bidMetricsRows": [{
"bids": {
"value": "1748"
},
"bidsInAuction": {
"value": "1421"
},
"billedImpressions": {
"value": "301"
},
"impressionsWon": {
"value": "915"
},
"measurableImpressions": {
"value": "298"
},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-01T08:00:00Z",
"startTime": "2017-11-30T08:00:00Z"
}
},
"viewableImpressions": {
"value": "172"
}
},
{
"bids": {
"value": "6"
},
"bidsInAuction": {
"value": "2"
},
"billedImpressions": {},
"impressionsWon": {
"value": "1"
},
"measurableImpressions": {},
"rowDimensions": {
"timeInterval": {
"endTime": "2017-12-02T08:00:00Z",
"startTime": "2017-12-01T08:00:00Z"
}
},
"viewableImpressions": {}
}
]
}
참고: 지정된 측정항목에 대해 0으로 설정된 필드는 응답에 나타나지 않습니다. 위의 빈 billedImpressions 및 measurableImpressions 측정항목은 이러한 값의 값과 분산이 모두 0으로 설정되었음을 나타냅니다.
경고: 응답의 데이터 분류의 경우 0이 아닌 측정항목이 1개 이상 포함되지 않은 행은 응답에 포함되지 않습니다. 예를 들어 timeSeriesGranularity가 지정되면 필터 세트의 지정된 기간 동안 모든 측정항목이 0인 timeInterval의 행은 응답에 포함되지 않습니다.