Pular para o conteúdo principal

Consultar o QueryMesh em nome de quem entrou

Com a capacidade QueryMesh ligada, a aplicação consulta o QueryMesh da organização em nome da pessoa que entrou. A credencial é dessa pessoa, e as políticas de dados da organização — acessos, máscaras e filtros definidos pela governança — decidem o que ela vê. Duas pessoas, a mesma consulta, resultados diferentes:

const r = await nn.querymesh.query(req, 'SELECT name, regionkey FROM tpch.tiny.nation')
// r.columns, r.rows — só o que as políticas DESTA pessoa deixam ver

A aplicação não informa o endereço do QueryMesh, não recebe token do IAM e não filtra linha nenhuma.

Antes de começar​

  • O login da organização ligado e publicado no serviço.
  • O QueryMesh da organização configurado no Zero — o administrador da organização faz isso uma vez.
  • Você pode alterar o serviço no projeto.
  • O console ainda não tem a tela: use a CLI (ou a API).

Passo a passo​

  1. O administrador da organização configura o QueryMesh dela, uma vez:

    zero orgs integrations set querymesh --url https://querymesh.suaempresa.com.br

    Só HTTPS. --audience diz o que o QueryMesh exige no token (padrão trino-oidc).

  2. Ligue a capacidade no serviço:

    zero services enable querymesh web

    Não é preciso publicar de novo: a capacidade fica Pronta quando o IAM da organização liberar o QueryMesh para a aplicação.

  3. Confira de ponta a ponta:

    zero services doctor querymesh web

    Cada verificação diz quem resolve o que falta: a aplicação, o administrador da organização ou a plataforma.

  4. No código, consulte com nn.querymesh.query(req, sql).

No código​

import { NNumbers, QueryMeshAccessDeniedError, UnauthenticatedError } from '@nnumbers/zero/app'

const nn = NNumbers.init()

app.get('/api/paises', async (req, res) => {
  try {
    const r = await nn.querymesh.query(req, 'SELECT name, regionkey FROM tpch.tiny.nation ORDER BY name')
    res.json({ columns: r.columns, rows: r.rows })
  } catch (e) {
    if (e instanceof UnauthenticatedError) return res.redirect(e.loginPath)
    if (e instanceof QueryMeshAccessDeniedError) return res.status(403).json({ code: e.code })
    throw e
  }
})

query(req, sql, { maxRows, signal }) devolve { columns, rows }, com o nome e o tipo de cada coluna. Use nomes completos (catálogo.esquema.tabela). maxRows (padrão 100.000) é o teto de linhas trazidas para a memória: acima dele, a consulta é cancelada no QueryMesh. signal também cancela lá, e não só a espera.

ErroCódigoQuando
UnauthenticatedErrorUSER_SESSION_REQUIREDninguém entrou, ou a sessão terminou — mande ao loginPath
ResourceCredentialErrorRESOURCE_CREDENTIAL_DENIEDa capacidade ou o QueryMesh da organização desligado, ou o IAM ainda não liberou o QueryMesh — zero services doctor querymesh <serviço> diz qual
QueryMeshIdentityRejectedErrorQUERYMESH_IDENTITY_REJECTEDo QueryMesh não aceitou a identidade da pessoa — confira a audiência configurada
QueryMeshAccessDeniedErrorQUERYMESH_ACCESS_DENIEDas políticas de dados negaram a consulta a esta pessoa
QueryMeshErrorQUERYMESH_QUERY_FAILEDsintaxe, tabela inexistente, maxRows excedido; retryable quando repetir pode dar certo

Em outra linguagem​

A aplicação pede a credencial da pessoa ao endereço em NNUMBERS_BROKER_URL, com a identidade que recebeu na requisição:

POST {NNUMBERS_BROKER_URL}/v1/credentials
X-NNumbers-Identity: <a identidade da requisição>
Content-Type: application/json

{"resource": "querymesh"}

A resposta traz token, token_type (Bearer), expires_in (segundos) e resource.endpoint, o endereço do QueryMesh. Consulte esse endereço com o protocolo do QueryMesh e Authorization: Bearer <token>, e nunca mande o token a outro endereço. Confira a identidade antes, como em Quem entrou, no código: sem pessoa, não peça.

Os estados​

EstadoO que significaO que fazer
Desligadaa capacidade não está ligada—
Falta configurar na organizaçãoa organização não tem o QueryMesh configurado, ou ele está desligadoo administrador da organização: zero orgs integrations set querymesh --url https://…
Aguardando o login da organizaçãoo login da organização ainda não está pronto para a aplicaçãoligue e publique o login da organização
Liberando o QueryMesh no IAMa plataforma está liberando o QueryMesh para a aplicaçãoaguarde
O IAM não liberou o QueryMesho IAM da organização ainda não aceita o QueryMesh para as aplicações — uma vez por organizaçãopeça ao administrador da plataforma; segue sozinho depois
Prontaa credencial sai em nome de quem entrou—

O que a plataforma garante​

  • A consulta é da pessoa. A credencial leva a identidade de quem entrou, emitida pelo IAM da organização para esta aplicação, e vale minutos. Sem pessoa não há consulta: não existe credencial "da aplicação" para cair nela.
  • O endereço não é da aplicação. Vem da configuração da organização, e a credencial só vai a ele. Se o QueryMesh mandar continuar em outro endereço, a consulta falha e a credencial não segue.
  • Desligar corta na hora. Desligar a capacidade ou o QueryMesh da organização faz a plataforma parar de emitir a credencial — antes mesmo de o IAM terminar de retirar a liberação.
  • Cada um no seu lugar. Outra aplicação, outra organização, sessão encerrada: nenhuma credencial.

Limites​

  • O nn.querymesh é do SDK de TypeScript; em outra linguagem, use a chamada acima.
  • Uma integração por organização: o QueryMesh.
  • O console ainda não tem a tela: use a CLI ou a API.

Próximos passos​