Guia

Conectar o Power BI

O OpenAGROs é um serviço OData v4 padrão. O Power BI descobre as coleções, os tipos e o que dá para filtrar sozinho.

1. Conectar

No Power BI Desktop: Obter dados → Feed OData.
Endereço: https://service.agrosti.com.br/odata/v1
Na tela de autenticação, aba Básico:
- Usuário:openagros — qualquer valor serve, ele é ignorado.
- Senha: o token, que começa com oag_.
Conectar. O navegador de coleções abre.

As outras abas não servem

Anônimo não envia credencial nenhuma;Windows e Conta organizacional mandam esquemas que não carregam o token. Todas respondem“não foi possível autenticar com as credenciais fornecidas”. A abaAPI da Web só funciona em conector customizado, que declara um nome para a chave — o conector OData padrão não declara.

Se você já salvou uma credencial errada para este endereço, o Power BI a reusa em silêncio e o erro se repete. Limpe em Arquivo → Opções e configurações → Configurações da fonte de dados → Permissões globais.

2. Se você preferir escrever o M

A consulta equivalente, para versionar ou parametrizar o endereço. A credencial continua sendo a Básica do passo anterior — não coloque o token na consulta.

Power Query

let
    Fonte = OData.Feed(
        "https://service.agrosti.com.br/odata/v1",
        null,
        [Implementation = "2.0"]
    )
in
    Fonte

3. Escolher as coleções

O navegador lista as coleções que os escopos do seu token liberam. Comece pequeno: um fato e as dimensões dele. Um modelo com tudo carregado fica lento e não fica mais útil.

Para um painel de safra, por exemplo: Harvest,Subareas, Farms e Crops.

Modelo pronto para o Fechamento

Para migrar o relatório de fechamento que antes lia o SQL diretamente, comece pelas projeções curadas abaixo. Elas já resolvem os joins e a deduplicação que não devem ser refeitos no Power BI:

Coleção	Grão	Uso
`CashBalancePeriods`	mês × conta × subconta	saldo anterior, movimento e saldo final
`AgriculturalCostRows`	apontamento × talhão	custo por operação, fazenda e planta
`HarvestPlantPeriods`	mês × talhão × safra	produção e kg/planta
`SalesPerformancePeriods`	mês × fazenda × safra	receita e receita/planta

As quatro coleções exigem filtro de data. Consulte os campos e os filtros disponíveis nas referências OData ou REST de cada coleção.

4. Relacionar

Os relacionamentos são por chave de texto, no formatofazenda|área|subárea. Todo fato traz farmKey,areaKey e subareaKey, e cada dimensão traz oid correspondente:

Do fato	Para a dimensão	Cardinalidade
`subareaKey`	`Subareas.id`	muitos para um
`areaKey`	`Areas.id`	muitos para um
`farmKey`	`Farms.id`	muitos para um
`activityId`	`Activities.id`	muitos para um

Relacione sempre por essas chaves de caminho. Elas carregam a hierarquia inteira, o que evita ambiguidade quando nomes de área ou de talhão se repetem entre fazendas.

5. Datas

Os campos de data chegam como data de verdade, não texto — então a hierarquia de tempo (ano, trimestre, mês) funciona direto. Se você for usar uma tabela de calendário própria, relacione-a ao campodate do fato.

Refresh incremental

Sem ele, todo refresh puxa a coleção inteira. Com ele, o Power BI particiona a tabela por data e só recarrega as partições recentes. Funciona em qualquer coleção com date filtrável; as que não têm data própria (ActivityMachines, LivestockActivityCosts) herdam a do apontamento e precisam ser recortadas pelo pai.

Crie os parâmetros RangeStart e RangeEnd, do tipo Data/Hora — os nomes são exigência do Power BI —, e filtre a tabela por eles:

text

let
    Fonte = OData.Feed(
        "https://service.agrosti.com.br/odata/v1",
        null,
        [Implementation = "2.0"]
    ),
    Tabela = Fonte{[Name = "Activities"]}[Data],
    Janela = Table.SelectRows(
        Tabela,
        each [date] >= DateTime.Date(RangeStart)
            and [date] < DateTime.Date(RangeEnd)
    )
in
    Janela

O intervalo é semiaberto: >= no começo e< no fim. Com <= dos dois lados, o último dia de uma partição é também o primeiro da seguinte, e ele conta duas vezes.

Atualize os últimos dois meses, não o último mês

Apontamento é lançado com atraso. Numa base real, o atraso médio entre o dia do trabalho e o dia do lançamento é de menos de um dia, mas o máximo observado no ano passou de dois meses. Uma janela de 30 dias perde o que foi digitado depois da virada — e perde em silêncio. Deixe também“Detectar alterações de dados” desligado: ele depende de uma coluna de última modificação confiável, que a origem não tem.

Desempenho

Filtre no servidor. Filtro aplicado no Power Query vira consulta no servidor; filtro aplicado depois baixa tudo antes. A referência de cada coleção marca quais campos aceitam filtro.
Recorte por data ao importar. Uma safra costuma bastar, e a diferença é de segundos para minutos.
Importe poucas coleções por vez. O Power BI abre todas as selecionadas em paralelo e pagina cada uma até o fim. Marcar as 50 de uma vez gera centenas de requisições em rajada e pode esbarrar no limite por minuto — o import falha no meio, com 429.
PestScoutings exige janela de data. É a coleção de maior volume; sem filtro de data a API recusa com 400. É proposital: o recorte mantém a consulta rápida.
Importação, não DirectQuery. A fonte é o sistema que a sua equipe usa o dia todo; consultar a cada interação de visual pesa na operação.

Antes de publicar o painel

Modelo conectado não é modelo correto. LeiaComo modelar sem errar: são quatro decisões, e as quatro dão número errado com cara de certo.