구독 추가 기능 취득 가져오기Get subscription add-on acquisitions

Microsoft Store analytics API에서이 메서드를 사용 하 여 지정 된 날짜 범위 및 기타 선택적 필터 중에 앱에 대 한 추가 기능 구독에 대 한 집계 획득 데이터를 가져올 수 있습니다.Use this method in the Microsoft Store analytics API to get aggregate acquisition data for add-on subscriptions for your app during a given date range and other optional filters.

필수 구성 요소Prerequisites

이 방법을 사용 하려면 먼저 다음을 수행 해야 합니다.To use this method, you need to first do the following:

  • 아직 수행 하지 않은 경우 Microsoft Store 분석 API에 대 한 모든 필수 구성 요소 를 완료 합니다.If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • 이 메서드에 대 한 요청 헤더에 사용할 AZURE AD 액세스 토큰을 가져옵니다 .Obtain an Azure AD access token to use in the request header for this method. 액세스 토큰을 얻은 후 만료되기 전에 60분 동안 사용할 수 있습니다.After you obtain an access token, you have 60 minutes to use it before it expires. 토큰이 만료 된 후 새 토큰을 얻을 수 있습니다.After the token expires, you can obtain a new one.

요청Request

요청 구문Request syntax

방법Method 요청 URIRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions

요청 헤더Request header

헤더Header 형식Type DescriptionDescription
권한 부여Authorization 문자열string 필수 사항입니다.Required. Bearer <token> 형식의 Azure AD 액세스 토큰입니다.The Azure AD access token in the form Bearer <token>.

요청 매개 변수Request parameters

매개 변수Parameter TypeType 설명Description 필요한 공간Required
applicationIdapplicationId 문자열string 구독 추가 기능 획득 데이터를 검색 하려는 앱의 저장소 ID 입니다.The Store ID of the app for which you want to retrieve subscription add-on acquisition data. Yes
subscriptionProductIdsubscriptionProductId 문자열string 획득 데이터를 검색 하려는 구독 추가 기능에 대 한 저장소 ID 입니다.The Store ID of the subscription add-on for which you want to retrieve acquisition data. 이 값을 지정 하지 않으면이 메서드는 지정 된 앱에 대 한 모든 구독 추가 기능에 대 한 취득 데이터를 반환 합니다.If you do not specify this value, this method returns acquisition data for all subscription add-ons for the specified app. 아니요No
startDatestartDate datedate 검색할 구독 추가 기능 획득 데이터의 날짜 범위에 있는 시작 날짜입니다.The start date in the date range of subscription add-on acquisition data to retrieve. 기본값은 현재 날짜입니다.The default is the current date. 아니요No
endDateendDate datedate 검색할 구독 추가 기능 획득 데이터의 날짜 범위에 있는 종료 날짜입니다.The end date in the date range of subscription add-on acquisition data to retrieve. 기본값은 현재 날짜입니다.The default is the current date. No
toptop intint 요청에 반환할 데이터 행 수입니다.The number of rows of data to return in the request. 지정 되지 않은 경우 최대값 및 기본값은 100입니다.The maximum value and the default value if not specified is 100. 쿼리에 더 많은 행이 있는 경우 응답 본문에는 다음 데이터 페이지를 요청 하는 데 사용할 수 있는 다음 링크가 포함 됩니다.If there are more rows in the query, the response body includes a next link that you can use to request the next page of data. 아니요No
skipskip intint 쿼리에서 건너뛸 행의 수입니다.The number of rows to skip in the query. 이 매개 변수를 사용 하 여 많은 데이터 집합을 페이징 합니다.Use this parameter to page through large data sets. 예를 들어 top = 100과 skip = 0은 처음 100 행의 데이터를 검색 하 고, top = 100을 검색 하 고, skip = 100은 다음 100 행 데이터를 검색 하는 식입니다.For example, top=100 and skip=0 retrieves the first 100 rows of data, top=100 and skip=100 retrieves the next 100 rows of data, and so on. 아니요No
filterfilter 문자열string 응답 본문을 필터링 하는 하나 이상의 문입니다.One or more statements that filter the response body. 각 문은 eq 또는 ne 연산자를 사용할 수 있으며, 또는 또는를 사용 하 여 문을 조합할 수 있습니다.Each statement can use the eq or ne operators, and statements can be combined using and or or. 필터 문에 다음 문자열을 지정할 수 있습니다 ( 응답 본문의 값에 해당).You can specify the following strings in the filter statements (these correspond to values in the response body):
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • 시장market
  • deviceTypedeviceType

Filter = date eq ' 2017-07-08 '의 예제 필터 매개 변수는 다음과 같습니다.Here is an example filter parameter: filter=date eq '2017-07-08'.

아니요No
aggregationLevelaggregationLevel 문자열string 집계 데이터를 검색 하는 시간 범위를 지정 합니다.Specifies the time range for which to retrieve aggregate data. , 또는 문자열 중 하나일 수 있습니다.Can be one of the following strings: day, week, or month. 지정 하지 않으면 기본값은 day입니다.If unspecified, the default is day. 아니요No
orderbyorderby 문자열string 각 구독 추가 기능 획득에 대 한 결과 데이터 값을 정렬 하는 문입니다.A statement that orders the result data values for each subscription add-on acquisition. 구문은 orderby = field [order], field [order],...입니다. Field 매개 변수는 다음 문자열 중 하나일 수 있습니다.The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following strings:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • 시장market
  • deviceTypedeviceType

Order 매개 변수는 선택 사항이 며 asc 또는 desc 로 각 필드에 대해 오름차순 또는 내림차순을 지정할 수 있습니다.The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. 기본값은 asc입니다.The default is asc.

다음은 orderby 문자열의 예입니다. orderby = date, marketHere is an example orderby string: orderby=date,market

아니요No
groupbygroupby 문자열string 지정 된 필드에만 데이터 집계를 적용 하는 문입니다.A statement that applies data aggregation only to the specified fields. 다음 필드를 지정할 수 있습니다.You can specify the following fields:
  • datedate
  • subscriptionProductNamesubscriptionProductName
  • applicationNameapplicationName
  • skuIdskuId
  • 시장market
  • deviceTypedeviceType

Groupby 매개 변수는 aggregationLevel 매개 변수와 함께 사용할 수 있습니다.The groupby parameter can be used with the aggregationLevel parameter. 예: groupby = market & aggregationLevel = weekFor example: groupby=market&aggregationLevel=week

아니요No

요청 예제Request example

다음 예에서는 구독 추가 기능 획득 데이터를 가져오는 방법을 보여 줍니다.The following examples demonstrates how to get subscription add-on acquisition data. ApplicationId 값을 앱의 적절 한 상점 ID로 바꿉니다.Replace the applicationId value with the appropriate Store ID for your app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=2017-07-07&endDate=2017-07-08 HTTP/1.1
Authorization: Bearer <your access token>

응답Response

응답 본문Response body

Value 형식Type DescriptionDescription
Value arrayarray 집계 구독 추가 기능 획득 데이터를 포함 하는 개체의 배열입니다.An array of objects that contain aggregate subscription add-on acquisition data. 각 개체의 데이터에 대 한 자세한 내용은 아래의 구독 획득 값 섹션을 참조 하십시오.For more information about the data in each object, see the subscription acquisition values section below.
@nextLink 문자열string 추가 데이터 페이지가 있는 경우이 문자열에는 다음 데이터 페이지를 요청 하는 데 사용할 수 있는 URI가 포함 됩니다.If there are additional pages of data, this string contains a URI that you can use to request the next page of data. 예를 들어 요청의 top 매개 변수가 100로 설정 되어 있지만 쿼리에 대 한 구독 추가 기능 획득 데이터의 행이 100 개를 초과 하는 경우이 값이 반환 됩니다.For example, this value is returned if the top parameter of the request is set to 100 but there are more than 100 rows of subscription add-on acquisition data for the query.
TotalCountTotalCount intint 쿼리의 데이터 결과에 있는 총 행 수입니다.The total number of rows in the data result for the query.

구독 획득 값Subscription acquisition values

배열의 요소에는 다음 값이 포함 됩니다.Elements in the Value array contain the following values.

Value 형식Type 설명Description
datedate 문자열string 취득 데이터의 날짜 범위에 있는 첫 번째 날짜입니다.The first date in the date range for the acquisition data. 요청에서 하루를 지정 하는 경우이 값은 해당 날짜입니다.If the request specified a single day, this value is that date. 요청에서 주, 월 또는 다른 날짜 범위를 지정 하는 경우이 값은 해당 날짜 범위의 첫 번째 날짜입니다.If the request specified a week, month, or other date range, this value is the first date in that date range.
subscriptionProductIdsubscriptionProductId 문자열string 획득 데이터를 검색 하는 구독 추가 기능에 대 한 저장소 ID 입니다.The Store ID of the subscription add-on for which you are retrieving acquisition data.
subscriptionProductNamesubscriptionProductName 문자열string 구독 추가 기능에 대 한 표시 이름입니다.The display name of the subscription add-on.
applicationIdapplicationId 문자열string 구독 추가 기능 획득 데이터를 검색 하는 앱의 저장소 ID 입니다.The Store ID of the app for which you are retrieving subscription add-on acquisition data.
applicationNameapplicationName 문자열string 응용 프로그램의 표시 이름입니다.The display name of the app.
skuIdskuId 문자열string 획득 데이터를 검색 하는 구독 추가 기능 SKU 의 ID입니다.The ID of the SKU of the subscription add-on for which you are retrieving acquisition data.
deviceTypedeviceType 문자열string 가져오기를 완료 한 장치 유형을 지정 하는 다음 문자열 중 하나입니다.One of the following strings that specifies the type of device that completed the acquisition:
  • 컴퓨터PC
  • 내선Phone
  • 콘솔-Xbox OneConsole-Xbox One
  • 콘솔-Xbox 시리즈 XConsole-Xbox Series X
  • IoTIoT
  • HolographicHolographic
  • 알 수 없음Unknown
marketmarket 문자열string 획득이 발생 한 시장의 ISO 3166 국가 코드입니다.The ISO 3166 country code of the market where the acquisition occurred.
currencyCodecurrencyCode 문자열string 세금 전 총 판매량에 대 한 ISO 4217 형식의 통화 코드입니다.The currency code in ISO 4217 format for gross sales before taxes.
grossSalesBeforeTaxgrossSalesBeforeTax integerinteger CurrencyCode 값으로 지정 된 현지 통화의 총 판매량입니다.The gross sales in the local currency specified by the currencyCode value.
totalActiveCounttotalActiveCount integerinteger 지정 된 기간 동안의 총 활성 구독 수입니다.The number of total active subscriptions during the specified time period. 이 값은 goodStandingActiveCount, pendingGraceActiveCount, graceActiveCountlockedActiveCount 값의 합계와 같습니다.This is equivalent to the sum of the goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount, and lockedActiveCount values.
totalChurnCounttotalChurnCount integerinteger 지정 된 기간 동안 비활성화 된 총 구독 수입니다.The total count of subscriptions that were deactivated during the specified time period. 이 값은 billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCountotherChurnCount 값의 합계와 같습니다.This is equivalent to the sum of the billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount, and otherChurnCount values.
newCountnewCount integerinteger 지정 된 기간 동안 평가판을 포함 하 여 새 구독을 획득 한 횟수입니다.The number of new subscription acquisitions during the specified time period, including trials.
renewCountrenewCount integerinteger 지정 된 기간 동안 사용자가 시작한 갱신 및 자동 갱신을 포함 하 여 구독을 갱신 하는 횟수입니다.The number of subscription renewals during the specified time period, including user-initiated renewals and automatic renewals.
goodStandingActiveCountgoodStandingActiveCount integerinteger 지정 된 기간 동안 활성 상태이 고 만료 날짜가 >인 구독의 수는 쿼리에 대 한 endDate 값입니다.The number of subscriptions that were active during the specified time period and where the expiration date is >= the endDate value for the query.
pendingGraceActiveCountpendingGraceActiveCount integerinteger 지정 된 기간 동안 활성 상태 이지만 청구 오류가 발생 한 구독 수와 구독 만료 날짜가 >= 쿼리의 endDate 값입니다.The number of subscriptions that were active during the specified time period but had a billing failure, and where the subscription expiration date is >= the endDate value for the query.
graceActiveCountgraceActiveCount integerinteger 지정 된 기간 동안 활성 상태 이지만 대금 청구 오류가 발생 하 고 있는 구독 수입니다.The number of subscriptions that were active during the specified time period but had a billing failure, and where:
  • 구독 만료 날짜가 쿼리에 대 한 endDate 값 < 됩니다.The subscription expiration date is < the endDate value for the query.
  • 유예 기간의 끝은 endDate 값 >=입니다.The end of the grace period is >= the endDate value.
lockedActiveCountlockedActiveCount integerinteger Dunning 에 있었던 구독 수 (즉, 구독 만료가 임박 하 고 Microsoft는 지정 된 기간 동안 구독을 자동으로 갱신 하는 자금을 확보 하려고 시도 하 고 있습니다.)The number of subscriptions that were in dunning (that is, the subscription is nearing expiration and Microsoft is trying to acquire funds to automatically renew the subscription) during the specified time period, and where:
  • 구독 만료 날짜가 쿼리에 대 한 endDate 값 < 됩니다.The subscription expiration date is < the endDate value for the query.
  • 유예 기간의 끝은 endDate 값 <=입니다.The end of the grace period is <= the endDate value.
billingChurnCountbillingChurnCount integerinteger 청구 요금을 처리 하는 데 실패 하 고 구독이 이전에 dunning 된 위치에서 지정 된 기간 동안 비활성화 된 구독 수입니다.The number of subscriptions that were deactivated during the specified time period because of a failure to process a billing charge and where the subscriptions were previously in dunning.
nonRenewalChurnCountnonRenewalChurnCount integerinteger 갱신 되지 않았기 때문에 지정 된 기간 동안 비활성화 된 구독 수입니다.The number of subscriptions that were deactivated during the specified time period because they were not renewed.
refundChurnCountrefundChurnCount integerinteger 지정 된 기간에 환불 된 구독 수입니다.The number of subscriptions that were deactivated during the specified time period because they were refunded.
chargebackChurnCountchargebackChurnCount integerinteger 비용 정산 때문에 지정 된 기간 동안 비활성화 된 구독 수입니다.The number of subscriptions that were deactivated during the specified time period because of a chargeback.
earlyChurnCountearlyChurnCount integerinteger 지정 된 기간 동안 비활성화 된 구독 중 적절 한 시간 동안 비활성화 된 구독 수입니다.The number of subscriptions that were deactivated during the specified time period while they were in good standing.
otherChurnCountotherChurnCount integerinteger 지정 된 기간 동안 다른 이유로 비활성화 된 구독 수입니다.The number of subscriptions that were deactivated during the specified time period for other reasons.

응답 예제Response example

다음 예제에서는이 요청에 대 한 예제 JSON 응답 본문을 보여 줍니다.The following example demonstrates an example JSON response body for this request.

{
  "Value": [
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9KDLGHH6R365",
      "subscriptionProductName": "Contoso App Subscription with One Month Free Trial",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "Unknown",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    },
    {
      "date": "2017-07-08",
      "subscriptionProductId": "9JJFDHG4R478",
      "subscriptionProductName": "Contoso App Monthly Subscription",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso App",
      "skuId": "0020",
      "market": "US",
      "deviceType": "PC",
      "currencyCode": "USD",
      "grossSalesBeforeTax": 0.0,
      "totalActiveCount": 1,
      "totalChurnCount": 0,
      "newCount": 0,
      "renewCount": 0,
      "goodStandingActiveCount": 1,
      "pendingGraceActiveCount": 0,
      "graceActiveCount": 0,
      "lockedActiveCount": 0,
      "billingChurnCount": 0,
      "nonRenewalChurnCount": 0,
      "refundChurnCount": 0,
      "chargebackChurnCount": 0,
      "earlyChurnCount": 0,
      "otherChurnCount": 0
    }
  ],
  "@nextLink": null,
  "TotalCount": 2
}