Obter aquisições de complementoGet add-on acquisitions

Use este método na API de análise da Microsoft Store para obter dados agregados de aquisição para complementos para seu app em formato JSON durante um determinado intervalo de datas e outros filtros opcionais.Use this method in the Microsoft Store analytics API to get aggregate acquisition data for add-ons for your app in JSON format during a given date range and other optional filters. Essas informações também estão disponíveis no relatório de aquisições de Complementos no Partner Center.This information is also available in the Add-on acquisitions report in Partner Center.

Pré-requisitosPrerequisites

Para usar este método, primeiro você precisa do seguinte:To use this method, you need to first do the following:

  • Se você não tiver feito isso, conclua todos os pré-requisitos para a API de análise da Microsoft Store.If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • Obtenha um token de acesso do Azure AD a ser usado no cabeçalho da solicitação para este método.Obtain an Azure AD access token to use in the request header for this method. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar.After you obtain an access token, you have 60 minutes to use it before it expires. Depois que o token expirar, você poderá obter um novo.After the token expires, you can obtain a new one.

SolicitaçãoRequest

Sintaxe da solicitaçãoRequest syntax

MétodoMethod URI da solicitaçãoRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions

Cabeçalho da solicitaçãoRequest header

CabeçalhoHeader TipoType DescriçãoDescription
AutorizaçãoAuthorization stringstring Obrigatórios.Required. O token de acesso do Azure AD no formulário Bearer <token>.The Azure AD access token in the form Bearer <token>.

Parâmetros da solicitaçãoRequest parameters

O parâmetro applicationId ou inAppProductId é obrigatório.The applicationId or inAppProductId parameter is required. Para recuperar dados de aquisição para todos os complementos registrados no aplicativo, especifique o parâmetro applicationId.To retrieve acquisition data for all add-ons registered to the app, specify the applicationId parameter. Para recuperar dados de aquisição de um único complemento, especifique o parâmetro inAppProductId.To retrieve acquisition data for a single add-on, specify the inAppProductId parameter. Se você especificar ambos, o parâmetro applicationId será ignorado.If you specify both, the applicationId parameter is ignored.

ParâmetroParameter TypeType DescriçãoDescription NecessáriaRequired
applicationIdapplicationId stringstring A ID da loja do aplicativo para o qual você deseja recuperar dados de aquisição de complemento.The Store ID of the app for which you want to retrieve add-on acquisition data. SimYes
inAppProductIdinAppProductId stringstring A ID da loja do complemento para o qual você deseja recuperar os dados de aquisição.The Store ID of the add-on for which you want to retrieve acquisition data. SimYes
startDatestartDate datedate A data de início no intervalo de datas de dados de aquisição de complemento a serem recuperados.The start date in the date range of add-on acquisition data to retrieve. O padrão é a data atual.The default is the current date. NãoNo
endDateendDate datedate A data final no intervalo de datas de dados de aquisição de complemento a serem recuperados.The end date in the date range of add-on acquisition data to retrieve. O padrão é a data atual.The default is the current date. NãoNo
toptop INTint O número de linhas de dados a serem retornadas na solicitação.The number of rows of data to return in the request. O valor máximo e o valor padrão; se não forem especificados, será 10.000.The maximum value and the default value if not specified is 10000. Se houver mais linhas na consulta, o corpo da resposta incluirá um link que você poderá usar para solicitar a próxima página de dados.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. NãoNo
skipskip INTint O número de linhas a serem ignoradas na consulta.The number of rows to skip in the query. Use este parâmetro para percorrer grandes conjuntos de dados.Use this parameter to page through large data sets. Por exemplo, top=10000 e skip=0 recuperam as primeiras 10.000 linhas de dados, top=10000 e skip=10000 recuperam as próximas 10.000 linhas de dados e assim por diante.For example, top=10000 and skip=0 retrieves the first 10000 rows of data, top=10000 and skip=10000 retrieves the next 10000 rows of data, and so on. NãoNo
filtrofilter stringstring Uma ou mais instruções que filtram as linhas na resposta.One or more statements that filter the rows in the response. Para saber mais, consulte a seção campos de filtro a seguir.For more information, see the filter fields section below. NãoNo
aggregationLevelaggregationLevel stringstring Especifica o intervalo de tempo para o qual recuperar dados agregados.Specifies the time range for which to retrieve aggregate data. Pode ser uma das seguintes cadeias de caracteres: day, week ou month.Can be one of the following strings: day, week, or month. Se não for especificado, o padrão será day.If unspecified, the default is day. NãoNo
orderbyorderby stringstring Uma instrução que classifica os valores de dados resultantes de cada aquisição de complemento.A statement that orders the result data values for each add-on acquisition. A sintaxe é orderby=field [order],field [order],.... O parâmetro field pode ser uma das seguintes sequências:The syntax is orderby=field [order],field [order],.... The field parameter can be one of the following strings:
  • datedate
  • acquisitionTypeacquisitionType
  • ageGroupageGroup
  • storeClientstoreClient
  • gendergender
  • anunciarmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • orderNameorderName

O parâmetro order é opcional e pode ser asc ou desc para especificar a ordem crescente ou decrescente de cada campo.The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. O padrão é ASC.The default is asc.

Veja um exemplo de cadeia de caracteres OrderBy : OrderBy = data, mercadoHere is an example orderby string: orderby=date,market

NãoNo
groupbygroupby stringstring Uma instrução que aplica a agregação de dados apenas aos campos especificados.A statement that applies data aggregation only to the specified fields. Você pode especificar os campos a seguir:You can specify the following fields:
  • datedate
  • applicationNameapplicationName
  • inAppProductNameinAppProductName
  • acquisitionTypeacquisitionType
  • ageGroupageGroup
  • storeClientstoreClient
  • gendergender
  • anunciarmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • orderNameorderName

As linhas de dados retornados conterão os campos especificados no parâmetro groupby, bem como o seguinte:The returned data rows will contain the fields specified in the groupby parameter as well as the following:

  • datedate
  • applicationIdapplicationId
  • inAppProductIdinAppProductId
  • acquisitionQuantityacquisitionQuantity

O parâmetro groupby pode ser usado com o parâmetro aggregationLevel.The groupby parameter can be used with the aggregationLevel parameter. Por exemplo: & GroupBy = ageGroup, Market & aggregationLevel = semanaFor example: &groupby=ageGroup,market&aggregationLevel=week

NãoNo

Campos de filtroFilter fields

O parâmetro filter da solicitação contém uma ou mais instruções que filtram as linhas da resposta.The filter parameter of the request contains one or more statements that filter the rows in the response. Cada instrução contém um campo e um valor que estão associados aos operadores eq ou ne, e as instruções podem ser combinadas usando-se and ou or.Each statement contains a field and value that are associated with the eq or ne operators, and statements can be combined using and or or. Estes são alguns exemplos dos parâmetros filter:Here are some example filter parameters:

  • filter=market eq 'US' and gender eq 'm'filter=market eq 'US' and gender eq 'm'
  • filter=(market ne 'US') and (gender ne 'Unknown') and (gender ne 'm') and (market ne 'NO') and (ageGroup ne 'greater than 55' or ageGroup ne ‘less than 13’)filter=(market ne 'US') and (gender ne 'Unknown') and (gender ne 'm') and (market ne 'NO') and (ageGroup ne 'greater than 55' or ageGroup ne ‘less than 13’)

Para obter uma lista dos campos com suporte, consulte a tabela a seguir.For a list of the supported fields, see the following table. Os valores de sequência devem estar entre aspas simples no parâmetro filter.String values must be surrounded by single quotes in the filter parameter.

CamposFields DescriçãoDescription
acquisitionTypeacquisitionType Uma das cadeias de caracteres a seguir:One of the following strings:
  • informaçõesfree
  • avaliaçãotrial
  • pagoupaid
  • promotional codepromotional code
  • iapiap
ageGroupageGroup Uma das cadeias de caracteres a seguir:One of the following strings:
  • less than 13less than 13
  • 13-1713-17
  • 18-2418-24
  • 25-3425-34
  • 35-4435-44
  • 44-5544-55
  • greater than 55greater than 55
  • DesconhecidoUnknown
storeClientstoreClient Uma das cadeias de caracteres a seguir:One of the following strings:
  • Windows Phone Store (cliente)Windows Phone Store (client)
  • Microsoft Store (cliente)Microsoft Store (client)
  • Microsoft Store (Web)Microsoft Store (web)
  • Volume purchase by organizationsVolume purchase by organizations
  • OutrosOther
gendergender Uma das cadeias de caracteres a seguir:One of the following strings:
  • dm
  • fixof
  • DesconhecidoUnknown
marketmarket Uma cadeia de caracteres que contém o código de país ISO 3166 do mercado onde ocorreu a aquisição.A string that contains the ISO 3166 country code of the market where the acquisition occurred.
osVersionosVersion Uma das cadeias de caracteres a seguir:One of the following strings:
  • Windows Phone 7.5Windows Phone 7.5
  • Windows Phone 8Windows Phone 8
  • Windows Phone 8.1Windows Phone 8.1
  • Windows Phone 10Windows Phone 10
  • Windows 8Windows 8
  • Windows 8.1Windows 8.1
  • Windows 10Windows 10
  • DesconhecidoUnknown
deviceTypedeviceType Uma das cadeias de caracteres a seguir:One of the following strings:
  • PROTECÇÃOPC
  • TelemóvelPhone
  • Console-Xbox OneConsole-Xbox One
  • Console-Xbox Series XConsole-Xbox Series X
  • IoTIoT
  • HolographicHolographic
  • DesconhecidoUnknown
orderNameorderName Uma cadeia de caracteres que especifica o nome do pedido do código promocional que foi usado para adquirir o complemento (só se aplicará se o usuário adquiriu o complemento resgatando um código promocional).A string that specifies the name of the order for the promotional code that was used to acquire the add-on (this only applies if the user acquired the add-on by redeeming a promotional code).

Exemplo de solicitaçãoRequest example

Os exemplos a seguir demonstram várias solicitações de obtenção de dados de aquisição do complemento.The following examples demonstrates several requests for getting add-on acquisition data. Substitua os valores de inAppProductId e applicationId pela ID da Store apropriada para seu complemento ou aplicativo.Replace the inAppProductId and applicationId values with the appropriate Store ID for your add-on or app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&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/inappacquisitions?applicationId=9NBLGGGZ5QDR&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/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=7/3/2015&top=100&skip=0&filter=market ne 'US' and gender ne 'Unknown' and gender ne 'm' and market ne 'NO' and ageGroup ne '>55' HTTP/1.1
Authorization: Bearer <your access token>

RespostaResponse

Corpo da respostaResponse body

ValorValue TipoType DescriçãoDescription
ValorValue arrayarray Uma matriz de objetos que contém dados agregados de aquisição de complemento.An array of objects that contain aggregate add-on acquisition data. Para obter mais informações sobre os dados em cada objeto, consulte a seção de valores de aquisição de complemento a seguir.For more information about the data in each object, see the add-on acquisition values section below.
@nextLink stringstring Se houver páginas adicionais de dados, essa cadeia de caracteres conterá um URI que você poderá usar para solicitar a próxima página de dados.If there are additional pages of data, this string contains a URI that you can use to request the next page of data. Por exemplo, esse valor é retornado se o parâmetro top da solicitação estiver definido como 10000, mas houver mais de 10000 linhas de dados de aquisição de complemento para a consulta.For example, this value is returned if the top parameter of the request is set to 10000 but there are more than 10000 rows of add-on acquisition data for the query.
TotalCountTotalCount INTint O número total de linhas no resultado dos dados da consulta.The total number of rows in the data result for the query.

Valores de aquisição de complementoAdd-on acquisition values

Os elementos na matriz Value contêm os valores a seguir.Elements in the Value array contain the following values.

ValorValue TipoType DescriçãoDescription
datedate stringstring A primeira data no intervalo de datas dos dados de aquisição.The first date in the date range for the acquisition data. Se a solicitação tiver especificado um único dia, o valor será essa data.If the request specified a single day, this value is that date. Se a solicitação especificou uma semana, um mês ou outro intervalo de datas, o valor será a primeira data nesse intervalo de datas.If the request specified a week, month, or other date range, this value is the first date in that date range.
inAppProductIdinAppProductId stringstring A ID da Store do complemento do qual você está recuperando dados de aquisição.The Store ID of the add-on for which you are retrieving acquisition data.
inAppProductNameinAppProductName stringstring O nome de exibição do complemento.The display name of the add-on. Este valor só será exibido nos dados de resposta se o parâmetro aggregationLevel for definido como day, a menos que você especifique o campo inAppProductName no parâmetro groupby.This value only appears in the response data if the aggregationLevel parameter is set to day, unless you specify the inAppProductName field in the groupby parameter.
applicationIdapplicationId stringstring A ID da Store do aplicativo para o qual você deseja recuperar dados de aquisição do complemento.The Store ID of the app for which you want to retrieve add-on acquisition data.
applicationNameapplicationName stringstring O nome de exibição do app.The display name of the app.
deviceTypedeviceType stringstring O tipo de dispositivo que concluiu a aquisição.The type of device that completed the acquisition. Para obter uma lista das cadeias de caracteres com suporte, consulte a seção campos de filtro acima.For a list of the supported strings, see the filter fields section above.
orderNameorderName stringstring O nome do pedido.The name of the order.
storeClientstoreClient stringstring A versão da Store onde ocorreu a aquisição.The version of the Store where the acquisition occurred. Para obter uma lista das cadeias de caracteres com suporte, consulte a seção campos de filtro acima.For a list of the supported strings, see the filter fields section above.
osVersionosVersion stringstring A versão do sistema operacional no qual ocorreu a aquisição.The OS version on which the acquisition occurred. Para obter uma lista das cadeias de caracteres com suporte, consulte a seção campos de filtro acima.For a list of the supported strings, see the filter fields section above.
marketmarket stringstring O código de país ISO 3166 do mercado onde ocorreu a aquisição.The ISO 3166 country code of the market where the acquisition occurred.
gendergender stringstring O sexo do usuário que fez a aquisição.The gender of the user who made the acquisition. Para obter uma lista das cadeias de caracteres com suporte, consulte a seção campos de filtro acima.For a list of the supported strings, see the filter fields section above.
ageGroupageGroup stringstring A faixa etária do usuário que fez a aquisição.The age group of the user who made the acquisition. Para obter uma lista das cadeias de caracteres com suporte, consulte a seção campos de filtro acima.For a list of the supported strings, see the filter fields section above.
acquisitionTypeacquisitionType stringstring O tipo de aquisição (grátis, pago e assim por diante).The type of acquisition (free, paid, and so on). Para obter uma lista das cadeias de caracteres com suporte, consulte a seção campos de filtro acima.For a list of the supported strings, see the filter fields section above.
acquisitionQuantityacquisitionQuantity inteirointeger O número de aquisições que ocorreram.The number of acquisitions that occurred.

Exemplo de respostaResponse example

O código a seguir demonstra um exemplo de corpo de resposta JSON para essa solicitação.The following example demonstrates an example JSON response body for this request.

{
  "Value": [
    {
      "date": "2015-01-02",
      "inAppProductId": "9NBLGGH3LHKL",
      "inAppProductName": "Contoso add-on 7",
      "applicationId": "9NBLGGGZ5QDR",
      "applicationName": "Contoso Demo",
      "deviceType": "Phone",
      "orderName": "",
      "storeClient": "Windows Phone Store (client)",
      "osVersion": "Windows Phone 8.1",
      "market": "GB",
      "gender": "m",
      "ageGroup": "50orover",
      "acquisitionType": "iap",
      "acquisitionQuantity": 1
    }
  ],
  "@nextLink": "inappacquisitions?applicationId=9NBLGGGZ5QDR&inAppProductId=&aggregationLevel=day&startDate=2015/01/01&endDate=2016/02/01&top=1&skip=1",
  "TotalCount": 33677
}