OData
OData
A superfície para ferramentas de BI. Fala OData v4, então o Power BI e o Excel descobrem as coleções, os tipos e o que dá para filtrar sozinhos.
- Base
https://service.agrosti.com.br/odata/v1/- Autenticação
Authorization: Bearer oag_...- Coleções
- 50
- Escrita
- Não — a superfície é somente leitura
Se você usa Power BI, comece por Conectar o Power BI — a ferramenta monta estas consultas por você. Esta página serve para quem quer entender ou escrever a consulta na mão.
Descobrir a estrutura
curl -H "Authorization: Bearer oag_SEU_TOKEN" \
"https://service.agrosti.com.br/odata/v1/"| Endereço | Devolve |
|---|---|
/odata/v1/ | As coleções disponíveis para o seu token |
/odata/v1/$metadata | Campos, tipos e o que cada coleção sabe fazer |
O $metadata é a fonte da verdade em tempo de execução: declara, por
coleção, o que é filtrável, o que é ordenável e que nada aqui aceita escrita.
Esta documentação é gerada da mesma definição, então as duas nunca divergem.
Filtrar
/odata/v1/Harvest?$filter=season eq '2025'Comparação
| Operador | Significa | Exemplo |
|---|---|---|
eq | igual | crop eq 'LARANJA' |
ne | diferente | application ne 'M' |
gt ge | maior, maior ou igual | date ge 2025-01-01 |
lt le | menor, menor ou igual | date le 2025-12-31 |
in | em uma lista | crop in ('LARANJA','CAFE') |
Texto
$filter=contains(farm,'SANTA')
$filter=startswith(subarea,'T-')
$filter=endswith(document,'2025')Combinar
$filter=season eq '2025' and crop eq 'LARANJA'
$filter=date ge 2025-01-01 and date le 2025-12-31
$filter=(crop eq 'LARANJA' or crop eq 'CAFE') and season eq '2025'
É a regra do OData v4: date ge 2025-01-01, não
date ge '2025-01-01'. Aceitamos as duas formas, mas a sem
aspas é a correta e a que o Power BI envia.
Nem todo campo aceita filtro
Filtra-se dimensão (fazenda, cultura, safra, data) e agrega-se medida (peso, custo, valor). Medidas ficam fora da lista de propósito.
A referência de cada coleção marca quais campos aceitam. Filtrar por um
campo de fora da lista responde 400 com o motivo — nunca um resultado
silenciosamente não filtrado.
Ordenar e escolher campos
$orderby=date desc
$orderby=farm asc,date desc
$select=id,date,farm,grossWeightKg
A chave da coleção volta sempre, mesmo que você não peça em
$select — sem ela o Power BI não consegue relacionar.
Paginar
/odata/v1/Harvest?$top=100&$skip=200&$count=true
Com $count=true, a resposta traz @odata.count com o
total da coleção filtrada — não o da página. Pagine até alcançá-lo.
Filtro obrigatório
PestScoutings exige uma janela de data. É a coleção de maior volume
da API, e o recorte obrigatório mantém a consulta rápida para você e leve para
a operação.
# recusado com 400
/odata/v1/PestScoutings
# aceito
/odata/v1/PestScoutings?$filter=date ge 2025-01-01 and date le 2025-03-31Limite de requisições
60 requisições por minuto por token, no máximo. Ao estourar,
a resposta é 429: espere a virada do minuto e repita. Em OData
isso raramente aperta — $filter e $select resolvem no
servidor o que no REST viraria muitas páginas. A lista completa de erros está
em Erros.
Coleções
Uma coleção é o que o OData chama de entity set — é
esse o termo que você vai encontrar no $metadata e nas mensagens
do Power BI. Aqui usamos "coleção" no texto e o nome real, em inglês, no código.
As 50 coleções, campo a campo, estão no menu à esquerda. Os fatos — o que você soma — são o ponto de partida: