Guida pratica: Autenticazione tramite l'API

Modifica online

Obiettivo: ottenere un token di autenticazione per effettuare richieste API autorizzate

Tempo stimato: 15-30 minuti (configurazione iniziale)

Quando utilizzarlo: prima di qualsiasi operazione di caricamento o download. Per tutte le chiamate API sono richiesti dei token.

Prerequisiti

  • Un account utente in "Amministrazione accessi avanzata" con accesso alle API
  • Chiavi API generate e autorizzate per l'accesso al tuo ambiente di destinazione
  • Accesso alla rete tramite frontdoor.apptio.com

Autorizzazioni richieste

Per le operazioni di caricamento, il tuo account deve:

  • AccessDev
  • UploadData

Per le operazioni di download, il tuo account deve:

  • AccessProd, AccessStg
  • AllDataView, DrillDown
  • ViewMetricReports, ViewObjectReports, ViewTransformReports, ViewTransparencyReports, ViewUnitReports
  • ViewReportsSavedForEveryone
Suggerimento: alcune autorizzazioni di visualizzazione potrebbero non essere necessarie a seconda dei prodotti installati e dei tipi di dati scaricati. In caso di dubbio, verifica la tua configurazione.

Metodo 1: Autenticazione tramite chiavi API (consigliato)

Le chiavi API rappresentano il metodo di autenticazione preferito per motivi di sicurezza. Consentono un controllo degli accessi dettagliato e possono essere revocate senza modificare le password degli utenti.

Passaggio 1: Generare le chiavi API nella sezione "Amministrazione dell'accesso avanzato"

  1. Accedi alla gestione dell'accesso avanzato
  2. Accedi alle impostazioni del tuo account utente
  3. Genera una nuova coppia di chiavi API (pubblica e segreta)
  4. Fai clic su «Concedi accesso» accanto al nome della chiave per autorizzare l'accesso all'ambiente
  5. Conserva la chiave segreta in un luogo sicuro: una volta creata, non potrà più essere recuperata

Fase 2: Richiedi un token di autenticazione

cURL:
curl -X POST https://frontdoor.apptio.com/service/apikeylogin \
 -H "Content-Type: application/json" \
 -H "Accept: application/json" \
 -d '{"keyAccess":"YOUR_PUBLIC_KEY","keySecret":"YOUR_SECRET_KEY"}'
Python:
import requests
import json
 
def get_auth_token(public_key, secret_key):
 """Authenticate with TBM Studio API using API keys."""
 url = "https://frontdoor.apptio.com/service/apikeylogin"
 headers = {
 "Content-Type": "application/json",
 "Accept": "application/json"
 }
 payload = {
 "keyAccess": public_key,
 "keySecret": secret_key
 }
 
 response = requests.post(url, headers=headers, json=payload)
 response.raise_for_status()
 
 # Token is returned in cookies
 token = response.cookies.get('apptio-opentoken')
 return token
 
# Usage
token = get_auth_token("your_public_key", "your_secret_key")

Passaggio 3: Ottieni il tuo ID ambiente

L'ID dell'ambiente è necessario per le successive chiamate API. Rimane invariato a meno che non si modifichi la configurazione dell'amministrazione dell'accesso avanzato.

curl -X GET "https://frontdoor.apptio.com/api/environment/yourdomain.com/main" \
 -H "Content-Type: application/json" \
 -H "apptio-opentoken: YOUR_TOKEN"
Python:
def get_environment_id(token, domain, frontdoor_env="main"):
 """Get the environment ID for API calls."""
 url = f"https://frontdoor.apptio.com/api/environment/{domain}/{frontdoor_env}"
 headers = {
 "Content-Type": "application/json",
 "apptio-opentoken": token
 }
 
 response = requests.get(url, headers=headers)
 response.raise_for_status()
 
 return response.json()["id"]
 
# Usage
env_id = get_environment_id(token, "yourdomain.com")

Metodo 2: Autenticazione tramite nome utente/password

Avviso: l'autenticazione tramite nome utente e password è supportata, ma non è consigliata per i sistemi di produzione. Quando possibile, utilizza le chiavi API per garantire una maggiore sicurezza.
cURL:
curl -X POST https://frontdoor.apptio.com/service/apikeylogin \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"userId":"user@domain.com","password":"your_password"}'
Python:
def get_auth_token_password(user_id, password):
    """Authenticate using username and password."""
    url = "https://frontdoor.apptio.com/service/apikeylogin"
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
    payload = {
        "userId": user_id,
        "password": password
    }
    
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
    
    return response.cookies.get('apptio-opentoken')

Risultati attesi

  • Se l'autenticazione va a buon fine, nei cookie di risposta viene restituito un apptio-opentoken
  • L'endpoint dell'ID ambiente restituisce una risposta JSON contenente l'ID numerico dell'ambiente
  • Entrambi i valori sono obbligatori per tutte le operazioni API successive

Errori comuni

  • Accesso all'ambiente non concesso alla chiave: dopo aver creato una chiave API, è necessario concederle esplicitamente l'accesso agli ambienti tramite il link "Concedi accesso".
  • Autorizzazioni mancanti: assicurarsi che sia assegnata l'autorizzazione " UploadData ".
  • Scadenza dei token: i token di autenticazione scadono. Implementare la logica di aggiornamento dei token nei processi di lunga durata.