Obter instalações de aplicativo da área de trabalho
Use esta URI REST para obter dados de instalação agregados no formato JSON para um aplicativo de área de trabalho que você adicionou ao Programa de aplicativo da área de trabalho do Windows. Esta URI permite que você obtenha dados de instalação em um determinado intervalo de datas e outros filtros opcionais. Essas informações também estão disponíveis no relatório Instalações para aplicativos de área de trabalho 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/desktop/installbasedaily |
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 do produto do aplicativo da área de trabalho para o qual você deseja recuperar dados de instalação. Para obter a ID do produto de um aplicativo de área de trabalho, abra qualquer relatório de análise para seu aplicativo de área de trabalho na Central de Parceiros (como Relatório de instalações) e recupere a ID do produto da URL passando o mouse sobre o link para revelar os detalhes. | Sim |
| startDate | date | A data de início no intervalo de datas dos dados de instalação a serem recuperados. O padrão é de 90 dias antes da data atual. | Não |
| endDate | date | A data de término no intervalo de datas dos dados de instalaçã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. Você pode especificar os seguintes campos no corpo da resposta:
|
Não |
| orderby | string | Uma instrução que ordena os valores dos dados de resultado para cada instalação. A sintaxe é orderby=field [order],field [order],.... O parâmetro field pode ser um dos seguintes campos do corpo da resposta:
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 no corpo da resposta:
As linhas de dados retornadas conterão os campos especificados no parâmetro groupby, bem como:
|
Não |
Exemplo de solicitação
O exemplo a seguir mostra várias solicitações para obter dados de instalação de aplicativos da área de trabalho. Substitua o valor applicationId pelo ID do Produto do aplicativo da área de trabalho.
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/desktop/installbasedaily?applicationId=1234567890&startDate=2018-01-01&endDate=2018-02-01&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/desktop/installbasedaily?applicationId=1234567890&startDate=2018-01-01&endDate=2018-02-01&filter=market eq 'US' and deviceType eq 'PC' 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 de instalação agregados. Para obter mais informações sobre os dados em cada objeto, consulte a tabela a seguir. |
| @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 instalação para a consulta. |
| TotalCount | int | O número total de linhas no resultado de dados da consulta. |
Os elementos na matriz Value contêm os valores a seguir.
| Valor | Type | Descrição |
|---|---|---|
| date | string | A data associada ao valor base da instalação. |
| applicationId | string | A ID do produto do aplicativo da área de trabalho para o qual você recuperou dados de instalação. |
| productName | string | O nome de exibição do aplicativo da área de trabalho como derivado dos metadados dos seus executáveis associados. |
| applicationVersion | string | A versão do executável do aplicativo que estava instalado. |
| deviceType | string | Uma destas cadeias de caracteres que especifica o tipo de dispositivo no qual o aplicativo da área de trabalho está instalado:
|
| market | string | O código de país ISO 3166 do mercado em que o aplicativo de área de trabalho está instalado. |
| osVersion | string | Uma das seguintes sequências que especifica a versão do SO na qual o aplicativo da área de trabalho está instalado:
|
| osRelease | string | Uma das seguintes cadeias de caracteres que especifica a versão do sistema operacional ou de pré-lançamento (como uma subpopulação dentro da versão do sistema operacional) na qual o aplicativo da área de trabalho está instalado. Para Windows 11: Versão 2110 Para Windows 10:
Para o Windows Server 1709:
Para o Windows Server 2016:
Para Windows 8.1:
Para Windows 7:
Se a versão do SO ou a versão de pré-lançamento for desconhecida, esse campo terá o valor Desconhecido. |
| installBase | número | O número de dispositivos distintos que tinham o produto instalado no nível da agregação especificado. |
Exemplo de resposta
Veja a seguir um exemplo de corpo de resposta JSON para essa solicitação.
{
"Value": [
{
"date": "2018-01-24",
"applicationId": "123456789",
"productName": "Contoso Demo",
"applicationVersion": "1.0.0.0",
"deviceType": "PC",
"market": "All",
"osVersion": "Windows 10",
"osRelease": "Version 1709",
"installBase": 348218.0
}
],
"@nextLink": "desktop/installbasedaily?applicationId=123456789&startDate=2018-01-01&endDate=2018-02-01&top=10000&skip=10000&groupby=applicationVersion,deviceType,osVersion,osRelease",
"TotalCount": 23012
}