Camada de Serviços do Sonar

Web Server API do Sonar

O Sonar possui uma camada de serviços bem vasta que permite desde consultar indicadores, projetos, usuários, eventos, alertas, código fonte, etc. Praticamente qualquer necessidade que você tiver pode ser consultada pela camada de serviços.

Alguns serviços não precisam de autenticação e podem ser consultados de forma simples e direta.

Exemplo

Consultar todos os indicadores de um projeto no Sonar
http://localhost:9000/api/metrics

Outros precisam de autenticação. O Sonar utiliza autenticação básica para HTTP e para isso é necessário informar o usuário e senha a cada requisição. Lembram do usuário "admin" que usamos na configuração do dashboard do Sonar ?

Exemplo

Recuperando as propriedades do servidor Sonar
admin:admin http://localhost:9000/api/server/system

Atenção

Os serviços podem retornar os dados em XML ou Json, por padrão os serviços retornam informações no formato XML. Para alterar o formato para Json, basta incluir o parâmetro "format=json" na chamada, o exemplo abaixo retorna todos os indicadores do servidor no formato json;
http://localhost:9000/api/metrics?format=json

Para acessar a documentação completa e oficial da camada de serviços basta acessar o link abaixo:
http://docs.codehaus.org/display/SONAR/Web+Service+API

Consulta de Indicadores

Vamos conhecer a API Web de consulta de indicadores (resources), é o serviço mais utilizado no dia a dia, pois é através dele que vamos integrar o Sonar com qualquer outro serviço, planilha eletrônica, ou novo componente que venhamos a criar.

Seu uso básico lista todos os projetos cadastrados no Sonar. http://localhost:9000/api/resources

Mas isso vai trazer somente os projetos do servidor, para trazer os indicadores é necessário completar a requisição com os indicadores que queremos buscar.

No exemplo abaixo, vamos buscar todos os projetos do Sonar e o indicador Número de Linhas de Código:
http://localhost:9000/api/resources?metrics=ncloc

<resources>

<resource>

<id>1</id>

<key>my:SonarSnitch</key>

<name>Sonar Snitch</name>

<lname>Sonar Snitch</lname>

<scope>PRJ</scope>

<qualifier>TRK</qualifier>

<lang>cs</lang>

<version>1.0</version>

<date>2014-10-04T18:46:48-0300</date>

<creationDate>2014-10-04T18:46:48-0300</creationDate>

<msr>

<key>ncloc</key>

<val>1558.0</val>

<frmt_val>1.558</frmt_val>

</msr>

</resource>

</resources>

Atenção: É necessário informar na API a lista de identificadores (key) separados por vírgula dos indicadores que você quer consultar. Caso seja informado um identificador inválido ou sem medida, o Sonar vai ignorar esses indicadores na sua requisição, por exemplo, na requisição abaixo o retorno será igual ao exemplo acima, pois o projeto não tem testes unitários registrados, e o indicador_falso não existe.
http://localhost:9000/api/resources?metrics=ncloc,coverage,indicador_falso

Preparando a lista de identificadores dos indicadores

Existem duas formas de se descobrir os identificadores (key) dos indicadores:

1. Utilizando a API de indicadores (metrics). O primeiro comando que vimos vai retornar todos os indicadores registrados no Sonar, Ele traz diversas as informações do indicador, como identificador (key), nome, descrição, etc.
   Veja no exemplo o retorno dos dados do indicador Número de Linhas de Código:
   http://localhost:9000/api/metrics/ncloc
   <metrics>
   <metric>

   <key>ncloc</key>

   <name>Lines of code</name>

   <description>Non Commenting Lines of Code</description>

   <domain>Size</domain>

   <qualitative>false</qualitative>

   <direction>-1</direction>

   <user_managed>false</user_managed>

   <val_type>INT</val_type>

   <hidden>false</hidden>

   </metric>
   </metrics>
   
2. Fazendo uma consulta direto no dashboard do Sonar e capturando os identificadores dos indicadores que são expostos pela Web API.

Vamos montar a consulta para recuperar o Número de Linhas de Código e o Total Quality e depois montar a requisição com o ncloc que já conhecemos e o Total Quality que é um indicador customizado.

Acessando a dashboard do Sonar, e logado com o usuário Admin, (login e senha "admin", lembra ? caso não se lembra, não deixe de ver o post "Configurando visualizações do Sonar") será exibido no menu o link para "measure", clique nele para acessarmos um gerador de consultas do Sonar. Pode acessar diretamente o link também:
http://localhost:9000/measures

Preencha o filtro de pesquisa com Projetos e adicione os dois indicadores (metrics) Lines os Code e Total Quality, como na imagem abaixo e clique em Search:

Filtro de pesquisa preenchido

A busca vai gerar o link abaixo na barra de endereço do navegador. Repare que nos trechos em negrito, já temos o que precisamos, que é os identificadores dos indicadores que queremos.
http://localhost:9000/measures/search?qualifiers%5B%5D=TRK&baseId=&c3_metric=ncloc&c3_period=&c3_op=gt&c3_val=0&c2_metric=total-quality&c2_period=&c2_op=gt&c2_val=0&search=Search

Com os identificadores expostos fica fácil gerar nossa query pela API:
http://localhost:9000/api/resources?metrics=ncloc,total-quality

<resources>

<resource>

<id>1</id>

<key>my:SonarSnitch</key>

<name>Sonar Snitch</name>

<lname>Sonar Snitch</lname>

<scope>PRJ</scope>

<qualifier>TRK</qualifier>

<lang>cs</lang>

<version>1.0</version>

<date>2014-10-04T18:46:48-0300</date>

<creationDate>2014-10-04T18:46:48-0300</creationDate>

<msr>

<key>ncloc</key>

<val>1558.0</val>

<frmt_val>1.558</frmt_val>

</msr>

<msr>

<key>total-quality</key>

<val>71.7</val>

<frmt_val>71,7%</frmt_val>

</msr>

</resource>

</resources>

O Sonar Snitch que implementei utiliza além desse serviço o serviço TimeMachine que consegue analisar os indicadores a cada build disparada. Já conversamos sobre essa ferramenta nos posts "Meus primeiros passos no Sonar" e "Integrando indicadores com o Total Quality". Vamos conversar mais sobre essa ferramenta em posts futuros, mas basicamente ela usa 2 serviços o resources que já vimos e o timemachine que permite analisar todos os indicadores de cada inspeção realizada.

Complemento

A documentação completa dessa API encontra-se no link abaixo:
http://docs.codehaus.org/pages/viewpage.action?pageId=244875483


Espero que tenham se divertido tanto quanto eu, esse post vai servir de base para posts que mostrem como integrar o Sonar em outras aplicações e planilhas.

Um grande abraço a todos.

Atenciosamente,
Erick Ferreira Marques da Silva