다음을 통해 공유

광고 성과 데이터 가져오기

Microsoft Store 분석 API에서 이 메서드를 사용하여 지정된 날짜 범위 및 기타 선택적 필터 동안 애플리케이션에 대한 집계 광고 성능 데이터를 가져옵니다. 이 메서드는 JSON 형식으로 데이터를 반환합니다.

이 메서드는 파트너 센터의 광고 성과 보고서에서 제공하는 것과 동일한 데이터를 반환합니다.

필수 조건

이 메서드를 사용하려면 먼저 다음을 수행해야 합니다.

  • 아직 수행하지 않은 경우 Microsoft Store 분석 API에 대한 모든 필수 구성 요소를 완료합니다.
  • 이 메서드에 대한 요청 헤더에서 사용할 Azure AD 액세스 토큰을 가져옵니다. 액세스 토큰을 받은 후 60분 이내에 사용해야 합니다. 그렇지 않으면 만료됩니다. 토큰이 만료되면 새 토큰을 가져올 수 있습니다.

자세한 내용은 Microsoft Store 서비스를 사용하여분석 데이터에 액세스하는 방법에 대해 를 참조하세요.

요청

요청 구문

메서드 URI 요청
가져오기 https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance

요청 헤더

헤더 유형 설명
승인 문자열 필수 사항입니다. Azure AD의 액세스 토큰은 Bearer<토큰> 형식입니다.

요청 매개 변수

특정 앱에 대한 광고 성능 데이터를 검색하려면 applicationId 매개 변수를 사용합니다. 개발자 계정과 연결된 모든 앱의 광고 성과 데이터를 검색하려면 applicationId 매개 변수를 생략합니다.

매개 변수 유형 설명 필수
애플리케이션 아이디 문자열 광고 성과 데이터를 검색하려는 앱의 스토어 ID 입니다. 아니오
시작 날짜 날짜 광고 성과 데이터에서 검색할 날짜 범위의 시작 날짜이며, YYYY/MM/DD 형식입니다. 기본값은 현재 날짜에서 30일을 뺀 날짜입니다. 아니오
종료일 날짜 검색할 광고 성과 데이터의 날짜 범위의 종료 날짜(YYYY/MM/DD 형식)입니다. 기본값은 현재 날짜에서 1일을 뺀 날짜입니다. 아니오
맨 위로 정수 (int) 요청에 반환할 데이터 행 수입니다. 지정하지 않으면 최대값과 기본값은 10000입니다. 쿼리에 행이 더 있는 경우 응답 본문에는 다음 데이터 페이지를 요청하는 데 사용할 수 있는 다음 링크가 포함됩니다. 아니오
건너뛰기 정수 (int) 쿼리에서 건너뛸 행의 수를 지정합니다. 이 매개변수를 사용하여 대량의 데이터 집합을 탐색하십시오. 예를 들어 top=10000 및 skip=0은 처음 10000개의 데이터 행을 검색하고 top=10000 및 skip=10000은 다음 10000개 행의 데이터 등을 검색합니다. 아니오
필터 문자열 응답의 행을 필터링하는 하나 이상의 구문이 있습니다. 자세한 내용은 아래 필터 필드 섹션을 참조하세요. 아니오
집계 수준 문자열 집계 데이터를 검색할 시간 범위를 지정합니다. 일, 주 또는 월 문자열 중 하나일 수 있습니다. 지정되지 않은 경우 기본값은 day입니다. 아니오
오더바이 (orderby) 문자열 결과 데이터 값을 정렬하는 문입니다. 구문은 orderby=field [order], field [order],.... 필드 매개 변수는 다음 문자열 중 하나일 수 있습니다.
  • 날짜
  • 시장
  • 장치 유형
  • 광고 단위 ID

order 매개 변수는 선택 사항이며 각 필드에 대해 오름차순 또는 내림차순을 지정하는 asc 또는 desc일 수 있습니다. 기본값은 asc입니다.

다음은 orderby 문자열의 예입니다. orderby=date,market

 아니오
그룹바이 문자열 지정된 필드에만 데이터 집계를 적용하는 문입니다. 다음 필드를 지정할 수 있습니다.

  • 애플리케이션 ID
  • 애플리케이션 이름
  • 날짜
  • 계정통화코드
  • 시장
  • 장치 유형
  • 광고 단위 이름
  • 광고 단위 ID
  • pubCenter앱 이름
  • 광고 공급자

groupby 매개 변수는 aggregationLevel 매개 변수와 함께 사용할 수 있습니다. 예: &groupby=applicationId&aggregationLevel=week

 아니오

필터 필드

요청 본문의 필터 매개 변수에는 응답의 행을 필터링하는 하나 이상의 문이 포함되어 있습니다. 각 문에는 eq 또는 ne 연산자와 연결된 필드와 값이 포함되며, 문장은 and 또는 or을 사용하여 결합할 수 있습니다. 다음은 필터 매개 변수의 예입니다.

  • filter=market eq 'US' 및 deviceType eq 'phone'

지원되는 필드 목록은 다음 표를 참조하세요. 문자열 값은 필터 매개 변수에서 작은따옴표로 묶어야 합니다.

분야 설명
시장 광고가 제공된 시장의 ISO 3166 국가 코드가 포함된 문자열입니다.
디바이스 유형 PC/태블릿 또는 휴대폰 문자열 중 하나입니다.
광고 단위 ID (adUnitId) 필터에 적용할 광고 단위 ID를 지정하는 문자열입니다.
pubCenter앱 이름 필터에 적용할 현재 앱의 pubCenter 이름을 지정하는 문자열입니다.
광고 제공자 필터에 적용할 광고 공급자 이름을 지정하는 문자열입니다.
날짜 필터에 적용할 날짜를 YYYY/MM/DD 형식으로 지정하는 문자열입니다.

예제 요청

다음 예제에서는 광고 성과 데이터를 가져오기 위한 몇 가지 요청을 보여 줍니다. applicationId 값을 앱의 스토어 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가 포함됩니다. 예를 들어 요청의 최상위 매개 변수가 5로 설정되어 있지만 쿼리에 대한 데이터 항목이 5개 이상인 경우 이 값이 반환됩니다.
총개수 정수 (int) 쿼리의 데이터 결과에 포함된 행의 총 개수입니다.

광고 성과 지표

값 배열의 요소는 다음 값을 포함합니다.

가치 유형 설명
날짜 문자열 광고 성과 데이터에 대한 날짜 범위의 첫 번째 날짜입니다. 요청이 1일을 지정한 경우 이 값은 해당 날짜입니다. 요청이 주, 월 또는 기타 날짜 범위를 지정한 경우 이 값은 해당 날짜 범위의 첫 번째 날짜입니다.
애플리케이션 아이디 문자열 광고 성과 데이터를 검색하는 앱의 스토어 ID입니다.
응용 프로그램 이름 문자열 앱의 표시 이름입니다.
광고 단위 ID (adUnitId) 문자열 광고 단위의 ID입니다.
광고단위이름 문자열 파트너 센터의 개발자가 지정한 광고 단위의 이름입니다.
광고 제공자 문자열 광고 공급자의 이름
디바이스 유형 문자열 광고가 제공된 디바이스의 유형입니다. 지원되는 문자열 목록은 위의 필터 필드 섹션을 참조하세요.
시장 문자열 광고가 제공된 시장의 ISO 3166 국가 코드입니다.
계좌통화코드 문자열 계정의 통화 코드입니다.
pubCenter앱 이름 문자열 파트너 센터의 앱과 연결된 pubCenter 앱의 이름입니다.
광고제공자요청 정수 (int) 지정된 광고 공급자에 대한 광고 요청 수입니다.
노출 수 정수 (int) 광고 노출 수입니다.
클릭 횟수 정수 (int) 광고 클릭 수입니다.
계정 통화 매출 숫자 계정의 국가/지역에 대한 통화로 된 수익입니다.
요청사항 정수 (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
}
  • Last updated on