다음을 통해 공유

게임 및 앱에 대한 취득 데이터 가져오기

  • 아티클

Microsoft Store 분석 API에서 이 방법을 사용하여 XDP(Xbox 개발자 포털)를 통해 수집되고 XDP 분석 대시보드에서 사용할 수 있는 UWP 앱 및 Xbox One 게임에 대한 JSON 형식의 집계 획득 데이터를 가져옵니다.

참고 항목

이 API는 2016년 10월 1일 이전의 일별 집계 데이터를 제공하지 않습니다.

필수 조건

이 메서드를 사용하려면 먼저 다음 방법대로 해야 합니다.

  • 아직 완료하지 않은 경우 Microsoft Store 분석 API에 대한 모든 필수 조건을 완료합니다.
  • 이 메서드에 대한 요청 헤더에 사용할 Azure AD 액세스 토큰을 가져오세요. 액세스 토큰을 가져온 후 만료되기까지 60분이 걸립니다. 토큰이 만료된 후 새 토큰을 가져올 수 있습니다.

Request

요청 구문

메서드 요청 URI
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions

요청 헤더

헤더 형식 설명
권한 부여 string 필수입니다. 전달자 형식의 Azure AD 액세스 토큰입니다<token>.

요청 매개 변수

매개 변수 형식 설명 필수
applicationId string 취득 데이터를 검색할 Xbox One 게임의 제품 ID입니다. 게임의 제품 ID를 가져오려면 XDP 분석 프로그램에서 게임으로 이동하고 URL에서 제품 ID를 검색합니다. 또는 파트너 센터 분석 보고서에서 획득 데이터를 다운로드하는 경우 제품 ID가 .tsv 파일에 포함됩니다. 예
startDate date 검색할 획득 데이터의 날짜 범위 중 시작 날짜입니다. 기본값은 현재 날짜입니다. 아니요
endDate date 검색할 획득 데이터의 날짜 범위 중 종료 날짜입니다. 기본값은 현재 날짜입니다. 아니요
필터 문자열 응답의 행을 필터링하는 한 개 이상의 구문입니다. 각 명령문에는 응답 본문의 필드 이름 및 eq 또는 ne 연산자와 연결된 값이 포함되며, 명령문은 and 또는 or을 사용하여 결합될 수 있습니다. 문자열 값은 필터 매개 변수에서 단일 따옴표로 묶여야 합니다. 예시: filter=market eq 'US' and gender eq 'm'.
응답 본문에서 지정할 수 있는 필드는 다음과 같습니다.
  • acquisitionType
  • age
  • storeClient
  • gender
  • 시장
  • osVersion
  • deviceType
  • sandboxId
 아니요
aggregationLevel 문자열 집계 데이터를 검색할 시간 범위를 지정합니다. 일 문자열, 주 문자열 또는 월 문자열 중 하나일 수 있습니다. 지정하지 않으면 기본값이 일이 됩니다. 아니요
orderby 문자열 각각의 획득에 대한 결과 데이터 값의 순서를 지정하는 구문입니다. 구문은 orderby=field [order],field [order],...입니다. field 매개 변수는 다음 문자열 중 하나일 수 있습니다.
  • date
  • acquisitionType
  • age
  • storeClient
  • gender
  • 시장
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleId
순서 매개변수는 선택 사항이며, 각 필드를 오름차순 또는 내림차순으로 지정하기 위해 asc 또는 desc가 될 수 있습니다. 기본값은 asc입니다. 다음은 orderby 문자열의 예시입니다. orderby=date,market		 아니요
groupby 문자열 지정된 필드에만 데이터 집계를 적용하는 구문입니다. 지정할 수 있는 필드는 다음과 같습니다.
  • date
  • applicationName
  • acquisitionType
  • age
  • storeClient
  • gender
  • 시장
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleId
반환된 데이터 행에는 groupby 매개변수에 지정된 필드에 더하여 다음 필드도 포함됩니다.
  • date
  • applicationId
  • acquisitionQuantity
groupby 매개 변수는 aggregationLevel 매개 변수와 함께 사용할 수 있습니다. 예: &groupby=age,market&aggregationLevel=week		 아니요

요청 예시

다음 예제에서는 Xbox One 게임 취득 데이터를 가져오는 데 필요한 몇 가지 요청을 보여 줍니다. applicationId 값을 게임의 제품 ID로 바꿉니다.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&top=10&skip=0 HTTP/1.1 
Authorization: Bearer <your access token> 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&skip=0&filter=market eq 'US' and gender eq 'm' HTTP/1.1 
Authorization: Bearer <your access token>

응답

응답 본문

값 형식 설명
값 배열 게임의 집계 취득 데이터가 포함된 개체의 배열입니다. 각 개체의 데이터에 대한 자세한 내용은 아래의 획득 값 섹션을 참조하세요.
TotalCount 정수 쿼리의 데이터 결과에 포함된 행의 총 개수입니다.

획득 값

값 배열의 요소에는 다음 값이 포함됩니다.

값 형식 설명
date 문자열 획득 데이터의 날짜 범위 중 첫 날짜입니다. 요청에서 하루를 지정한 경우, 이 값은 해당 날짜입니다. 요청에서 주, 월 또는 기타 날짜 범위를 지정한 경우, 이 값은 해당 날짜 범위 중 첫 날짜입니다.
applicationId string 취득 데이터를 검색할 Xbox One 게임의 제품 ID입니다.
applicationName string 게임의 표시 이름입니다.
acquisitionType string 획득 유형을 나타내는 다음 문자열 중 하나입니다.
  • 무료
  • 평가판
  • 유료
  • 프로모션 코드
  • Iap
  • 구독 Iap
  • 개인 대상
  • 사전 주문
  • Xbox Game Pass(또는 2018년 3월 23일 이전에 데이터를 쿼리한 경우에는 Game Pass)
  • 디스크
  • 선불 코드
  • 청구된 사전 주문
  • 취소된 사전 주문
  • 실패한 사전 주문
연령 string 획득을 한 사용자의 연령 그룹을 나타내는 다음 문자열 중 하나입니다.
  • 13 미만
  • 13-17
  • 18-24
  • 25-34
  • 35-44
  • 44-55
  • 55보다 큼
  • 알 수 없음
deviceType string 획득을 완료한 디바이스의 유형을 나타내는 다음 문자열 중 하나입니다.
  • PC
  • 전화
  • 콘솔-Xbox One
  • 콘솔-Xbox 시리즈 X
  • IoT
  • 서버
  • 태블릿
  • Holographic
  • 알 수 없음
gender string 획득을 한 사용자의 성별을 나타내는 다음 문자열 중 하나입니다.
  • m
  • 여성
  • 알 수 없음
시장 문자열 획득이 발생한 시장의 ISO 3166 국가 번호입니다.
osVersion 문자열 획득이 발생한 OS 버전입니다. 이 메서드의 경우 이 값은 항상 Windows 10 또는 Windows 11 중 하나입니다.
paymentInstrumentType string 획득 시 사용된 결제 지침을 나타내는 다음 문자열 중 하나입니다.
  • 신용 카드
  • 직불 카드
  • 유추 구매
  • MS 잔액
  • 이동통신사
  • 온라인 계좌 이체
  • PayPal
  • 분할 거래
  • 토큰 상환
  • 금액 0 지불
  • eWallet
  • 알 수 없음
sandboxId string 게임에 대해 생성된 샌드박스 ID입니다. RETAIL 값 또는 개인 샌드박스 ID일 수 있습니다.
storeClient string 획득이 발생한 스토어의 버전을 나타내는 다음 문자열 중 하나입니다.
  • Windows Phone Store(클라이언트)
  • Microsoft Store(클라이언트)(또는 2018년 3월 23일 이전에 데이터를 쿼리한 경우 Windows Store(클라이언트))
  • Microsoft Store(웹)(또는 2018년 3월 23일 이전에 데이터를 쿼리한 경우 Windows Store(웹))
  • 조직에서 대량 구매
  • 기타
xboxTitleId string Xbox Live 지원 게임의 Xbox 개발자 포털(XDP)에서 할당한 Xbox Live 타이틀 ID(16진 값으로 표시)입니다.
acquisitionQuantity 수 지정된 집계 수준에서 발생한 획득의 횟수입니다.
purchasePriceUSDAmount number 취득을 위해 고객이 지불한 금액입니다. 이 금액은 월별 환율을 사용하여 USD로 변환됩니다.
purchaseTaxUSDAmount number 취득에 적용된 세금이며 USD로 변환됩니다.
localCurrencyCode string 파트너 센터 계정의 국가를 기반으로 하는 현지 통화 코드입니다.
xboxProductId string 해당하는 경우 XDP 제품의 Xbox 제품 ID입니다.
availabilityId string 해당되는 경우 XDP 제품의 가용성 ID입니다.
skuId string 해당하는 경우 XDP 제품의 SKU ID입니다.
skuDisplayName string 해당하는 경우 XDP 제품의 SKU 표시 이름입니다.
xboxParentProductId string 해당하는 경우 XDP 제품의 Xbox 상위 제품 ID입니다.
parentProductName string 해당되는 경우 XDP 제품의 부모 제품 이름입니다.
productTypeName string 해당하는 경우 XDP 제품의 제품 유형 이름입니다.
purchaseTaxType string 해당하는 경우 XDP 제품의 구매 세금 유형입니다.
purchasePriceLocalAmount number 해당하는 경우 XDP 제품의 구매 가격 현지 금액입니다.
purchaseTaxLocalAmount number 해당하는 경우 XDP 제품의 구매 세금 현지 금액입니다.

응답 예시

다음 예제에서는 이 요청에 대한 JSON 응답 본문의 예를 보여줍니다.

{ 
    "Value": [ 
        { 
            "date": "2019-01-15T01:00:00.0000000Z", 
            "applicationId": "9WZDNCRFHXHT", 
            "applicationName": null, 
            "acquisitionType": "Paid", 
            "age": null, 
            "deviceType": "Phone", 
            "gender": null, 
            "market": "US", 
            "osVersion": "Windows 11", 
            "paymentInstrumentType": null, 
            "sandboxId": "RETAIL", 
            "storeClient": "Microsoft Store (client)", 
            "xboxTitleId": null, 
            "localCurrencyCode": "USD", 
            "xboxProductId": null, 
            "availabilityId": "B42LRTSZ2MCJ", 
            "skuId": "0010", 
            "skuDisplayName": null, 
            "xboxParentProductId": null, 
            "parentProductName": null, 
            "productTypeName": "Game", 
            "purchaseTaxType": "TaxesNotIncluded", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 3.08, 
            "purchasePriceLocalAmount": 3.08, 
            "purchaseTaxUSDAmount": 0.09, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null,
    
    "TotalCount": 12221 
}