광고 성과 데이터 가져오기
Microsoft Store 분석 API에서 이 메서드를 사용하여 지정된 날짜 범위 및 다른 선택 필터 동안 애플리케이션의 광고 성과 집계 데이터를 가져옵니다. 이 메서드는 JSON 형식으로 데이터를 반환합니다.
이 메서드는 파트너 센터의 광고 성과 보고서에서 제공하는 데이터와 동일합니다.
필수 조건
이 메서드를 사용하려면 먼저 다음을 수행해야 합니다.
- 아직 완료하지 않은 경우 Microsoft Store 분석 API에 대한 모든 필수 조건을 완료합니다.
- 이 메서드에 대한 요청 헤더에 사용할 Azure AD 액세스 토큰을 가져옵니다. 액세스 토큰을 가져온 후 만료되기까지 60분이 걸립니다. 토큰이 만료된 후 새 토큰을 가져올 수 있습니다.
자세한 정보는 Microsoft Store 서비스를 사용하여 분석 데이터에 액세스하기를 참조하세요.
요청
요청 구문
| 메서드 | 요청 URI |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance |
요청 헤더
| 헤더 | 유형 | 설명 |
|---|---|---|
| 권한 부여 | 문자열 | 필수. Bearer<토큰> 형식의 Azure AD 액세스 토큰. |
요청 매개 변수
특정 앱에 대한 광고 성과 데이터를 검색하려면 applicationId 매개 변수를 사용합니다. 개발자 계정과 연결된 모든 앱의 광고 성과 데이터를 검색하려면 applicationId 매개 변수를 생략합니다.
| 매개 변수 | 형식 | 설명 | 필수 |
|---|---|---|---|
| applicationId | 문자열 | 광고 성과 데이터를 검색할 앱의 Store ID. | 아니요 |
| startDate | 날짜 | YYYY/MM/DD 형식의 검색할 광고 성과 데이터의 날짜 범위의 시작 날짜. 기본값은 현재 날짜에서 30일을 뺀 값입니다. | 아니요 |
| endDate | 날짜 | YYYY/MM/DD 형식의 검색할 광고 성과 데이터의 날짜 범위의 종료 날짜. 기본값은 현재 날짜에서 하루를 뺀 값입니다. | 아니요 |
| top | int | 요청에서 반환할 데이터 행의 수. 지정되지 않은 경우 최댓값 및 기본값은 10000입니다. 쿼리에 행이 더 있는 경우, 다음 데이터 페이지를 요청하는 데 사용할 수 있는 다음 링크가 응답 본문에 포함됩니다. | 아니요 |
| skip | int | 쿼리에서 건너뛸 행 수. 이 매개 변수를 사용하여 큰 데이터 집합을 페이징합니다. 예를 들어 top=10000 및 skip=0은 데이터의 첫 10000행을 검색하고 top=10000 및 skip=10000은 데이터의 그 다음 10000행을 검색하는 식으로 이어집니다. | 아니요 |
| 필터 | 문자열 | 응답의 행을 필터링하는 하나 이상의 문. 자세한 정보는 아래의 필터 필드 섹션을 참조하세요. | 아니요 |
| aggregationLevel | 문자열 | 집계 데이터를 검색할 시간 범위를 지정합니다. day , week 또는 month 문자열 중 하나일 수 있습니다. 지정하지 않았을 때, 기본값은 day입니다. | 아니요 |
| orderby | 문자열 | 결과 데이터 값을 정렬하는 문. 구문은 orderby=field [order],field [order],...입니다. field 매개 변수는 다음 문자열 중 하나일 수 있습니다.
order 매개 변수는 옵션이며 각 필드를 asc 또는 desc로 오름차순 또는 내림차순으로 지정할 수 있습니다. 기본값은 asc입니다. 다음은 orderby 문자열의 예시입니다. orderby=date,market |
아니요 |
| groupby | 문자열 | 지정된 필드에만 데이터 집계를 적용하는 문. 다음과 같은 필드를 지정할 수 있습니다.
groupby 매개 변수는 aggregationLevel 매개 변수와 함께 사용할 수 있습니다. 예시: &groupby=applicationId&aggregationLevel=week |
아니요 |
필터 필드
요청의 필터 매개 변수는 응답 본문의 행을 필터링하는 하나 이상의 문을 포함합니다. 각 문에는 eq 또는 ne 연산자와 연결된 필드 및 값이 포함되며 and 또는 or를 사용하여 문을 결합할 수 있습니다. 다음은 필터 매개 변수의 예시입니다.
- filter=market eq 'US' and deviceType eq 'phone'
지원되는 필드 목록은 다음의 테이블을 참조하세요. 문자열 값은 필터 매개 변수에서 단일 따옴표로 묶여야 합니다.
| 필드 | 설명 |
|---|---|
| 시장 | 광고가 제공된 시장의 ISO 3166 국가 코드를 포함하는 문자열. |
| deviceType | 다음의 문자열 중 하나입니다. PC/태블릿 또는 전화. |
| adUnitId | 필터에 적용할 광고 단위 ID를 지정하는 문자열. |
| pubCenterAppName | 필터에 적용할 현재 앱의 pubCenter 이름을 지정하는 문자열. |
| adProvider | 필터에 적용할 광고 공급자 이름을 지정하는 문자열. |
| 날짜 | 필터에 적용할 날짜를 YYYY/MM/DD 형식으로 지정하는 문자열. |
요청 예제
다음의 예시는 광고 성과 데이터를 가져오기 위한 몇 가지 요청을 보여 줍니다. applicationId 값을 앱의 Store ID로 바꿉니다.
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance?applicationId=9NBLGGH4R315&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance?applicationId=9NBLGGH4R315&startDate=8/1/2015&endDate=8/31/2015&skip=0&$filter=market eq 'US' and deviceType eq 'phone’ eq 'US'; and gender eq 'm' HTTP/1.1
Authorization: Bearer <your access token>
응답
응답 본문
| 값 | 형식 | 설명 |
|---|---|---|
| 값 | 배열 | 집계된 광고 성과 데이터를 포함하는 개체의 배열. 각 개체의 데이터에 대한 자세한 정보는 아래의 광고 성과 값 섹션을 참조하십시오. |
| @nextLink | 문자열 | 추가적인 데이터 페이지가 있는 경우, 다음 데이터 페이지를 요청하는 데 사용할 수 있는 URI가 이 문자열에 포함됩니다. 예를 들어 요청의 top 매개 변수가 5로 설정되어 있지만 쿼리에 대한 데이터 항목이 5개 이상인 경우 이 값이 반환됩니다. |
| TotalCount | int | 쿼리에 대한 데이터 결과의 총 행 수. |
광고 성과 값
값 배열의 요소에는 다음의 값이 포함됩니다.
| 값 | 형식 | 설명 |
|---|---|---|
| 날짜 | 문자열 | 광고 성과 데이터의 날짜 범위의 첫 번째 날짜. 요청에서 하루를 지정한 경우 이 값은 해당 날짜입니다. 요청에서 주, 월 또는 다른 날짜 범위를 지정한 경우 이 값은 해당 날짜 범위의 첫 번째 날짜입니다. |
| applicationId | 문자열 | 광고 성과 데이터를 검색할 앱의 Store ID. |
| applicationName | 문자열 | 앱의 표시 이름. |
| adUnitId | 문자열 | 광고 단위의 ID. |
| adUnitName | 문자열 | 파트너 센터에서 개발자가 지정한 광고 단위 이름. |
| adProvider | 문자열 | 광고 공급자의 이름. |
| deviceType | 문자열 | 광고가 제공된 디바이스 유형. 지원되는 문자열 목록은 위의 필터 필드 섹션을 참조하세요. |
| 시장 | 문자열 | 광고가 제공된 시장의 ISO 3166 국가 코드. |
| accountCurrencyCode | 문자열 | 계정의 통화 코드. |
| pubCenterAppName | 문자열 | 파트너 센터에서 앱과 연결된 pubCenter 앱의 이름. |
| adProviderRequests | int | 지정된 광고 공급자에 대한 광고 요청 수. |
| impressions | int | 광고 노출 수. |
| clicks | int | 광고 클릭 수. |
| revenueInAccountCurrency | number | 계정의 국가/하위 지역에 대한 통화로 된 수익. |
| requests | int | 광고 요청 수. |
응답 예제
다음 예제는 이 요청의 JSON 응답 본문 예제를 보여 줍니다.
{
"Value": [
{
"date": "2015-03-09",
"applicationId": "9NBLGGH4R315",
"applicationName": "Contoso Demo",
"market": "US",
"deviceType": "phone",
"adUnitId":"10765920",
"adUnitName":"TestAdUnit",
"revenueInAccountCurrency": 10.0,
"impressions": 1000,
"requests": 10000,
"clicks": 1,
"accountCurrencyCode":"USD"
},
{
"date": "2015-03-09",
"applicationId": "9NBLGGH4R315",
"applicationName": "Contoso Demo",
"market": "US",
"deviceType": "phone",
"adUnitId":"10795110",
"adUnitName":"TestAdUnit2",
"revenueInAccountCurrency": 20.0,
"impressions": 2000,
"requests": 20000,
"clicks": 3,
"accountCurrencyCode":"USD"
},
],
"@nextLink": "adsperformance?applicationId=9NBLGGH4R315&aggregationLevel=week&startDate=2015/03/01&endDate=2016/02/01&top=2&skip=2",
"TotalCount": 191753
}
관련 항목
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기