Selo de estado:
Preview(teto atual do produto) · Curso ACD-250 — Integrações e consumo externo · Aula 1 de 6 · Atualizado em 2026-10-04.
Objetivo#
Ao final desta aula você vai classificar cada superfície pelo estado — e, com isso, responder à única pergunta que importa antes de escrever integração: posso construir sobre isto hoje?
Vídeo#
Identificador no manifesto: acd-250-01-superficies-de-integracao-estado · duração-alvo 5 min · tela do produto: /connect.
Roteiro de gravação (5 capítulos):
| # | Minutagem-alvo | Capítulo | Tela do produto |
|---|---|---|---|
| 1 | 0:00–0:30 | Abertura: título + selo. A pergunta da aula: posso construir sobre isto hoje? | /connect |
| 2 | 0:30–1:30 | Os quatro estados: Preview, fora de GA, Roadmap — e "GA", que não aparece. | /connect |
| 3 | 1:30–3:00 | A tabela das superfícies, uma por uma: chave, OData, kit Power BI/Excel, Embed, API REST, webhooks. | /connect · /excel |
| 4 | 3:00–4:00 | Onde cada uma aparece no produto: chaves em Integrações e chaves, feeds em /connect e /excel. | /settings |
| 5 | 4:00–5:00 | Erros comuns (construir sobre rota fora de GA, esperar SLA) e encerramento. | /connect |
Conteúdo#
Esta aula não ensina a operar nada. Ela ensina a ler o selo — porque em integração, escolher a superfície errada custa um projeto inteiro. A regra de fundo do produto é desconfortável e proposital: nenhuma superfície de integração do ingestia.io é anunciada como GA disponível hoje. O teto do produto é Preview, e cada superfície está num ponto diferente abaixo desse teto.
Os três estados que você vai encontrar — e o quarto, que não aparece
Preview— funciona, está documentado e é coberto por teste, mas sem SLA e sujeito a ajustes de contrato. Pode ir para produção por sua conta e risco, de preferência com o suporte acompanhando.- Fora de GA (indisponível hoje) — a capacidade existe no código e o contrato está documentado, mas não foi liberada para uso externo. É o caso da API de consulta REST: são rotas que disparam consulta cobrável no BigQuery, e elas só abrem quando a guarda de limite de requisições em modo fail-closed e a proteção de custo estiverem endurecidas e re-provadas. Documentar sem liberar é transparência, não convite.
Roadmap— planejado, não existe ainda. Assinatura de webhooks, API de escrita e chave de API por membro (com recorte por linha) estão todas aqui.- GA — não aparece. Se você vir "GA" em qualquer material sobre integração do ingestia.io, o material está errado.
A tabela que vale decorar
| Superfície | Estado | Quando usar |
|---|---|---|
| Autenticação por chave de API | Preview | sempre — é a porta de entrada de todo o resto (Aula 2) |
Feed OData v4 (/api/v1/odata) | Preview | é o caminho recomendado hoje para consumo externo de dados (Aula 3) |
| Kit Power BI / Excel | Preview | Power BI, Excel, Tableau e qualquer cliente OData v4 (Aula 3) |
| Embed SDK (painel dentro do seu site) | Preview | mostrar painel em portal próprio, com token assinado (Aula 4) |
API de consulta REST (/api/v1/query, /api/v1/tables) | Fora de GA | não construa sobre ela hoje — estude o contrato, planeje, espere (Aula 6) |
| Assinatura de webhooks | Roadmap | nunca hoje — reaja a mudanças com consulta periódica do OData, ou com as assinaturas e alertas do próprio produto |
API de escrita (INSERT/UPDATE/…) | Roadmap | nunca — a plataforma é somente leitura por desenho |
| Chave de API por membro, com recorte por linha | Roadmap | nunca hoje — a chave é de nível workspace |
Onde isso aparece no produto
Três telas cobrem o assunto inteiro. /connect ("Conectar BI") é a vitrine: mostra a URL base da API, o nome do seu dataset gold e as receitas de conexão por ferramenta (Power BI via Feed OData, Tableau, Looker Studio). /excel ("Analisar no Excel") é o caminho curto até a tabela dinâmica, em três passos — a chave, a URL pronta e onde colar; é área do dono, porque a chave abre tudo que está publicado. E /settings → Integrações e chaves é onde a credencial nasce e morre: o cartão Chaves de API, com Nova chave e Revogar, ao lado do estado das integrações do ambiente.
Note o que não há nessas telas: nenhum botão "ativar API REST", nenhum campo de URL de webhook. O produto não oferece o que não está liberado — a ausência é a mensagem.
Exemplo: a Aurora Varejo escolhendo uma superfície
A Aurora Varejo precisa de três coisas. A diretoria quer os marts aurora_gold.vendas e aurora_gold.filiais dentro do Power BI. O time de produto quer um painel embutido no portal dos lojistas (https://portal.example.com). E o time de dados pediu "um endpoint JSON para o nosso ETL puxar vendas toda noite".
Com a tabela acima, a decisão sai em cinco minutos. Power BI → feed OData, Preview, segue. Portal dos lojistas → Embed SDK, Preview, segue com token assinado no servidor. O "endpoint JSON para o ETL" → é a API REST, fora de GA: a resposta honesta é não construa isso agora. E o desvio certo não é insistir na rota bloqueada: é usar o mesmo feed OData com atualização incremental filtrando por data — a leitura externa que de fato existe hoje.
Fora de GA não é "beta com jeitinho"
Uma rota fora de GA pode responder 503 como estado esperado, pode mudar de contrato sem aviso de compatibilidade e não entra em nenhuma promessa de disponibilidade. Integração crítica construída sobre ela quebra — e a quebra é prevista, não é incidente.
Erros comuns
| Erro | Por que machuca | O que fazer |
|---|---|---|
Construir o ETL noturno sobre /api/v1/query porque "a doc existe" | a doc é contrato para planejamento; a rota está fora de GA e pode negar | use o feed OData com filtro por data |
| Colar a chave de API no código do navegador ou num repositório | a chave lê todos os marts publicados do workspace | chave só no servidor, como variável de ambiente (Aula 2) |
| Prometer ao cliente disponibilidade, latência ou RPO/RTO da integração | Preview é explicitamente sem SLA; uptime e latência não são medidos hoje | combine "sem SLA" por escrito antes de assinar |
| Esperar webhook de evento | assinatura de webhooks é Roadmap | consulta periódica do OData, ou assinaturas e alertas do produto |
| Supor que a chave respeita o grupo de acesso do membro | o escopo é workspace, não usuário | trate a chave como credencial de serviço |
Estado
Teto do produto: Preview, nada GA. Chave de API, OData v4, kit Power BI/Excel e Embed SDK = Preview (sem SLA). API de consulta REST = fora de GA, barrada por evidência pendente de limite de requisições fail-closed e proteção de custo. Webhooks de assinatura, API de escrita e chave por membro = Roadmap. Valores em BRL (x-ingestia-cost-brl) são projeção, nunca preço faturado garantido. Em toda superfície: somente leitura, escopo por workspace e PII nunca sai pela API.
Faça você mesmo#
Esta aula é de conhecimento: não há exercício operacional. Leia, assista e responda à checagem rápida.
Se quiser fixar sem operar nada, abra /connect apenas para olhar e, para cada ferramenta listada na tela, diga em voz alta qual superfície ela usa e em que estado essa superfície está. Guarde a tabela desta aula: as cinco aulas seguintes são, cada uma, uma linha dela.
Checagem rápida#
Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.
Documentação relacionada#
Capacidades ensinadas#
(conceitual — sem capacidade específica da matriz) — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".