YNKX · Inteligência Sênior SAP BR

Conectar o SAP HANA Cloud

Manual passo a passo para usuários do SaaS — do BTP ao teste real no YNKX. Feito pra qualquer pessoa resolver os bloqueios mais comuns: role, login CF, instância parada, allowlist, usuário técnico e JWT/OAuth.

Começar Ir pro teste final
SaaS
suporte guiado
BTP
ambiente cliente
Ops
suporte recorrente

Antes de começar — 3 becos sem saída

tools

Assinatura obrigatória para abrir o HANA Cloud Central.

hana

A instância de banco real do cliente. É daqui que saem host, porta, allowlist e credenciais.

hana-cloud-connection

Não é banco. É só conexão com data lake. Não resolve o YNKX.

Regra de ouro: se a tela lista a instância do cliente numa tabela com Status, você está no lugar certo.

Fluxo real de diagnóstico no SaaS

1. Role

HANA Central abre sem "Not authorized".

2. Credencial

Usuário/senha ou JWT/OAuth configurado.

3. Running

Instância sai de Stopped/Starting.

4. IP

IP público entra em Allowed Connections.

5. Teste

YNKX retorna ok: True.

O YNKX suporta dois modos comerciais: usuário/senha HANA para onboarding simples e JWT/OAuth para clientes enterprise que já possuem identity provider e user mapping no HANA.

Botão Auto resolver no YNKX

Na tela Configuração SAP HANA, clique Auto resolver. O app testa JWT/OAuth, faz fallback para usuário/senha quando JWT não está habilitado no banco, verifica CF CLI, mira org/space quando possível, dispara Start da instância e mostra o IP público no formato /32. O que a SAP exige no navegador (SSO/passcode e allowlist) fica como próximo passo claro.

Quando o CF ainda não estiver logado, use Abrir passcode CF, faça login com default identity provider, cole o Temporary Authentication Code no campo do YNKX e clique Copiar comando. Depois cole no terminal e rode uma vez.

Fluxograma completo da conexão

BTP autorizado?

Usuário tem SAP HANA Cloud Administrator e fez logout/login.

Não: Security → Users → Assign Role Collection.

→
Credencial configurada?

Use usuário técnico/senha ou service key JWT/OAuth.

Não: preencha usuário/senha ou registre a service key.

→
HANA Running?

Stopped precisa Start; Starting precisa aguardar.

Starting: atualize até virar Running.

→
IP liberado?

Manage Configuration → Connections.

Não: adicione SEU_IP/32.

→
Auto resolver

Se retornar ok: True, conexão pronta.

Depois: migrate + seed.

Not authorized

Volte para BTP role collection. Não mexa na key ainda.

No org/space ou passcode

Use Abrir passcode CF. CF ajuda no Start, mas usuário/senha ou JWT podem conectar sem CF.

JWT falhou, senha conectou

Onboarding simples OK. Para enterprise, configure JWT/OAuth depois.

1

Pré-requisitos

O que você precisa ter antes de conectar.

  • Acesso ao SAP BTP Cockpit da subaccount do cliente
  • Uma instância SAP HANA Cloud criada no ambiente do cliente (plano hana ou equivalente contratado)
  • Modo padrão: usuário técnico HANA com senha e privilégios combinados para o schema do YNKX
  • Modo enterprise opcional: service key JSON + JWT/OAuth configurado no HANA com identity provider e user mapping
2

Descubra seu IP público

O HANA só aceita conexões de IPs liberados. Anote o seu.

curl -s https://api.ipify.org

Guarde no formato SEU_IP/32. Em cliente corporativo, use o IP público/NAT da rede ou do servidor onde o backend YNKX roda.

3

Confirme o "SAP HANA Cloud Tools"

É essa assinatura que libera o HANA Cloud Central — o painel onde se liga a instância e libera IP.

  1. BTP Cockpit → seu subaccount → Instances and Subscriptions
  2. Botão Create → Subscription
  3. Service: SAP HANA Cloud · Plan: tools
  4. Clique Create → status vira Subscribed
De acordo com a lista de planos da SAP: tools abre o painel; hana é o banco; hana-cloud-connection é só conexão database/data lake. Não use esse último como banco do YNKX. Plano free/trial é só para desenvolvimento ou homologação, não como referência comercial do manual.
4

Atribua a role de administrador (e relogue)

Só assinar o Tools não basta — a SAP manda atribuir a Role Collection ao seu usuário. Sem isso, o painel dá "Not authorized".

  1. BTP Cockpit → subaccount do cliente → Security → Users
  2. Clique no usuário que vai acessar o YNKX/HANA Central
  3. No painel da direita, em Role Collection, clique ... → Assign Role Collection
  4. Selecione SAP HANA Cloud Administrator
  5. Opcional, mas útil: selecione também SAP HANA Cloud Viewer e SAP HANA Cloud Security Administrator
  6. Clique Assign Role Collection para concluir
  7. Logout e login completo no BTP — a permissão só ativa no próximo login
Importante: esse é o procedimento oficial da SAP. A tela Role Collections → SAP HANA Cloud Administrator → Users também pode funcionar, mas se der confusão, volte para Security → Users e atribua a role collection por lá.
Se o plano tools não aparecer em Plan, falta entitlement na subaccount. A SAP também sugere o booster Set Up SAP HANA Cloud Administration Tools na página Boosters do global account.
5

Abra o SAP HANA Cloud Central

Enfim o lugar certo pra gerenciar o banco.

  1. Aba Subscriptions → clique em SAP HANA Cloud (Tools)
  2. Botão Go to Application (canto superior direito)
  3. Abre o painel com a instância SAP HANA Cloud do cliente e um status colorido
Se ainda abrir Not authorized, faça logout completo do BTP e entre de novo. Não basta atualizar a página.

Opcional: habilite Cloud Foundry para o botão "Iniciar instância" do YNKX

A conexão SQL não depende disso. O SaaS usa o CF CLI local apenas para mostrar org/space e acionar Start pelo app quando o usuário quiser.

Endpoint correto

Use o endpoint exibido em Subaccount → Overview → Cloud Foundry Environment.

https://api.cf.SUA_REGIAO.hana.ondemand.com
Se aparecer "No org or space targeted"

Não é erro do HANA. Faça login no endpoint certo e mire a org/space:

cf target -o SUA_ORG -s SEU_SPACE 
cf logout
cf api https://api.cf.SUA_REGIAO.hana.ondemand.com
cf login --sso
# Abra o link /passcode, escolha "default identity provider",
# copie o Temporary Authentication Code e cole no terminal.
cf target -o SUA_ORG -s SEU_SPACE
cf service SUA_INSTANCIA_HANA

Se der Invalid passcode, gere outro no link. O código expira rápido e só funciona uma vez.

6

Ligue a instância

A instância pode estar parada por política operacional, janela de manutenção ou economia de custo. Se estiver parada, ligue.

  • Bolinha cinza/Stopped → menu ⋯ → Start
  • Status Starting → não configure ainda; aguarde e atualize até virar Running
  • Bolinha verde/Running → já está no ar, siga adiante
Sintoma clássico de instância dormindo/IP bloqueado: erro -10709 "Socket closed by peer". Não é bug do seu código — é o HANA te derrubando na porta.
Se o YNKX conectar via usuário/senha, a conexão comercial já está pronta. Se estiver usando JWT/OAuth e aparecer "JWT aceito, mas o HANA não abriu", isso é progresso: credencial e role estão OK; falta RUNNING e allowlist.
7

Libere seu IP (allowlist)

Autoriza sua máquina a falar com o banco.

  1. Espere a instância estar Running; em Starting, a SAP bloqueia parte das abas
  2. Na instância → Manage Configuration
  3. Aba Connections ou Allowed Connections
  4. Add → cole SEU_IP/32 → Save

Pra testar rápido dá pra usar "Allow all IP addresses", mas reverta depois por segurança.

8

Configure o backend (.env)

Aponte o YNKX pra instância do cliente. Para onboarding comercial, use usuário técnico HANA. Para ambientes enterprise com SSO/mapeamento pronto, adicione JWT/OAuth.

# Modo padrão SaaS: usuário técnico HANA
HANA_HOST=xxxxx.hna1.prod-us10.hanacloud.ondemand.com
HANA_PORT=443
HANA_USER=USUARIO_TECNICO
HANA_PASSWORD=SENHA_FORNECIDA_PELO_CLIENTE
HANA_SCHEMA=YNKX_HANA

# Opcional enterprise: JWT/OAuth via service key
HANA_SERVICE_KEY=/caminho/cliente-hana-key.json
HANA_CF_INSTANCE=NOME_DA_INSTANCIA_HANA

No YNKX dá pra fazer isso pela própria tela Configuração SAP HANA: preencha host/usuário/senha/schema e salve. Se o cliente optar por JWT/OAuth, registre também a service key.

9

Teste a conexão real

O momento da verdade.

# Melhor caminho no app:
# Configuração SAP HANA -> Auto resolver

# Teste por terminal usando usuário/senha:
cd backend && ../.venv/bin/python -c "import config_service as cs; print(cs.test_connection())"

# Teste enterprise opcional usando JWT/OAuth:
cd backend && ../.venv/bin/python -c "import config_service as cs; print(cs.test_connection_jwt())"
Conectou {'ok': True, 'current_schema': 'YNKX_HANA'}
Socket closed by peer Volte ao passo 6 (Start) e 7 (IP)
Regra SaaS: se usuário/senha conectou, o cliente já pode usar. Se JWT/OAuth falhar com "No compatible authentication methods", falta mapeamento OAuth/JWT dentro do HANA; mantenha usuário técnico ou configure identity provider/user mapping com o time SAP do cliente.

Tabela rápida: erro apareceu, faz isso

SintomaCausa provávelCorreção
Not authorizedRole Collection faltando ou sessão antiga.Atribua SAP HANA Cloud Administrator em Security → Users e faça logout/login completo.
No org/space targetedCF logado, mas sem target.Use o endpoint correto e rode cf target -o ORG -s SPACE.
Invalid passcodeCódigo expirou ou já foi usado.Abra novamente o link /passcode, use default identity provider e cole o código imediatamente no terminal.
StartingBanco ligando.Espere virar Running. Durante Starting, Connections/Configuration podem ficar indisponíveis.
Socket closed by peerInstância parada ou IP bloqueado.Start na instância, aguarde Running e adicione o IP público em Allowed Connections.
Usuário/senha conectouOnboarding comercial OK.Salve a configuração e siga para migração das tabelas.
JWT não habilitado/mapeadoService key existe, mas o banco não aceita OAuth/JWT como login SQL.Use usuário técnico ou configure identity provider e user mapping no HANA.
JWT aceito, HANA não abriuKey e OAuth estão OK.Não mexa na key. Foque em Running + allowlist.
10

Prepare as tabelas do cliente no HANA

Cria/atualiza as tabelas do YNKX no schema configurado do cliente. Use seed apenas em desenvolvimento/homologação.

cd backend
../.venv/bin/python -m db.migrate up       # cria/atualiza as tabelas YNKX
../.venv/bin/python -m db.seed --reset     # opcional: dados demo/homologacao

Pronto — o YNKX agora gerencia dados de um cliente real dentro do HANA.

Conexão concluída!

Se o teste retornou ok: True, o SAP HANA Cloud do cliente está ligado ao YNKX. Se o cliente trocar IP/NAT, mover o backend ou parar a instância, repita Start + allowlist.

Copiado!