Questo articolo spiega come un'organizzazione multitenant può ottenere tramite API le informazioni sulle istanze che gestisce: validità della licenza, componenti contrattati, utenti contrattati e attivi, data dell'ultima campagna avviata, tipo di organizzazione e settore.
A cosa serve
La sezione Gestione delle istanze consente di visualizzare l'inventario delle organizzazioni dalla piattaforma. L'endpoint Managed instances offre le stesse informazioni in modo automatizzato, pensato per i casi in cui un sistema esterno deve utilizzarle. Ad esempio:
- Una dashboard che mostra lo stato di tutte le istanze in un unico punto.
- Un processo che avvisa delle licenze in scadenza.
- Un controllo periodico che confronta gli utenti attivi con gli utenti contrattati.
- Il monitoraggio delle istanze che non hanno avviato campagne di recente.
Se cerca la gestione delle istanze dalla piattaforma, consulti Multitenant.
Prima di iniziare
- Verifichi che la Sua organizzazione gestisca delle istanze. L'endpoint è disponibile solo per le organizzazioni multitenant che gestiscono istanze.
- Registri un'applicazione in Configurazione > Integrazioni > Applicazioni registrate selezionando l'ambito read_managed_instances. La procedura completa è descritta in Integrazione delle API in SMARTFENSE.
- Ottenga un access token con il flusso Authorization code o Client Credentials. Entrambi sono supportati da questo endpoint.
Nota: l'ambito read_managed_instances viene offerto solo alle organizzazioni che gestiscono istanze. Se non lo vede durante la registrazione dell'applicazione, la Sua organizzazione non ha istanze gestite associate.
Consultare le istanze
GET /api/v1/organization/managed-instances
Il percorso è relativo all'URL della Sua istanza. Includa il token nell'intestazione Authorization della richiesta:
curl -X GET "https://nometenant.takesecurity.com/api/v1/organization/managed-instances" \ -H "Authorization: Bearer <access_token>"
Dove nometenant corrisponde al nome della Sua istanza.
La risposta include le istanze gestite a qualsiasi livello della gerarchia, sia attive sia disattivate.
Parametri di query
Tutti i parametri sono facoltativi e possono essere combinati.
| Parametro | Tipo | Descrizione |
|---|---|---|
| name | string | Restituisce solo le istanze il cui nome contiene questo testo. Non distingue tra maiuscole e minuscole. |
| page | integer | Numero della pagina da consultare. Valore predefinito: 1. |
| page_size | integer | Numero di record per pagina. Valore predefinito: 50. Valore massimo: 50. |
| validity_end_date_before | string (data) | Restituisce solo le istanze la cui validità termina in questa data o prima. Formato: YYYY-MM-DD. |
Esempio: istanze la cui licenza scade entro il 31 dicembre 2026.
GET /api/v1/organization/managed-instances?validity_end_date_before=2026-12-31
Risposta
La risposta è paginata e viene fornita in formato application/json:
{
"count": 123,
"next": "https://nometenant.takesecurity.com/api/.../?page=4",
"previous": "https://nometenant.takesecurity.com/api/.../?page=2",
"results": [
{
"name": "string",
"url": "http://example.com",
"active": true,
"validity_start_date": "2019-08-24",
"validity_end_date": "2019-08-24",
"contracted_users": 0,
"active_users": 0,
"last_campaign_launched_at": "2019-08-24T14:15:22Z",
"company_type": { ... },
"sector": { ... },
"components": [ ... ]
}
]
}- count: numero totale di istanze che soddisfano i filtri.
- next e previous: URL della pagina successiva e precedente. Le utilizzi per scorrere tutti i risultati.
- results: elenco delle istanze della pagina consultata.
Campi di ogni istanza
| Campo | Tipo | Descrizione |
|---|---|---|
| name | string | Nome dell'istanza. |
| url | string (URI) | Indirizzo con cui si accede all'istanza. |
| active | boolean | Indica se l'istanza è attiva. |
| validity_start_date | data o null | Data di inizio validità della licenza. È nulla se non è stata caricata. |
| validity_end_date | data | Data di fine validità della licenza. |
| contracted_users | integer | Numero di utenti contrattati. |
| active_users | integer | Numero di utenti attivi in questo momento. Vengono conteggiati come nelle informazioni sulla licenza, per poterli confrontare con quelli contrattati. |
| last_campaign_launched_at | data e ora o null | Data e ora di inizio dell'ultima campagna avviata, di qualsiasi componente. È nulla se l'istanza non ha mai avviato una campagna. |
| company_type | oggetto | Tipo di organizzazione. |
| sector | oggetto o null | Settore dell'organizzazione. È nullo se non è stato caricato. |
| components | array di oggetti | Componenti contrattati. |
Importante: company_type, sector e ogni elemento di components vengono riportati con un codice stabile e il loro nome nella lingua dell'organizzazione. Utilizzi il codice per automatizzare i processi e il nome solo per visualizzare le informazioni.
Come viene calcolata l'ultima campagna avviata
Il campo last_campaign_launched_at segue queste regole:
- Non conteggia le campagne di prova.
- Non conteggia le campagne programmate per una data successiva.
- Un itinerario conta come una sola campagna.
- Riporta la data in cui la campagna è iniziata, non quella dell'ultima email inviata.
Codici di risposta
| Codice | Significato |
|---|---|
| 200 | Richiesta completata correttamente. |
| 400 | Uno dei filtri non ha un valore valido. |
| 401 | Non è stato fornito un token di accesso, oppure il token non è valido o è scaduto. |
| 403 | Il token non dispone dell'ambito richiesto, oppure l'organizzazione non ha istanze gestite disponibili da consultare. |
| 429 | È stato superato il limite di richieste consentite. Riprovi dopo il tempo indicato nell'header Retry-After. |
Nota: se riceve un 400 filtrando per data, verifichi che validity_end_date_before rispetti il formato YYYY-MM-DD.
💡 Best practice
- Registri un'applicazione dedicata a questa integrazione, con read_managed_instances come unico ambito se non ne servono altri.
- Scorra tutte le pagine seguendo il campo next finché non è nullo. Il massimo per pagina è di 50 istanze.
- Utilizzi validity_end_date_before per individuare in anticipo le licenze in scadenza.
- Confronti active_users con contracted_users per identificare le istanze vicine al limite della licenza.
- Controlli last_campaign_launched_at per individuare le istanze senza attività recente.
- Utilizzi il codice del tipo di organizzazione, del settore e dei componenti nei processi automatici. Il nome può cambiare in base alla lingua di ciascuna organizzazione.
- In caso di 429, attenda il tempo indicato in Retry-After prima di riprovare.