게임 및 앱에 대한 추가 기능 취득 데이터 가져오기
Microsoft Store 분석 API에서 이 방법을 사용하여 XDP(Xbox 개발자 포털)를 통해 수집되고 XDP 분석 파트너 센터 대시보드에서 사용할 수 있는 UWP 앱 및 Xbox One 게임에 대한 JSON 형식의 집계 추가 기능 획득 데이터를 가져옵니다.
필수 조건
이 메서드를 사용하려면 먼저 다음 방법대로 해야 합니다.
- 아직 완료하지 않은 경우 Microsoft Store 분석 API에 대한 모든 필수 조건을 완료합니다.
- 이 메서드에 대한 요청 헤더에 사용할 Azure AD 액세스 토큰을 가져오세요. 액세스 토큰을 가져온 후 만료되기까지 60분이 걸립니다. 토큰이 만료된 후 새 토큰을 가져올 수 있습니다.
참고 항목
이 API는 2016년 10월 1일 이전의 일별 집계 데이터를 제공하지 않습니다.
요청
요청 구문
| 메서드 | 요청 URI |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions |
요청 헤더
| 헤더 | 형식 | 설명 |
|---|---|---|
| 권한 부여 | string | 필수입니다. 전달자 형식의 Azure AD 액세스 토큰입니다<token>. |
요청 매개 변수
applicationId 또는 addonProductId 매개 변수가 필요합니다. 앱에 등록된 모든 추가 기능의 획득 데이터를 검색하려면 applicationId 매개변수를 지정하세요. 단일 추가 기능에 대한 구입 데이터를 검색하려면 addonProductId 매개 변수를 지정합니다. 둘 다 지정하면 applicationId 매개변수가 무시됩니다.
| 매개 변수 | 형식 | 설명 | 필수 |
|---|---|---|---|
| applicationId | string | 취득 데이터를 검색할 Xbox One 게임의 productId입니다. 게임의 productId를 가져오려면 XDP 분석 프로그램에서 게임으로 이동하고 URL에서 productId를 검색합니다. 또는 파트너 센터 분석 보고서에서 획득 데이터를 다운로드하는 경우 productId가 .tsv 파일에 포함됩니다. | 예 |
| addonProductId | string | 구입 데이터를 검색할 추가 기능의 productId입니다. | 예 |
| startDate | date | 검색할 추가 기능 획득 데이터의 날짜 범위 중 시작 날짜입니다. 기본값은 현재 날짜입니다. | 아니요 |
| endDate | date | 검색할 추가 기능 획득 데이터의 날짜 범위 중 종료 날짜입니다. 기본값은 현재 날짜입니다. | 아니요 |
| 필터 | 문자열 | 응답의 행을 필터링하는 한 개 이상의 구문입니다. 각 명령문에는 응답 본문의 필드 이름 및 eq 또는 ne 연산자와 연결된 값이 포함되며, 명령문은 and 또는 or을 사용하여 결합될 수 있습니다. 문자열 값은 필터 매개 변수에서 단일 따옴표로 묶여야 합니다. 예시: filter=market eq 'US' and gender eq 'm'. 응답 본문에서 지정할 수 있는 필드는 다음과 같습니다.
|
아니요 |
| aggregationLevel | 문자열 | 집계 데이터를 검색할 시간 범위를 지정합니다. 일 문자열, 주 문자열 또는 월 문자열 중 하나일 수 있습니다. 지정하지 않으면 기본값이 일이 됩니다. | 아니요 |
| orderby | 문자열 | 각각의 추가 기능 획득에 대한 결과 데이터 값의 순서를 지정하는 구문입니다. 구문은 orderby=field [order],field [order],...입니다. field 매개 변수는 다음 문자열 중 하나일 수 있습니다.
다음은 orderby 문자열의 예시입니다. orderby=date,market |
아니요 |
| groupby | 문자열 | 지정된 필드에만 데이터 집계를 적용하는 구문입니다. 지정할 수 있는 필드는 다음과 같습니다.
|
아니요 |
요청 예시
다음 예제에서는 추가 기능 획득 데이터를 가져오기 위한 여러 가지 요청을 보여줍니다. addonProductId 및 applicationId 값을 추가 기능 또는 앱에 대한 Store ID로 적절하게 바꿉니다.
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&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/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0&filter=market eq 'GB' and gender eq 'm' HTTP/1.1
Authorization: Bearer <your access token>
응답
응답 본문
| 값 | 형식 | 설명 |
|---|---|---|
| 값 | 배열 | 추가 기능 획득 집계 데이터가 들어 있는 개체의 배열입니다. 각 개체 속의 데이터에 대한 자세한 내용은 아래의 추가 기능 획득 값 섹션을 참조하세요. |
| TotalCount | int | 쿼리의 데이터 결과에 포함된 행의 총 개수입니다. |
추가 기능 획득 값
값 배열의 요소에는 다음의 값이 포함됩니다.
| 값 | 형식 | 설명 |
|---|---|---|
| date | 문자열 | 획득 데이터의 날짜 범위 중 첫 날짜입니다. 요청에서 하루를 지정한 경우, 이 값은 해당 날짜입니다. 요청에서 주, 월 또는 기타 날짜 범위를 지정한 경우, 이 값은 해당 날짜 범위 중 첫 날짜입니다. |
| addonProductId | string | 구입 데이터를 검색할 추가 기능의 productId입니다. |
| addonProductName | string | 추가 기능의 표시 이름입니다. aggregationLevel 매개 변수가 day로 설정되어 있는 경우 groupby 매개 변수에서 addonProductName 필드를 지정하지 않는 한 이 값은 응답 데이터에만 나타납니다. |
| applicationId | string | 추가 기능 구입 데이터를 검색하려는 앱의 productId입니다. |
| applicationName | string | 게임의 표시 이름입니다. |
| deviceType | string | 획득을 완료한 디바이스의 유형을 나타내는 다음 문자열 중 하나입니다.
|
| storeClient | string | 획득이 발생한 스토어의 버전을 나타내는 다음 문자열 중 하나입니다.
|
| osVersion | 문자열 | 획득이 발생한 OS 버전입니다. 이 메서드의 경우 이 값은 항상 Windows 10 또는 Windows 11 중 하나입니다. |
| 시장 | 문자열 | 획득이 발생한 시장의 ISO 3166 국가 번호입니다. |
| gender | string | 획득을 한 사용자의 성별을 나타내는 다음 문자열 중 하나입니다.
|
| 연령 | string | 획득을 한 사용자의 연령 그룹을 나타내는 다음 문자열 중 하나입니다.
|
| acquisitionType | string | 획득 유형을 나타내는 다음 문자열 중 하나입니다.
|
| acquisitionQuantity | 정수 | 발생한 획득의 횟수입니다. |
| inAppProductId | string | 이 추가 기능이 사용되는 제품의 제품 ID입니다. |
| inAppProductName | string | 이 추가 기능이 사용되는 제품의 제품 이름입니다. |
| paymentInstrumentType | string | 취득에 사용된 결제 방법 유형입니다. |
| sandboxId | string | 게임에 대해 생성된 샌드박스 ID입니다. RETAIL 값 또는 개인 샌드박스 ID일 수 있습니다. |
| xboxTitleId | string | 해당하는 경우 XDP 제품의 Xbox 제목 ID입니다. |
| 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 제품의 구매 세금 유형입니다. |
| purchasePriceUSDAmount | number | 추가 기능에 대해 고객이 지불한 금액으로 USD로 변환됩니다. |
| purchasePriceLocalAmount | number | 지역 통화로 표시된 추가 기능에 대해 고객이 지불한 금액입니다. |
| purchaseTaxUSDAmount | number | 추가 기능에 적용된 세액이며 USD로 변환됩니다. |
| purchaseTaxLocalAmount | number | 해당하는 경우 XDP 제품의 구매 세금 현지 금액입니다. |
응답 예시
다음 예제에서는 이 요청에 대한 JSON 응답 본문의 예를 보여줍니다.
{
"Value": [
{
"inAppProductId": "9NBLGGH1864K",
"inAppProductName": "866879",
"addonProductId": "9NBLGGH1864K",
"addonProductName": "866879",
"date": "2017-11-05",
"applicationId": "9WZDNCRFJ314",
"applicationName": "Tetris Blitz",
"acquisitionType": "Iap",
"age": "35-49",
"deviceType": "Phone",
"gender": "m",
"market": "US",
"osVersion": "Windows Phone 8.1",
"paymentInstrumentType": "Credit Card",
"sandboxId": "RETAIL",
"storeClient": "Windows Phone Store (client)",
"xboxTitleId": "",
"localCurrencyCode": "USD",
"xboxProductId": "00000000-0000-0000-0000-000000000000",
"availabilityId": "",
"skuId": "",
"skuDisplayName": "Full",
"xboxParentProductId": "",
"parentProductName": "Tetris Blitz",
"productTypeName": "Add-On",
"purchaseTaxType": "",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 1.08,
"purchasePriceLocalAmount": 0.09,
"purchaseTaxUSDAmount": 1.08,
"purchaseTaxLocalAmount": 0.09
}
],
"@nextLink": null,
"TotalCount": 7601
}