Obter aquisições de aplicativo
Use esse método na API de análise da Microsoft Store para obter dados de aquisição agregados em formato JSON para um aplicativo durante um determinado intervalo de datas e outros filtros opcionais. Essas informações também estão disponíveis no Relatório de aquisições na Central de Parceiros.
Pré-requisitos
Para usar este método, primeiro você precisa fazer o seguinte:
- Se você ainda não fez isso, conclua todos os pré-requisitos da API de análise da Microsoft Store.
- Obtenha um token de acesso do Azure AD a ser usado no cabeçalho da solicitação para esse método. Após obter um token de acesso, você tem 60 minutos para usá-lo antes dele expirar. Depois que o token expirar, você poderá obter um novo.
Solicitar
Sintaxe da solicitação
| Método | URI da solicitação |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/appacquisitions |
Cabeçalho da solicitação
| Cabeçalho | Tipo | Descrição |
|---|---|---|
| Autorização | string | Obrigatório. O token de acesso do Azure AD no Token<de portador> do formulário. |
Parâmetros da solicitação
| Parâmetro | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| applicationId | string | A ID da Store do aplicativo cujos dados de aquisição você deseja recuperar. | Sim |
| startDate | date | A data de início no intervalo de datas dos dados de aquisição a serem recuperados. O padrão é a data atual. | Não |
| endDate | date | A data de término no intervalo de datas dos dados de aquisição a serem recuperados. O padrão é a data atual. | Não |
| top | int | O número de linhas de dados a serem retornadas na solicitação. O valor máximo e padrão, se não for especificado, será 10.000. Se houver mais linhas na consulta, o corpo da resposta incluirá um proximo link que você poderá usar para solicitar a próxima página de dados. | Não |
| skip | int | O número de linhas a serem ignoradas na consulta. Use esse parâmetro para percorrer grandes conjuntos de dados. Por exemplo, top=10000 e skip=0 recupera as primeiras 10.000 mil linhas de dados, top=10000 e skip=10000 recupera as próximas dez mil linhas de dados, e assim por diante. | Não |
| filtro | string | Uma ou mais instruções que filtram as linhas na resposta. Cada instrução contém um nome de campo do corpo da resposta e um valor associados aos operadores eq ou ne, e as instruções podem ser combinadas usando and ou or. Os valores de sequência devem estar entre aspas simples no parâmetro filter. Por exemplo, filter=market eq 'US' and gender eq 'm'. Você pode especificar os seguintes campos no corpo da resposta:
|
Não |
| aggregationLevel | string | Especifica o intervalo de tempo cujos dados agregados serão recuperados. Pode ser uma das seguintes sequências: dia, semana ou mês. Se não for especificado, o padrão será dia. | Não |
| orderby | string | Uma instrução que ordena os valores dos dados de resultado para cada aquisição. A sintaxe é orderby=field [order],field [order],.... O parâmetro field pode ser uma das seguintes sequências:
O parâmetro order é opcional e pode ser asc ou desc para especificar ordem ascendente ou descendente para cada campo. O padrão é asc. Este é um exemplo de sequência orderby: orderby=date,market |
Não |
| groupby | string | Uma instrução que aplica agregação de dados somente aos campos especificados. Você pode especificar os seguintes campos:
As linhas de dados retornadas conterão os campos especificados no parâmetro groupby, bem como:
O parâmetro groupby pode ser usado com o parâmetro aggregationLevel. Por exemplo: &groupby=ageGroup,market&aggregationLevel=week |
Não |
Exemplo de solicitação
O exemplo a seguir demonstra várias solicitações para a obtenção de dados de aquisição de aplicativos. Substitua o valor applicationId pela ID da Store para seu aplicativo.
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/appacquisitions?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/appacquisitions?applicationId=9NBLGGGZ5QDR&startDate=8/1/2015&endDate=8/31/2015&skip=0&filter=market eq 'US' and gender eq 'm' HTTP/1.1
Authorization: Bearer <your access token>
Resposta
Corpo da resposta
| Valor | Type | Descrição |
|---|---|---|
| Valor | matriz | Uma matriz de objetos que contêm dados agregados de aquisição para o aplicativo. Para obter mais informações sobre os dados em cada objeto, consulte a seção Valores de aquisição abaixo. |
| @nextLink | string | Se houver páginas adicionais de dados, essa sequência conterá um URI que você poderá usar para solicitar a próxima página de dados. Por exemplo, esse valor será retornado se o parâmetro top da solicitação estiver definido como 10000, mas se existirem mais de 10000 linhas de dados de aquisição para a consulta. |
| TotalCount | int | O número total de linhas no resultado de dados da consulta. |
Valores de aquisição
Os elementos na matriz Value contêm os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| date | string | A primeira data no intervalo de datas para os dados de aquisição. Se a solicitação tiver especificado um único dia, esse valor será essa data. Se a solicitação tiver especificado uma semana, um mês ou outro intervalo de datas, esse valor será a primeira data nesse intervalo de datas. |
| applicationId | string | O ID da Store do aplicativo para o qual você está recuperando os dados de aquisição. |
| applicationName | string | O nome de exibição do aplicativo. |
| deviceType | string | Uma das seguintes sequências que especifica o tipo de dispositivo em que a aquisição ocorreu:
|
| orderName | string | O nome do pedido. |
| storeClient | string | Uma das seguintes sequências que indica a versão da Store na qual a aquisição ocorreu:
|
| osVersion | string | Uma das seguintes sequências que especifica a versão do SO em que a aquisição ocorreu:
|
| market | string | O código de país ISO 3166 do mercado no qual a aquisição ocorreu. |
| gender | string | Uma das seguintes sequências que especifica o gênero do usuário que fez a aquisição:
|
| ageGroup | string | Uma das seguintes sequências que especifica o grupo etário do usuário que fez a aquisição:
|
| acquisitionType | string | Uma das seguintes sequências que indica o tipo de aquisição:
|
| acquisitionQuantity | número | O número de aquisições que ocorreram durante o nível de agregação especificado. |
Exemplo de solicitação e resposta
Os snippets de código a seguir demonstram alguns exemplos de solicitações e o corpo da resposta JSON para estas solicitações.
Solicitação de Exemplo
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/appacquisitions?applicationId=9NBLGGGZ5QDR HTTP/1.1
Authorization: Bearer <your access token>
Resposta de exemplo
{
"Value": [
{
"applicationId": "9NBLGGGZ5QDR",
"date": "2022-07-29",
"acquisitionQuantity": 7,
"purchasePriceUSDAmount": 0.0,
"purchasePriceLocalAmount": 0.0,
"purchaseTaxUSDAmount": 0.0,
"purchaseTaxLocalAmount": 0.0
},
],
"TotalCount": 1,
"DataFreshnessTimestamp": "2022-07-29T08:42:00"
}
Solicitação de Exemplo
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/appacquisitions?applicationId=9NBLGGGZ5QDR&startDate=8/1/2021&endDate=12/21/2021&skip=0&filter=market&groupby=date,applicationName,acquisitionType,ageGroup,storeClient,gender,market,osVersion,deviceType HTTP/1.1
Authorization: Bearer <your access token>
Resposta de exemplo
{
"Value": [
{
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"acquisitionType": "Free",
"storeClient": "Microsoft Store (client)",
"gender": "f",
"market": "TW",
"osVersion": "Windows 10",
"deviceType": "PC",
"date": "2021-08-01",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 0.0,
"purchasePriceLocalAmount": 0.0,
"purchaseTaxUSDAmount": 0.0,
"purchaseTaxLocalAmount": 0.0
},
{
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Contoso Demo",
"acquisitionType": "Free",
"storeClient": "Microsoft Store (client)",
"gender": "Unknown",
"market": "BR",
"osVersion": "Windows 10",
"deviceType": "PC",
"date": "2021-08-01",
"acquisitionQuantity": 1,
"purchasePriceUSDAmount": 0.0,
"purchasePriceLocalAmount": 0.0,
"purchaseTaxUSDAmount": 0.0,
"purchaseTaxLocalAmount": 0.0
},
],
"TotalCount": 2,
"DataFreshnessTimestamp": "2022-07-29T08:42:00"
}