Índice:

•Sobre este site
•Como realizar uma consulta
•Tipos de dados de entrada/retorno de uma consulta
•Perguntas frequentes

Sobre este site

O Portal de Dados da UFRGS foi elaborado com o objetivo de disponibilizar para a comunidade os dados que estão armazenados na base de dados institucional da Universidade, em conformidade com as diretivas da Lei Nº 13.709, de 14 de Agosto de 2018, ou Lei Geral de Proteção de Dados - LGPD.
Nesta primeira versão do Portal estão disponibilizados dados que são considerados “públicos” de acordo com a LGPD e a Política de Classificação e Compartilhamento de Dados da UFRGS.

O nome Portal de Dados da UFRGS disponibiliza seus dados através de um conjunto de APIs. Esta interface (construída em arquitetura REST) realiza requisições/consultas à base de dados e disponibiliza o resultado desta consulta de maneira organizada para o usuário.

As informações que este site oferece estão organizadas em consultas, divididas em grupos, de acordo com o seu escopo:

•Graduação: disciplinas de graduação, docentes, cursos, turmas, etc.
•Pós-graduação: disciplinas dos programas de pós-graduação, docentes, turmas, etc.
•Institucionais: comissões, unidades acadêmicas, etc.
•Pesquisa: dados de projetos de pesquisa, etc.
•Espaços Físicos: dados de campi, salas, prédios, etc.
•Assistência Estudantil: dados de benefícios, etc.
•Extensão: dados de atividades de extensão, etc.
•Pessoas: dados de servidores técnico-administrativos, docentes, etc.

Estes grupos de consulta estão listados na página inicial do site:
Logo do Catálogo de Serviços de TI

Como realizar uma consulta

1) Encontrar uma consulta:

2) Visualizar dados de uma consulta e definir dados de parâmetros (quando aplicável):

Cada página de consulta é composta pelos seguintes itens:

•Descrição: um breve resumo sobre cada consulta;
•URI (Uniform Resource Identifier): identificador do recurso acessado por uma consulta;
•Parâmetros de entrada: descrição dos dados que podem ser utilizados para identificar ou filtrar os resultados que serão retornados pela consulta. Cada parâmetro possui: um nome, a identificação se é obrigatório ou opcional, e um tipo (os tipos possíveis estão descritos na sessão "Tipos de dados de entrada/retorno");
•Dados retornados: informações que farão parte de cada item que compõe o resultado da consulta. Para cada retorno estão descritos seu nome e o seu tipo (os tipos possíveis estão descritos na sessão "Tipos de dados de entrada/retorno");
•Obter dados: campos de formulário onde podem ser preenchidos valores para os parâmetros de entrada;
•Formato do arquivo de retorno: É possível realizar o download do resultado da consulta nos formatos JSON, CSV e XLS;
•Consultas: menu na lateral direita com a lista das outras consultas do grupo em questão.

3) Preencher o valor dos parâmetros de consulta (quando aplicável) e selecionar o tipo de arquivo para download:

Os parâmetros de uma consulta podem ser obrigatórios, opcionais ou inexistentes (quando não há parâmetros de entrada, retorna a lista de todos os itens da consulta).
Logo do Catálogo de Serviços de TI

Para selecionar o tipo de arquivo de download do resultado da consulta, deve-se clicar no botão correspondente:

•JSON: "JavaScript Object Notation", que utiliza texto no formato atributo-valor;
•CSV: "Comma-separated values", arquivos de texto que separam valores com vírgulas (podem ser abertos por editores de texto simples ou planilhas, como bloco de notas ou Microsoft Excel);
•XLS: arquivo de planilha para Microsoft Excel.

Exemplo de retorno em formato JSON:
Logo do Catálogo de Serviços de TI

Exemplo de retorno em formato CSV:
Logo do Catálogo de Serviços de TI

Exemplo de retorno em formato XLS:
Logo do Catálogo de Serviços de TI

Observação (casos especiais):

3.a) Caso o resultado de uma consulta seja vazio (ou seja, sem nenhum elemento), para os arquivos no formato CSV e XLS, a mensagem “Não foram encontrados resultados para a busca.” é exibida, já para arquivos em formato JSON, é realizado o download de um arquivo com 0 elementos.

Exemplo de retorno sem resultados para arquivo CSV ou XLS:

Logo do Catálogo de Serviços de TI

Exemplo de retorno sem resultados para arquivo JSON:

Logo do Catálogo de Serviços de TI

3.b) Algumas consultas possuem dados de retorno com subdocumentos (subelementos), que apresentam uma incompatibilidade com os arquivos nos formatos CSV e XLS. Para estes tipos de consultas apenas é permitido o download de arquivos no formato JSON. Um exemplo deste caso é a lista de membros de um projeto de interação acadêmica, onde para cada membro são exibidos um conjunto de dados de identificação.

Exemplo de tipo de retorno "subdocumento" na descrição da consulta:
Logo do Catálogo de Serviços de TI

Exemplo de resultado de subdocumento em uma consulta:
Logo do Catálogo de Serviços de TI

Tipos de dados de entrada/retorno de uma consulta

Os tipos de dados de retorno possíveis para uma consulta são:

•Data: no formato dd/mm/aaaa, sendo dd – dia, mm - mês e aaaa - ano;
•Misto: para dados com definição genérica de tipo;
•Numérico inteiro/integral: valores numéricos positivos, negativos e zero, sem casas decimais;
•Numérico positivo: valores numéricos maiores que zero, sem casas decimais;
•Período letivo: no formato aaaa/n, sendo aaaa – ano letivo e n – semestre letivo, (por exemplo, 2022/1);
•Ponto flutuante: valores numéricos positivos, negativos e zero que possuem casas decimais;
•Subdocumento: conjunto composto por uma lista de subelementos, que possuem também parâmetros de retorno; e
•Texto: valor textual que permite diferentes tipos de caracteres (letras, números, caracteres especiais).

Perguntas frequentes

Como saber se os dados que necessito estão disponíveis?

É possível verificar os dados disponíveis de duas maneiras:

•Através da lista de consultas disponíveis em cada grupo; ou
•Através dos dados de retorno cadastrados em cada consulta.

Caso os dados desejados não estejam disponíveis, é possível solicitar o cadastro dos mesmos (botão “Solicitar Serviço” no Catálogo de Serviços de TI, https://catalogoservicos.ufrgs.br/ti). Será então avaliada a possibilidade de publicidade dos dados de acordo com os critérios da LGPD, ou seja, se os dados são públicos ou restritos. Caso a disponibilização seja possível, após a análise da solicitação, será implementada e disponibilizada uma nova consulta no portal de dados (ou um novo retorno para consulta).
Observação: Nesta versão do portal, apenas dados públicos são disponibilizados.

Por que algumas consultas não possuem opção de download em formato de arquivo CSV e XLS?

Quando algum dos dados de retorno de uma consulta é do tipo “subdocumento”, o download está disponível apenas no formato JSON. Isto acontece por uma incompatibilidade de formatação dos arquivos CSV e XLS com o tipo subdocumento.

Por que às vezes a quantidade de elementos que o arquivo em formato JSON retorna é menor do que dos arquivos em formato CSV e XLS?

O retorno de resultados da consulta em formato JSON utiliza uma funcionalidade chamada “paginação” (representada pelos atributos: per-page , quantidade de elementos em uma página, e page , página à qual o conjunto de dados pertence), que define um número máximo de elementos que farão parte do arquivo. O número máximo padrão é 1000. Um exemplo de consulta em que esta paginação é feita é “Disciplinas de graduação”, sem a utilização do parâmetro “Curso”. Nesta versão do portal de dados ainda não é possível editar estes atributos de paginação através do sistema, porém isto pode ser feito a partir de uma requisição à API utilizando um navegador web, um cliente de API ou uma aplicação própria.

É possível acessar os dados utilizando uma aplicação diferente deste portal?

Como a API UFRGS foi construída utilizando arquitetura REST (Representational State Transfer), é possível realizar uma requisição diretamente aos seus endpoints (pontos de comunicação de acesso) e acessar os dados disponíveis das seguintes maneiras:

1. A partir do portal de dados;
2. A partir do navegador web, utilizando uma URL bem formatada na barra de endereços para realizar a requisição. Exemplo: para a requisição “Disciplinas de um determinado curso de graduação”, é possível utilizar a URL: https://api.ufrgs.br/v2/graduacao/curso/298/disciplinas, onde 298 é o código do curso. As URLs que acessam os endpoints estão descritas no item "URI" de cada consulta;
3. Através de uma ferramenta cliente de API (Postman, REST-assured, cURL, por exemplo), definindo ambientes, coleções e parâmetros conforme os dados disponíveis para cada consulta no portal;
4. A partir de uma aplicação própria desenvolvida pelo usuário da API (como uma aplicação web ou aplicativo para dispositivos móveis, por exemplo), definindo os parâmetros de implementação de acordo com os dados disponibilizados para cada consulta do portal.

Outras situações, ou dúvidas relacionadas com as situações descritas acima, entrar em contato por meio do botão “Solucionar dúvida” no Catálogo de Serviços de TI (https://catalogoservicos.ufrgs.br/ti).

Existe alguma maneira de organizar os dados de retorno da consulta, caso a lista de resultados seja muito longa (além dos arquivos JSON, CSV e XLS providos)?

Quando a requisição é realizada diretamente aos endpoints (pontos de comunicação de acesso) da API, é possível formatar e organizar os resultados utilizando os seguintes parâmetros na consulta:

•fields: atributos que devem ser retornados, do tipo texto ( string ), separados por vírgula
•per-page: número de registros por página, do tipo número inteiro ( integer );
•fields: atributos que devem ser retornados, do tipo texto ( string ), separados por vírgula

É possível filtrar os dados de retorno de uma consulta, caso não sejam desejados todos os dados listados no portal?

É possível selecionar os dados que serão retornados por uma consulta acessando diretamente os endpoints (pontos de comunicação de acesso) da API e utilizando o parâmetro “fields”, o qual deve ser preenchido com todos os atributos desejados, separados por vírgula.
Este parâmetro pode ser utilizado nas requisições feitas através do navegador web, de softwares clientes de API e de aplicações externas (que podem ser desenvolvidas pelo próprio usuário dos dados da API).
Por exemplo, a consulta “Disciplinas de graduação” possui os seguintes dados de retorno: Sigla, NomeDisciplina, NrCreditos, Sumula, Objetivo e Departamento. Caso seja desejado apenas os dados de Sigla, NomeDisciplina e Departamento, é possível atribuir estes valores ao parâmetro “fields” no momento da chamada à API, separados por vírgula ( fields=Sigla,NomeDisciplina,Departamento ).