Obter aquisições de complemento

Artigo
01/18/2024

Use esse método na API de análise da Microsoft Store para obter dados de aquisição agregados para complementos para seu aplicativo no formato JSON durante um determinado intervalo de datas e para outros filtros opcionais. Essas informações também estão disponíveis no relatório de Aquisições de complementos 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/inappacquisitions`

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

O parâmetro applicationId ou inAppProductId é obrigatório. Para recuperar dados de aquisição de todos os complementos registrados no aplicativo, especifique o parâmetro applicationId. Para recuperar dados de aquisição para um único complemento, especifique o parâmetro inAppProductId. Se você especificar ambos, o parâmetro applicationId será ignorado.

Parâmetro	Tipo	Descrição	Obrigatório
applicationId	string	A ID da Store do aplicativo cujos dados de aquisição de complementos você deseja recuperar.	Sim
inAppProductId	string	O ID da Store do complemento para o qual você deseja recuperar os dados de aquisição.	Sim
startDate	date	A data de início no intervalo de datas dos dados de aquisição do complemento 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 do complemento 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. Para obter mais informações, consulte a seção sobre campos de filtro abaixo.	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 de complemento. A sintaxe é orderby=field [order],field [order],.... O parâmetro field pode ser uma das seguintes sequências: date acquisitionType ageGroup storeClient gender market osVersion deviceType orderName 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: date applicationName inAppProductName acquisitionType ageGroup storeClient gender market osVersion deviceType orderName As linhas de dados retornadas conterão os campos especificados no parâmetro groupby, bem como: date applicationId inAppProductId acquisitionQuantity O parâmetro groupby pode ser usado com o parâmetro aggregationLevel. Por exemplo: &groupby=ageGroup,market&aggregationLevel=week	Não

Filtrar campos

O parâmetro filter da solicitação contém uma ou mais instruções que filtram as linhas na resposta. Cada instrução contém um campo e um valor associados aos operadores eq ou ne e as instruções podem ser combinadas usando and ou or. Veja a seguir alguns exemplos de parâmetros filter:

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’)

Para obter uma lista dos campos com suporte, consulte a tabela a seguir. Os valores de sequência devem estar entre aspas simples no parâmetro filter.

Campos	Descrição
acquisitionType	Uma das cadeias de caracteres a seguir: gratuito avaliação pago código de promoção IAP
ageGroup	Uma das cadeias de caracteres a seguir: menos de 13 13-17 18-24 25-34 35-44 44-55 mais de 55 Desconhecido
storeClient	Uma das cadeias de caracteres a seguir: Loja do Windows Phone (cliente) Microsoft Store (cliente) Microsoft Store (Web) Aquisição de volume por organizações Outras
gender	Uma das cadeias de caracteres a seguir: m f Desconhecido
market	Uma sequência que contém o código do país ISO 3166 do mercado no qual a aquisição ocorreu.
osVersion	Uma das cadeias de caracteres a seguir: Windows Phone 7.5 Windows Phone 8 Windows Phone 8.1 Windows Phone 10 Windows 8 Windows 8.1 Windows 10 Windows 11 Desconhecido
deviceType	Uma das cadeias de caracteres a seguir: Computador Telefone Console-Xbox One Console-Xbox Series X IoT Holográfico Desconhecido
orderName	Uma sequência que especifica o nome do pedido do código de promoção que foi usado para adquirir o complemento (isso só se aplica se o usuário adquiriu o complemento ao resgatar um código de promoção).

Exemplo de solicitação

Os exemplos a seguir demonstram várias solicitações para obter dados de aquisição de complemento. Substitua os valores inAppProductId e applicationId com o ID da Store mais apropriado para seu complemento ou aplicativo.

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>

Resposta

Corpo da resposta

Valor	Type	Descrição
Valor	matriz	Uma matriz de objetos que contêm dados agregados de aquisição de complemento. Para obter mais informações sobre os dados em cada objeto, consulte a seção valores de aquisição de complementos 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 dez mil, mas houver mais de dez mil linhas de dados de aquisição de complementos para a consulta.
TotalCount	int	O número total de linhas no resultado de dados da consulta.

Valores de aquisição de complementos

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.
inAppProductId	string	O ID da Store do complemento para o qual você está recuperando os dados de aquisição.
inAppProductName	string	O nome de exibição do complemento. Esse valor será exibido nos dados de resposta somente se o parâmetro aggregationLevel estiver configurado como day, a menos que você especifique o campo inAppProductName no parâmetro groupby.
applicationId	string	A ID da Store do aplicativo cujos dados de aquisição de complementos você deseja recuperar.
applicationName	string	O nome de exibição do aplicativo.
deviceType	string	O tipo de dispositivo que concluiu a aquisição. Para obter uma lista das sequências com suporte, consulte a seção campos de filtro acima.
orderName	string	O nome do pedido.
storeClient	string	A versão da Store em que a aquisição ocorreu. Para obter uma lista das sequências com suporte, consulte a seção campos de filtro acima.
osVersion	string	A versão do sistema operacional em que a aquisição ocorreu. Para obter uma lista das sequências com suporte, consulte a seção campos de filtro acima.
market	string	O código de país ISO 3166 do mercado no qual a aquisição ocorreu.
gender	string	O gênero do usuário que realizou a aquisição. Para obter uma lista das sequências com suporte, consulte a seção campos de filtro acima.
ageGroup	string	A faixa etária do usuário que realizou a aquisição. Para obter uma lista das sequências com suporte, consulte a seção campos de filtro acima.
acquisitionType	string	O tipo de aquisição (gratuita, paga, e assim por diante). Para obter uma lista das sequências com suporte, consulte a seção campos de filtro acima.
acquisitionQuantity	Número inteiro	O número de aquisições ocorridas.

Exemplo de solicitação e resposta

O snippet de código a seguir demonstra um exemplo de solicitação e o corpo da resposta em JSON para essa solicitação.

Solicitação de Exemplo

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

Resposta de exemplo

{
    "Value": [
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Deluxe Collector's Edition",
            "addonProductId": "9NBLGGAAGZDQ",
            "date": "2022-07-29",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 18.12,
            "purchasePriceLocalAmount": 18.12,
            "purchaseTaxUSDAmount": 1.13,
            "purchaseTaxLocalAmount": 1.13
        },
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Episode 4",
            "addonProductId": "9NAAAAAAAAAQ",
            "date": "2017-01-07",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 4.147206,
            "purchasePriceLocalAmount": 3.99,
            "purchaseTaxUSDAmount": 0.686004,
            "purchaseTaxLocalAmount": 0.66
        },
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Deluxe Collector's Edition",
            "addonProductId": "9NALGGGZ5QDQ",
            "date": "2018-04-01",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 1.99,
            "purchasePriceLocalAmount": 1.99,
            "purchaseTaxUSDAmount": 0.0,
            "purchaseTaxLocalAmount": 0.0
        },
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Strategy Guide Episode 4",
            "addonProductId": "9NBLGGGZ5QDQ",
            "date": "2021-11-25",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 1.31902922876179,
            "purchasePriceLocalAmount": 150.0,
            "purchaseTaxUSDAmount": 0.114315866492689,
            "purchaseTaxLocalAmount": 13.0
        },
    ],
    "TotalCount": 4,
    "DataFreshnessTimestamp": "2022-07-29T05:54:00"
}

Compartilhar via

Obter aquisições de complemento

Pré-requisitos

Solicitar

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetros da solicitação

Filtrar campos

Exemplo de solicitação

Resposta

Corpo da resposta

Valores de aquisição de complementos

Exemplo de solicitação e resposta

Solicitação de Exemplo

Resposta de exemplo

Comentários

Recursos adicionais

Compartilhar via

Obter aquisições de complemento

Pré-requisitos

Solicitar

Sintaxe da solicitação

Cabeçalho da solicitação

Parâmetros da solicitação

Filtrar campos

Exemplo de solicitação

Resposta

Corpo da resposta

Valores de aquisição de complementos

Exemplo de solicitação e resposta

Solicitação de Exemplo

Resposta de exemplo

Tópicos relacionados

Comentários

Recursos adicionais