Problemi di SAP BTP Cockpit: cinque casi e come risolverli

Se SAP BTP Cockpit le restituisce errori, quasi certamente si tratta di una di cinque cause. Un 401 da una service key è quasi sempre la richiesta OAuth, non le credenziali. Un Internal Server Error su Integration Suite di solito indica role collection mancanti o una sessione scaduta. I link morti vengono da booster configurati prima che il subaccount cambiasse. I fallimenti delle destination CAP sono di solito un nome non corrispondente o un binding mancante. E un'app che funzionava ieri su un account trial può aver perso il database durante la notte. Questa guida è per sviluppatori e consulenti di integrazione che lavorano in subaccount Cloud Foundry. La tabella di triage qui sotto indica che cosa controllare per primo.

La prima volta che ho visto il banner rosso di errore in SAP BTP Cockpit, ho pensato di aver sbagliato qualcosa. Link sbagliato, sessione scaduta.

Dopo la terza o la quarta volta, era chiaro che non dipendeva solo da me.

Nelle settimane successive ho tenuto un quaderno e ho annotato ogni volta che qualcosa si rompeva. Internal Server Error all'apertura di Integration Suite. Destination che sembravano valide e rifiutavano di connettersi. App che funzionavano ieri e oggi si bloccavano. Sono emersi dei pattern. Pochi erano documentati in modo utile da qualche parte, e il Cockpit stesso non offre quasi nulla con cui lavorare.

Sintomo	Causa più probabile	Da controllare per primo
401 Unauthorized chiamando un'API con una service key	Grant type o token URL sbagliati, oppure authority mancanti	Decodifichi il token e legga aud e scope
Internal Server Error all'apertura di Integration Suite	Role collection mancanti o sessione scaduta	Le role collection del suo utente, poi un logout completo
Booster o tile aprono una pagina vuota o sbagliata	Il subaccount è cambiato dopo l'esecuzione del booster	Navighi dall'albero del Cockpit
App CAP: «destination not found» o errori di autenticazione	Nome non corrispondente, binding mancante, kind OData sbagliato	cds.requires e xs-app.json a confronto con il nome nel Cockpit
L'app funzionava ieri, oggi si blocca (trial)	Istanza HANA Cloud fermata durante la notte	Stato dell'istanza di database in SAP HANA Cloud Central

Cloud Foundry, Kyma e l'ambiente ABAP girano sulla base multi-cloud di SAP, che per i nuovi clienti è lo standard dal 2020. Il vecchio ambiente Neo riceve solo aggiornamenti di sicurezza e compliance, e SAP ne ha fissato il sunset al 31 dicembre 2028. Quasi tutti i problemi qui sotto sono problemi di Cloud Foundry.

Due cambi di nome confondono ancora chi legge guide più vecchie. Il servizio SAP Launchpad è diventato SAP Build Work Zone, standard edition, a gennaio 2023. E molte tile e molti booster sono stati ricostruiti con la crescita di SAP Build, quindi gli screenshot del 2022 spesso non corrispondono più a ciò che vede.

Su RISE with SAP, BTP di solito arriva come entitlement a crediti dentro il contratto. Il Cockpit è lo stesso. Cambia chi, nella sua organizzazione, controlla il global account, quindi trovi quella persona prima di avere bisogno di un nuovo entitlement.

Crea un'istanza di servizio, genera una service key, copia client ID e secret in Postman, aggiunge il token URL e invia la richiesta. 401. Nessun dettaglio.

Copia di nuovo il secret. Fallisce ancora. Il servizio è a posto. Il flusso OAuth no.

Che cosa controllare, in ordine:

1. Grant type. L'accesso tecnico alla maggior parte delle API dei servizi BTP usa client_credentials. Lo imposti esplicitamente in Postman. Non si fidi del default.
2. Token URL. Lo prenda dalla service key. Alcune key riportano un tokenurl; altre l'url di XSUAA, a cui si aggiunge /oauth/token. Non ne prenda mai uno da un altro subaccount.
3. Header. Per una chiamata diretta al token, invii Content-Type: application/x-www-form-urlencoded e Authorization: Basic <base64(clientid:clientsecret)>.
4. Authority. Con le client credentials, il token porta solo gli scope concessi a quell'istanza di servizio. Se l'API richiede un ruolo che l'istanza non ha, il token lo ottiene comunque, e l'API risponde comunque di no. Lo corregga nei parametri dell'istanza (per esempio, i ruoli su un'istanza del piano API di Integration Suite), non nella richiesta.
5. Audience. Se ha un token e l'API lo rifiuta, decodifichi il token e legga il claim aud. Se non corrisponde all'API che sta chiamando, sta usando una key dell'istanza di servizio sbagliata.

Apre Integration Suite e compare un banner rosso «Internal Server Error». Nessun log. Ricarica, cambia browser, stesso risultato.

Succede di solito dopo che il servizio è rimasto inutilizzato per un po': aperto al mattino, lasciato per qualche ora, usato di nuovo più tardi. I thread della community SAP e la knowledge base indicano due cause abituali: role collection mancanti e sessioni scadute.

Che cosa di solito risolve il problema:

1. Verifichi le role collection. Il suo utente ha bisogno di Integration_Provisioner per configurare il tenant e delle role collection PI_ pertinenti (administrator, integration developer, business expert) per lavorarci. Le assegni nel subaccount, sotto Security.
2. Esca completamente. Le modifiche ai ruoli arrivano alla sua sessione solo dopo un nuovo login. Chiuda tutte le schede di BTP e Integration Suite, esca e rientri.
3. Cancelli i cookie dei domini BTP se l'errore sopravvive a un nuovo login. Un cookie di sessione scaduto può sopravvivere alla sessione.
4. Usi una sola sessione del Cockpit. Più schede o profili del browser sullo stesso subaccount causano conflitti di sessione che assomigliano esattamente a questo errore.

Il vero problema è la visibilità. Il Cockpit non dice nulla su che cosa sia fallito, quindi si finisce a tirare a indovinare. Segua invece l'elenco in ordine. Per uno sguardo più ampio sul perché i programmi di integrazione si fermano, veda il mio articolo sui ritardi di consegna di SAP Integration Suite.

Clicca su «Go to Application» e ottiene una schermata vuota, una pagina di destinazione generica o un reindirizzamento privo di senso.

Segue dei pattern:

1. I link dei booster si rompono quando la configurazione del subaccount cambia dopo l'esecuzione del booster. Il reindirizzamento punta a qualcosa che non esiste più.
2. Le tile di Integration Suite a volte funzionano, a volte danno errore, a volte vanno in timeout, di solito per i motivi di sessione visti sopra.
3. I link di SAP Build Work Zone mostrano «connection denied» quando la subscription esiste ma il suo utente non ha la role collection per il sito.
4. Più schede o profili del browser aprono i link in contesti scaduti.

Che cosa funziona: navigare dall'albero del Cockpit (subaccount, poi Services, poi Instances and Subscriptions) e salvare tra i preferiti gli URL diretti di Integration Suite, delle destination e di Work Zone. Usare una sola sessione in un profilo del browser pulito. Quando un link fallisce una volta su tre, si smette di fidarsi della piattaforma e si comincia a costruire soluzioni di ripiego. I preferiti sono la soluzione di ripiego più economica che esista. Se sta ancora cercando di orientarsi, la mia guida al BTP Cockpit spiega la navigazione di base.

Distribuisce un'app CAP, configura una destination nel Cockpit, e le richieste continuano a fallire con «destination not found» o errori di autenticazione. La destination è elencata. L'app è in esecuzione. I messaggi di errore non portano da nessuna parte.

La documentazione CAP di SAP è chiara su come tutto va collegato: il servizio remoto viene dichiarato sotto cds.requires in package.json (o .cdsrc.json) con un kind, e il nome della destination va sotto credentials.destination. L'app ha inoltre bisogno di binding sia al servizio Destination sia a XSUAA. La maggior parte dei fallimenti è una rottura in qualche punto di questa catena.

1. 01cds.requiresDichiara il servizio remoto, il suo kind e il nome della destination
2. 02Profilo di produzioneContiene le credenziali della destination dopo il deployment
3. 03Service bindingL'app è associata a Destination e XSUAA
4. 04Destination nel CockpitStesso nome di cds.requires e xs-app.json, maiuscole incluse
5. 05Servizio remotoodata-v2 per un servizio V2, odata per V4

Le richieste raggiungono il servizio remoto

Sintomo	Soluzione
Destination elencata ma l'app non la trova	Confronti il nome in cds.requires e nelle route di xs-app.json con il Cockpit, carattere per carattere, maiuscole comprese
Funziona in locale, fallisce dopo il deployment	Verifichi che il profilo [production] contenga davvero le credenziali della destination e che l'app sia associata a Destination e XSUAA
Il servizio OData V2 remoto restituisce errori	Imposti kind su odata-v2 per un servizio V2 e su odata per V4. Usi V4 ovunque entrambe le parti lo consentano
Un'app UI5 richiede V2 ma il suo servizio CAP è V4	Aggiunga il plugin @cap-js-community/odata-v2-adapter. Il più vecchio @sap/cds-odata-v2-adapter-proxy è deprecato
L'autenticazione fallisce con credenziali valide	Parta da OAuth2ClientCredentials o BasicAuthentication. Usi SAML o la principal propagation solo quando lo scenario lo richiede
Non è sicuro che il target sia raggiungibile	Usi «Check Connection» sulla destination nel Cockpit prima di fare il debug dell'app

I team che gestiscono bene questo aspetto tengono una breve checklist delle destination per ogni app. Non perché la configurazione sia complessa. Perché un presupposto sbagliato su nome, binding o kind OData fallisce in silenzio e richiede molto più tempo a trovarsi che a prevenirsi.

Un'app CAP che funzionava ieri ora si blocca. Nessun errore. Il Cockpit la mostra in esecuzione. La riavvia. Niente.

Controlli prima il database. Il tutorial SAP su HANA Cloud trial afferma che le istanze free tier vengono fermate ogni notte e vanno riavviate ogni giorno in cui si lavora. L'account trial in sé dura fino a 90 giorni se si accede con regolarità. La sua app sta bene. Il suo database dorme.

Che cosa aiuta:

1. Riavvii l'istanza HANA Cloud da SAP HANA Cloud Central prima di cominciare a fare il debug del codice.
2. Usi la CLI (cf apps, cf services) per vedere memoria e uso dei servizi. L'interfaccia del Cockpit ne mostra molto meno.
3. Elimini le istanze di servizio inutilizzate prima di crearne di nuove. Le quote del trial valgono per l'intero account, non per una sola app.
4. Tenga i workload di demo e di test in subaccount separati.

Se ha bisogno di più di un'app e di un database in esecuzione in modo affidabile, o di un uptime stabile per le demo, passi a un account produttivo. I piani free tier in un account produttivo si possono passare a pagamento senza perdere il lavoro fatto, cosa che un account trial non permette.

Perché ottengo un errore 401 con le credenziali della service key di SAP BTP anche quando sembrano corrette?

Quasi sempre è la richiesta OAuth, non le credenziali. Le cause abituali sono il grant type sbagliato (usi client_credentials per l'accesso tecnico), un token URL che non corrisponde alla service key o header sbagliati nella chiamata al token.

Se ottiene un token e l'API lo rifiuta comunque, lo decodifichi. Verifichi che il claim aud corrisponda all'API e controlli gli scope. Con le client credentials, gli scope derivano dalle authority concesse all'istanza di servizio, quindi corregga i ruoli mancanti nei parametri dell'istanza.

Che cosa causa gli Internal Server Error all'apertura di Integration Suite in BTP Cockpit?

Più spesso role collection mancanti o una sessione scaduta. Si assicuri che il suo utente abbia Integration_Provisioner e le role collection PI_ che le servono. Poi chiuda tutte le schede di BTP, esca e rientri, perché i nuovi ruoli si applicano solo dopo un nuovo login.

Se il problema persiste, cancelli i cookie dei domini BTP e si limiti a una sola sessione del Cockpit. Più schede sullo stesso subaccount provocano lo stesso errore.

Perché la mia app CAP non riesce a collegarsi a una destination che nel Cockpit appare corretta?

Di solito è un nome non corrispondente. Il nome della destination in cds.requires e nelle route di xs-app.json deve coincidere con quello del Cockpit esattamente, maiuscole comprese.

Se il nome è giusto, verifichi che l'app sia associata sia al servizio Destination sia a XSUAA, che il profilo [production] contenga le credenziali e che il kind corrisponda al servizio remoto: odata-v2 per V2, odata per V4. Usi «Check Connection» nel Cockpit per confermare che il target sia raggiungibile.

Perché la mia app trial su SAP BTP smette di funzionare di notte?

Nei piani trial e free tier, le istanze SAP HANA Cloud vengono fermate ogni notte per risparmiare risorse. La sua app continua a girare ma non raggiunge il database. Riavvii l'istanza in SAP HANA Cloud Central ogni giorno prima di lavorare.

Usi cf apps e cf services per controllare memoria e uso dei servizi, perché le quote del trial sono difficili da vedere nel Cockpit. Elimini le istanze inutilizzate prima di crearne di nuove.

Perché i link dentro booster e tile portano a pagine vuote?

I link dei booster si rompono quando la struttura del subaccount cambia dopo l'esecuzione del booster. Il reindirizzamento punta a una posizione che non esiste più o che non è mai stata configurata del tutto.

Navighi dall'albero del Cockpit e salvi tra i preferiti gli URL diretti di Integration Suite, delle destination e di SAP Build Work Zone. Non faccia affidamento sulla navigazione generata dai booster per ciò che usa ogni giorno.

Quando conviene passare da un account trial BTP a un piano a pagamento?

Quando i limiti cominciano a costarle tempo. Se esegue più di un'app o di un database, o ha bisogno di un uptime stabile per demo o test, il trial crea più attrito di quanto ne faccia risparmiare.

I vantaggi principali sono stabilità e una visibilità più chiara delle risorse, non nuove funzionalità. Un account produttivo con piani free tier è un buon passo intermedio: quei piani si possono passare a pagamento in seguito senza ricostruire nulla.