Obter dados de aquisições de complemento para seus jogos e aplicativosGet add-on acquisitions data for your games and apps

Use esse método na API de análise de Microsoft Store para obter dados agregados de aquisição de complemento no formato JSON para aplicativos UWP e Xbox One que foram ingeridos por meio do portal do desenvolvedor do Xbox (XDP) e disponíveis no painel do centro de parceiros do XDP Analytics.Use this method in the Microsoft Store analytics API to get aggregate add-on acquisition data in JSON format for UWP apps and Xbox One games that were ingested through the Xbox Developer Portal (XDP) and available in the XDP Analytics Partner Center dashboard.

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.

Observação

Esta API não fornece dados de agregação diária antes de 1º de outubro de 2016.This API does not provide daily aggregate data before Oct 1st 2016.

SolicitaçãoRequest

Sintaxe da solicitaçãoRequest syntax

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

Cabeçalho da solicitaçãoRequest header

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

Parâmetros da solicitaçãoRequest parameters

O parâmetro ApplicationId ou addonProductId é necessário.The applicationId or addonProductId 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 para um único complemento, especifique o parâmetro addonProductId .To retrieve acquisition data for a single add-on, specify the addonProductId 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 ProductID do jogo do Xbox One para o qual você está recuperando dados de aquisição.The productId of the Xbox One game for which you are retrieving acquisition data. Para obter o ProductID do seu jogo, navegue até o jogo no programa XDP Analytics e recupere o ProductID da URL.To get the productId of your game, navigate to your game in the XDP Analytics Program and retrieve the productId from the URL. Como alternativa, se você baixar os dados de aquisições do relatório de análise do Partner Center, o ProductID será incluído no arquivo. TSV.Alternatively, if you download your acquisitions data from the Partner Center analytics report, the productId is included in the .tsv file. SimYes
addonProductIdaddonProductId stringstring A ProductID do complemento para o qual você deseja recuperar os dados de aquisição.The productId 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. Cada instrução contém um nome de campo do corpo de resposta 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 name from the response body and value that are associated with the eq or ne operators, and statements can be combined using and or or. 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. Por exemplo, filter=market eq 'US' and gender eq 'm'.For example, filter=market eq 'US' and gender eq 'm'.
Você pode especificar os campos a seguir do corpo da resposta:You can specify the following fields from the response body:
  • acquisitionTypeacquisitionType
  • idadeage
  • storeClientstoreClient
  • gendergender
  • anunciarmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • sandboxIdsandboxId
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 [pedido], campo [ordem],... O parâmetro Field pode ser uma das seguintes cadeias de caracteres:The syntax is orderby=field [order],field [order],... The field parameter can be one of the following strings:
  • datedate
  • acquisitionTypeacquisitionType
  • idadeage
  • 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
  • addonProductNameaddonProductName
  • acquisitionTypeacquisitionType
  • idadeage
  • storeClientstoreClient
  • gendergender
  • anunciarmarket
  • osVersionosVersion
  • deviceTypedeviceType
  • paymentInstrumentTypepaymentInstrumentType
  • sandboxIdsandboxId
  • xboxTitleIdHexxboxTitleIdHex
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
  • addonProductIdaddonProductId
  • 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 = age, market&aggregationLevel = semanaFor example: &groupby=age,market&aggregationLevel=week
NãoNo

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 addonProductId e ApplicationId pela ID de armazenamento apropriada para seu complemento ou aplicativo.Replace the addonProductId and applicationId values with the appropriate Store ID for your add-on or app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&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&skip=0&filter=market eq 'GB' and gender eq 'm' 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.
addonProductIdaddonProductId stringstring A ProductID do complemento para o qual você está recuperando dados de aquisição.The productId of the add-on for which you are retrieving acquisition data.
addonProductNameaddonProductName stringstring O nome de exibição do complemento.The display name of the add-on. Esse valor só aparecerá nos dados de resposta se o parâmetro aggregationLevel for definido como Day, a menos que você especifique o campo addonProductName no parâmetro GroupBy .This value only appears in the response data if the aggregationLevel parameter is set to day, unless you specify the addonProductName field in the groupby parameter.
applicationIdapplicationId stringstring A ProductID do aplicativo para o qual você deseja recuperar dados de aquisição de complemento.The productId of the app for which you want to retrieve add-on acquisition data.
applicationNameapplicationName stringstring O nome de exibição do jogo.The display name of the game.
deviceTypedeviceType stringstring Uma das sequências a seguir que especifica o tipo de dispositivo que concluiu a aquisição:One of the following strings that specifies the type of device that completed the acquisition:
  • PROTECÇÃO"PC"
  • Telemóvel"Phone"
  • "Console-Xbox One""Console-Xbox One"
  • "Console-Xbox Series X""Console-Xbox Series X"
  • IOT"IoT"
  • Servidor"Server"
  • PC"Tablet"
  • Holographic"Holographic"
  • Conhecidos"Unknown"
storeClientstoreClient stringstring Uma das sequências a seguir que indica a versão da Store onde ocorreu a aquisição:One of the following strings that indicates the version of the Store where the acquisition occurred:
  • "Armazenamento de Windows Phone (cliente)""Windows Phone Store (client)"
  • "Microsoft Store (cliente)" (ou "Windows Store (cliente)" se estiver consultando dados antes de 23 de março de 2018)"Microsoft Store (client)" (or "Windows Store (client)" if querying for data before March 23, 2018)
  • "Microsoft Store (Web)" (ou "Windows Store (Web)" se estiver consultando dados antes de 23 de março de 2018)"Microsoft Store (web)" (or "Windows Store (web)" if querying for data before March 23, 2018)
  • "Compra de volume por organizações""Volume purchase by organizations"
  • Outros"Other"
osVersionosVersion stringstring A versão do sistema operacional no qual ocorreu a aquisição.The OS version on which the acquisition occurred. Para esse método, esse valor é sempre "Windows 10".For this method, this value is always "Windows 10".
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 Uma das sequências a seguir que especifica o gênero do usuário que fez a aquisição:One of the following strings that specifies the gender of the user who made the acquisition:
  • "m""m"
  • "f""f"
  • Conhecidos"Unknown"
ageage stringstring Uma das sequências a seguir que indica a faixa etária do usuário que fez a aquisição:One of the following strings that indicates the age group of the user who made the acquisition:
  • "menos de 13""less than 13"
  • "13-17""13-17"
  • "18-24""18-24"
  • "25-34""25-34"
  • "35-44""35-44"
  • "44-55""44-55"
  • "maior que 55""greater than 55"
  • Conhecidos"Unknown"
acquisitionTypeacquisitionType stringstring Uma das sequências a seguir que indica o tipo de aquisição:One of the following strings that indicates the type of acquisition:
  • Informações"Free"
  • Avaliação"Trial"
  • Pagou"Paid"
  • "Código promocional""Promotional code"
  • IAP da"Iap"
  • "Assinatura IAP da""Subscription Iap"
  • "Público privado""Private Audience"
  • "Pré-pedido""Pre Order"
  • "Passagem de jogos do Xbox" (ou "jogo pass" se estiver consultando dados antes de 23 de março de 2018)"Xbox Game Pass" (or "Game Pass" if querying for data before March 23, 2018)
  • Disco"Disk"
  • "Código pré-pago""Prepaid Code"
  • "Pré-encomenda cobrada""Charged Pre Order"
  • "Pré-pedido cancelado""Cancelled Pre Order"
  • "Pré-pedido com falha""Failed Pre Order"
acquisitionQuantityacquisitionQuantity inteirointeger O número de aquisições que ocorreram.The number of acquisitions that occurred.
inAppProductIdinAppProductId stringstring ID do produto no qual este complemento é usado.Product ID of the product where this add-on is used.
inAppProductNameinAppProductName stringstring Nome do produto no qual este complemento é usado.Product Name of the product where this add-on is used.
paymentInstrumentTypepaymentInstrumentType stringstring Tipo de instrumento de pagamento usado para a aquisição.Payment instrument type used for the acquisition.
sandboxIdsandboxId stringstring A ID da área restrita criada para o jogo.The Sandbox ID created for the game. Pode ser o valor de varejo ou uma ID de área restrita privada.This can be the value RETAIL or a private sandbox ID.
xboxTitleIdxboxTitleId stringstring ID do título do Xbox do produto de XDP, se aplicável.Xbox Title ID of the product from XDP, if applicable.
localCurrencyCodelocalCurrencyCode stringstring Código de moeda local com base no país da conta do Partner Center.Local Currency code based on the country of the Partner Center account.
xboxProductIdxboxProductId stringstring ID de produto do Xbox do produto de XDP, se aplicável.Xbox Product ID of the product from XDP, if applicable.
availabilityIdavailabilityId stringstring ID de disponibilidade do produto de XDP, se aplicável.Availability ID of the product from XDP, if applicable.
skuIdskuId stringstring ID do SKU do produto de XDP, se aplicável.SKU ID of the product from XDP, if applicable.
skuDisplayNameskuDisplayName stringstring Nome de exibição do SKU do produto de XDP, se aplicável.SKU Display Name of the product from XDP, if applicable.
xboxParentProductIdxboxParentProductId stringstring ID do produto pai do Xbox do produto de XDP, se aplicável.Xbox Parent Product ID of the product from XDP, if applicable.
parentProductNameparentProductName stringstring Nome do produto pai do produto de XDP, se aplicável.Parent Product Name of the product from XDP, if applicable.
productTypeNameproductTypeName stringstring Nome do tipo de produto do produto de XDP, se aplicável.Product Type Name of the product from XDP, if applicable.
purchaseTaxTypepurchaseTaxType stringstring Tipo de imposto de compra do produto de XDP, se aplicável.Purchase Tax Type of the product from XDP, if applicable.
purchasePriceUSDAmountpurchasePriceUSDAmount númeronumber O valor pago pelo cliente para o complemento, convertido em USD.The amount paid by the customer for the add-on, converted to USD.
purchasePriceLocalAmountpurchasePriceLocalAmount númeronumber O valor do imposto aplicado ao complemento.The tax amount applied to the add-on.
purchaseTaxUSDAmountpurchaseTaxUSDAmount númeronumber O valor do imposto aplicado ao complemento, convertido em USD.The tax amount applied to the add-on, converted to USD.
purchaseTaxLocalAmountpurchaseTaxLocalAmount númeronumber Valor local do imposto de compra do produto de XDP, se aplicável.Purchase Tax Local Amount of the product from XDP, if applicable.

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": [ 
    { 
            "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 
}