Para listar os dispositivos, a API de Operações oferece um endpoint com o protocolo OData (somente leitura). Abaixo você encontra como montar o request apropriado. Lembrando que para realizar qualquer request a API é necessário acrescentar um bearer token no cabeçalho de autenticação. A cada requisição feita a API de Operações é necessário recalcular o token.
API
A API base para listar os dispositivos está no endereço https://api.cloud4mobile.com.br/devices.
Swagger
Veja mais informações na documentação.
Limites
O máximo de dispositivos permitidos por página é 50. Caso seja requisitado mais (conforme exemplo abaixo) um erro será retornado.
Filtros
Filtros são adicionados ao request através de query strings. Não esqueça de utlizar “&” como separador. Filtros disponíveis:
- status: enumeração que filtra a lista de dispositivos de acordo com o status
- valores possíveis: 0 (todos), 1 (habilitados), 2 (desabilitados), 3 (ativos) e 4 (inativos)
- Ativo/Inativo: corresponde a última comunicação do dispositivo com o servidor. Caso seja maior que o definido nas configurações é considerado inativo.
- O valor default para esse filtro é 0, caso não seja informado na query string.
- Exemplo: &status=1
- $expand: Filtro de expansão será detalhado mais a frente
- $top: quantidade máxima por página (até o limite de 50)
- $skip: controla o offset da paginação
- $orderby: indica a ordenação do resultado
- Exemplo: &$orderby=HardwareId asc
- $inlinecount=allpages: retorna um cabeçalho HTTP (X-Total-Count) contendo o total de dispositivos encontrados com os filtros fornecidos
Os filtros que iniciam com “$” são do odata e são os únicos permitidos desse protocolo.
Exemplo de Paginação
Para exemplificar como proceder com a paginação, considere que temos 204 dispositivos habilitados cadastrados em nosso ambiente. Considere também que vamos exibir 25 dispositivos por página, logo teríamos 9 páginas.
- Primeira chamada: https://api.cloud4mobile.com.br/devices?$top=25&$skip=0
- Segunda chamada: https://api.cloud4mobile.com.br/devices?$top=25&$skip=25
- Terceira chamada: https://api.cloud4mobile.com.br/devices?$top=25&$skip=50
E assim por diante. Para saber o total de dispositivos disponíveis basta incluir o filtro $inlinecount=allpages, conforme descrito anteriormente.
É possível controlar a paginação de 2 maneiras:
- Dinamicamente: mantendo o top fixo, se após a chamada da API a quantidade itens retornado for menor que o skip, então não temos mais páginas. No exemplo citado, a última chamada ($top=25&$skip=225) retornaria 4 itens apenas, logo não existem mais páginas
- Estaticamente: colocar o filtro $inlinecount=allpages na primeira requisição (skip=0) e realizar um cálculo com o valor que será utilizado no top. Com base no exemplo citado:
- X-Total-Count retorna 204, fixando o top em 25 -> 204/25=8,16 -> 9 páginas (8 páginas com 25 itens e 1 com os últimos 4 itens)
X-Total-Count retorna 204, fixando o top em 25 -> 204/25=8,16 -> 9 páginas (8 páginas com 25 itens e 1 com os últimos 4 itens)
Filtro de expansão ($expand)
Por padrão, apenas algumas informações são retornadas de uma chamada para listar os dados dos dispositivos. Os detalhes de algumas informações só são incluidos no retorno se explicitamente requisitadas. Para isso deve-se utilizar o filtro $expand do OData. Esses são os possíveis valores que podem ser usados com essa opção:
- DataUsage: retorna o consumo dos dados da rede móvel do dispositivo
- BatteryMonitorSettings: retorna as configurações aplicadas para o monitor de bateria
- DataUsageMonitorSettings: retorna as configurações aplicadas para o monitor de uso de dados da rede móvel
- LocationMonitorSettings: retorna as configurações aplicadas para o monitor de localização do dispositivo
- MemoryMonitorSettings: retorna as configurações aplicadas para o monitor de uso de memória do dispositivo
- LocationHistoryMonitorSettings: retorna as configurações aplicadas para o monitor do histórico de localização do dispositivo
- ApplicationUsageStatisticsMonitorSettings: retornas as configurações aplicadas para o monitor de estatísticas de uso dos aplicativos (tempo de execução e uso da rede)
- Group: retorna os detalhes do grupo do dispositivo
- LastBatteryData: retorna a última informação coletada da bateria
- LastLocation: retorna a última localização coletada pelo dispositivo
- LastMemoryData: retorna a última informação coletada sobre o uso da memória do dispositivo
- Blacklist: retorna a lista dos aplicativos bloqueados aplicada ao dispositivo
- SamsungPolicySettings: retorna as configurações do perfil de configurações da Samsung aplicada ao dispositivo
- ApplicationInventory/ApplicationPackages: retorna a lista de aplicativos instalados no dispositivo
- ApplicationSettings: retorna as configurações aplicadas aos aplicativos através do perfil de configurações da Samsung
Mais de uma opção de $expand pode ser usada, basta incluir separando por vírgulas, exemplo: $expand=DataUsage,Group. A opção ApplicationInventory/ApplicationPackages deve ser usada com a barra: $expand=DataUsage,Group,ApplicationInventory/ApplicationPackages.
Retorno da API
O retorno da API é uma lista contendo os detalhes requisitados na consulta. Veja exemplos de como utilizar a API:
- C#
- Typescript (Javascript) – em breve
- Java – em breve
Consulte os campos de retorno na documentação swagger.
