Saltar al contenido 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. Quem executa a consulta é a plataforma, com o token da sessão 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.

Passo a passo​

  1. O administrador da organização configura o QueryMesh dela, uma vez — pela CLI, pela API ou pelo console, em Configurações → Integrações:

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

    Só HTTPS, e só endereço público. O endereço é um por organização.

  2. Ligue a capacidade no serviço — pela CLI, pela API ou pelo console, no cartão Recursos:

    zero services enable querymesh web

    Vale na hora, sem publicar. Enquanto a integração da organização não estiver pronta, o estado é Falta configurar na organização; enquanto o login da organização espera publicação, é Espera o login da organizaçã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).

Para desligar, zero services disable querymesh web: vale na hora e a próxima consulta é recusada. O login da organização continua. E organization-iam só pode ser desligado depois do QueryMesh.

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 }: cada coluna tem name e type (o tipo do Trino), e cada linha traz um valor por coluna, na ordem das colunas. Use nomes completos (catálogo.esquema.tabela). maxRows (1 a 100.000; padrão 100.000) é o teto de linhas: acima dele, a consulta é cancelada no QueryMesh. signal cancela a consulta lá também, e não só a espera.

Os códigos​

ErroCódigoQuandoO que fazer
UnauthenticatedErrorUSER_SESSION_REQUIREDninguém entrou, ou a sessão terminoumande ao loginPath
QueryMeshNotConfiguredErrorORGANIZATION_INTEGRATION_NOT_CONFIGUREDa organização não tem o QueryMesh configurado, ou ele está desligadoo administrador da organização: zero orgs integrations set querymesh --url https://…
QueryMeshNotEnabledErrorQUERYMESH_NOT_ENABLEDesta aplicação não ligou a capacidadezero services enable querymesh <serviço> — vale na hora, sem publicar
QueryMeshIdentityRejectedErrorQUERYMESH_IDENTITY_REJECTEDo QueryMesh não aceitou o token de quem entrou — ele não confia neste IAM, ou exige outra audiência ou outro scopequando falta ao realm o scope que o QueryMesh exige, quem resolve é a equipe que administra a plataforma — entrar de novo não resolve
QueryMeshAccessDeniedErrorQUERYMESH_ACCESS_DENIEDas políticas de dados da organização negaram a consulta a esta pessoapeça o acesso ao administrador de dados da organização
QueryMeshErrorQUERYMESH_QUERY_FAILEDsintaxe, tabela inexistente, maxRows excedido, ou resposta do QueryMesh fora do protocoloconfira a consulta e repita; se a resposta veio fora do protocolo, fale com quem administra o QueryMesh
QueryMeshErrorQUERYMESH_UNAVAILABLEo QueryMesh não respondeu ou está ocupado, ou a plataforma está no limite de consultasretryable: repita em instantes
—SERVICE_CAPABILITY_REQUIRES_IDENTITYnão é da consulta: é da administração — desligar o login da organização com o QueryMesh ligado (409)desligue o QueryMesh primeiro

Em outra linguagem​

O caminho é o mesmo do SDK: o servidor confere a identidade que recebeu (veja Em outra linguagem) e chama o broker, dentro do cluster:

POST {NNUMBERS_BROKER_URL}/v1/querymesh/query
X-NNumbers-Identity: <a identidade da requisição, já conferida>
Content-Type: application/json

{"sql": "SELECT 1", "max_rows": 1000}

A resposta traz columns e rows no formato acima; as recusas vêm como {"code", "message"}, com os códigos da tabela. Sem pessoa, não peça. O protocolo de runtime tem a conferência da identidade, os caminhos reservados e os status de cada recusa.

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://…
Espera o login da organizaçãoo QueryMesh consulta em nome de quem entrou, e o login da organização ainda não está no arligue e publique o login da organização
Prontaa consulta sai em nome de quem entrou—

O que a plataforma garante​

  • A consulta é da pessoa. Quem consulta é a plataforma, com o token da sessão de quem entrou — emitido pelo IAM da organização para o login desta 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 o token só vai a ele. Se o QueryMesh mandar continuar em outro endereço, a consulta falha e o token não segue.
  • A audiência que o QueryMesh exige vem de um client scope padrão do client de login, aplicado no realm da organização pelo provisionamento da NNumbers. Enquanto o realm não o tiver, a consulta responde 502 QUERYMESH_IDENTITY_REJECTED informando que falta o scope; entrar de novo não resolve. Depois de aplicado, a sessão que já estava aberta consulta sem novo login.
  • Desligar corta na hora. Desligar a capacidade ou o QueryMesh da organização faz a plataforma parar de consultar — a próxima consulta é recusada.
  • Cada um no seu lugar. Outra aplicação, outra organização, sessão encerrada: nenhuma consulta.

Limites​

  • O nn.querymesh é do SDK de TypeScript; em outra linguagem, use a chamada acima.
  • Uma integração por organização: o QueryMesh.
  • Desligar o login da organização exige desligar o QueryMesh antes.

Próximos passos​