Obter dados de desempenho de anúncios
Use esse método na API de análise da Microsoft Store para obter dados de desempenho agregados de anúncios para seus aplicativos durante um determinado intervalo de datas e outros filtros opcionais. Esse método retorna os dados no formato JSON.
Esse método retorna os mesmos dados fornecidos pelo Relatório de desempenho de anúncio 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.
Para obter mais informações, consulte Acessar dados analíticos usando os serviços da Microsoft Store.
Solicitar
Sintaxe da solicitação
| Método | URI da solicitação |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance |
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
Para recuperar dados de desempenho do anúncio para um aplicativo específico, use o parâmetro applicationId. Para recuperar dados de desempenho do anúncio de todos os aplicativos associados à sua conta de desenvolvedor, omita o parâmetro applicationId.
| Parâmetro | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| applicationId | string | A ID da Store do aplicativo cujos dados de desempenho do anúncio você deseja recuperar. | Não |
| startDate | date | A data de início no intervalo de datas dos dados de desempenho do anúncio a serem recuperados, no formato AAAA/MM/DD. O padrão é a data atua menos 30 dias. | Não |
| endDate | date | A data de término no intervalo de datas dos dados de desempenho do anúncio a serem recuperados, no formato AAAA/MM/DD. O padrão é a data atual menos um dia. | 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. 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:
O parâmetro groupby pode ser usado com o parâmetro aggregationLevel. Por exemplo: &groupby=applicationId&aggregationLevel=week |
Não |
Filtrar campos
O parâmetro filter do corpo 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. Este é um exemplo de parâmetro filter:
- filter=market eq 'US' and deviceType eq 'phone'
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.
| Campo | Descrição |
|---|---|
| market | Uma sequência que contém o código de país ISO 3166 do mercado no qual os anúncios foram veiculados. |
| deviceType | Uma das seguintes sequências: PC/Tablet ou Phone. |
| adUnitId | Uma sequência que especifica uma ID de unidade publicitária a ser aplicada ao filtro. |
| pubCenterAppName | Uma sequência que especifica o nome pubCenter para o aplicativo atual a ser aplicado ao filtro. |
| adProvider | Uma sequência que especifica um nome de provedor de anúncios a ser aplicado ao filtro. |
| date | Uma sequência que especifica uma data no formato AAAA/MM/DD a ser aplicada ao filtro. |
Exemplo de solicitação
O exemplo a seguir demonstra várias solicitações para obter dados de desempenho do anúncio. Substitua o valor applicationId pela ID da Store para seu aplicativo.
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance?applicationId=9NBLGGH4R315&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/adsperformance?applicationId=9NBLGGH4R315&startDate=8/1/2015&endDate=8/31/2015&skip=0&$filter=market eq 'US' and deviceType eq 'phone’ eq 'US'; and gender eq 'm' HTTP/1.1
Authorization: Bearer <your access token>
Response
Corpo da resposta
| Valor | Type | Descrição |
|---|---|---|
| Valor | matriz | Uma matriz de objetos que contêm dados de desempenho agregados do anúncio. Para obter mais informações sobre os dados em cada objeto, consulte a seção Valores de desempenho do anúncio 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 5, mas houver mais de 5 itens de dados para a consulta. |
| TotalCount | int | O número total de linhas no resultado de dados da consulta. |
Valores de desempenho do anúncio
Os elementos na matriz Value contêm os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| date | string | A primeira data no intervalo de datas dos dados de desempenho do anúncio. 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 | A ID da Store do aplicativo cujos dados de desempenho do anúncio você está recuperando. |
| applicationName | string | O nome de exibição do aplicativo. |
| adUnitId | string | A ID da unidade publicitária. |
| adUnitName | string | O nome da unidade publicitária, conforme especificado pelo desenvolvedor na Central de Parceiros. |
| adProvider | string | O nome do provedor de anúncios. |
| deviceType | string | O tipo de dispositivo no qual os anúncios foram veiculados. 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 os anúncios foram veiculados. |
| accountCurrencyCode | string | O código de moeda da conta. |
| pubCenterAppName | string | O nome do aplicativo pubCenter associado ao aplicativo na Central de Parceiros. |
| adProviderRequests | int | O número de solicitações de anúncios para o provedor de anúncios especificado. |
| impressions | int | O número de impressões do anúncio. |
| clicks | int | O número de cliques no anúncio. |
| revenueInAccountCurrency | number | A receita, na moeda do país/região da conta. |
| solicitações | int | O número de solicitações de anúncio. |
Exemplo de resposta
Veja a seguir um exemplo de corpo de resposta JSON para essa solicitação.
{
"Value": [
{
"date": "2015-03-09",
"applicationId": "9NBLGGH4R315",
"applicationName": "Contoso Demo",
"market": "US",
"deviceType": "phone",
"adUnitId":"10765920",
"adUnitName":"TestAdUnit",
"revenueInAccountCurrency": 10.0,
"impressions": 1000,
"requests": 10000,
"clicks": 1,
"accountCurrencyCode":"USD"
},
{
"date": "2015-03-09",
"applicationId": "9NBLGGH4R315",
"applicationName": "Contoso Demo",
"market": "US",
"deviceType": "phone",
"adUnitId":"10795110",
"adUnitName":"TestAdUnit2",
"revenueInAccountCurrency": 20.0,
"impressions": 2000,
"requests": 20000,
"clicks": 3,
"accountCurrencyCode":"USD"
},
],
"@nextLink": "adsperformance?applicationId=9NBLGGH4R315&aggregationLevel=week&startDate=2015/03/01&endDate=2016/02/01&top=2&skip=2",
"TotalCount": 191753
}
Tópicos relacionados
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de