Panoramica dell'API SoftLayer

L'API (Application Programming Interface) di SoftLayer è l'interfaccia di sviluppo che dà agli sviluppatori e agli amministratori di sistema un'interazione diretta con il sistema di backend di SoftLayer. La funzionalità esposta dalla nostra API consente agli utenti di eseguire il monitoraggio e la gestione in remoto di server e di richiamare informazioni dai diversi sistemi di SoftLayer come contabilità, inventario e DNS. La nostra API supporta molte delle funzioni nel portale clienti SoftLayer, il che di solito significa che, se possibile nel portale clienti, un'interazione può essere eseguita anche nella nostra API.

Chi dovrebbe utilizzare la API?

La SLAPI (SoftLayer API) è disponibile per tutti i clienti SoftLayer senza costi aggiuntivi. Invitiamo i nostri clienti con una conoscenza di base della programmazione orientata agli oggetti ad avvalersi appieno delle funzionalità offerte dalla SLAPI. Anche se i clienti SoftLayer utilizzano la SLAPI per diverse attività, la capacità di interagire a livello di programmazione con tutte le parti dell'ambiente SoftLayer all'interno dell'API fa sì che la maggior parte dei clienti utilizzi la SLAPI per automatizzare le attività.

Utilizzo dell'API SoftLayer

Prima di iniziare

La SLAPI offre agli utenti un'interazione diretta con gli oggetti sui quali si basa il portale clienti. Prima di eseguire attività di sviluppo per la SLAPI, sarà estremamente proficuo comprendere i concetti di programmazione orientata agli oggetti quali oggetti, proprietà, metodi ed eredità. I metodi di SLAPI vengono eseguiti sugli oggetti servizio nei nostri sistemi di backend, che restituiscono sia oggetti tipo di dati specifici per SoftLayer sia tipi di dati standard come numeri interi, booleani e stringhe.
La SLAPI è un sistema RPC (Remote Procedure Call). Ogni chiamata comporta l'invio di dati verso un endpoint API e la ricezione in risposta di dati strutturati. Il formato utilizzato per inviare e ricevere dati con la SLAPI dipende da quale implementazione dell'API scegli. La SLAPI attualmente utilizza SOAP, XML-RPC o REST, per la trasmissione di dati. Prima di effettuare chiamate API, è utile comprendere come utilizzare questi protocolli nel tuo linguaggio di programmazione o di creazione di script. Puoi utilizzare qualsiasi implementazione nella tua applicazione. Abbiamo anche fornito diversi client API specifici per un servizio, disponibili in una gamma dei nostri linguaggi supportati sul nostro profilo github.

Creazione di un utente API

Ogni chiamata alla SLAPI è autenticata da un account del portale clienti. Gli account sul portale clienti possono contenere più utenti e consigliamo vivamente di creare un utente del portale clienti univoco per eseguire le chiamate API. Indipendentemente dal fatto che tu stia sviluppando un'applicazione oppure utilizzando un'applicazione basata sull'API sviluppata da altri, devi eseguire l'autenticazione all'interno del tuo programma per accedere alle informazioni su tutti gli aspetti del tuo account e per interagire con essi. L'autenticazione presso la SLAPI richiede il tuo nome utente del portale clienti e la chiave API, un token di autenticazione speciale riservato per le chiamate di metodi API. Le autorizzazioni utente definite nel portale clienti sono riflesse nelle chiamate API.

Scelta della rete pubblica o privata

I server endpoint SLAPI esistono nelle reti pubbliche e private di SoftLayer. Le tue applicazioni basate sull'API possono connettersi da qualsiasi host su Internet; tuttavia, la rete privata di SoftLayer offre un livello supplementare di protezione dei dati. Inoltre, SoftLayer offre diversi endpoint API di rete privata, che sono accessibili solo quando si è connessi alla rete privata. Tutti i server e tutte le istanze di elaborazione associati a un account SoftLayer hanno una connessione diretta alla rete privata e non richiedono un'ulteriore autenticazione. Se desideri utilizzare degli endpoint privati da un altro dispositivo, è richiesta una connessione VPN nella nostra rete privata.

Concetti API di base

Servizi

Un servizio è un endpoint associati ai sistemi SoftLayer interni. Ogni servizio è una raccolta di metodi, o azioni, che è possibile eseguire. Un elenco di tutti i servizi SLAPI è disponibile nella sezione Riferimento di questo sito.
Quando si accede alla sezione Servizi per l'API desiderata, sul lato sinistro dello schermo viene visualizzato un elenco di tutti i servizi disponibili. Tutti i servizi SoftLayer iniziano con "SoftLayer_" e contengono dei termini aggiuntivi che definiscono la funzione generale fornita dal
servizio: "Hardware", "Account", "Billing", "Network", ecc. Ogni servizio continua poi con un nome che definisce la sua funzione specifica
all'interno di quello specifico sottoinsieme. Ogni servizio associato all'API SoftLayer ha un nome univoco. Anche se alcuni servizi, come SoftLayer_Account e SoftLayer_Account_Address, possono condividere un prefisso comune, la loro interazione non è necessariamente simile e non c'è alcuna eredità diretta per
i servizi con un nome analogo. Per tale ragione, ci si deve approcciare a ogni servizio separatamente.
Per visualizzare i dettagli per uno specifico servizio, fare clic sul relativo nome. La pagina di ogni servizio include un elenco di metodi per esso disponibili e, in molti casi, è inclusa anche una breve panoramica per spiegarlo. Anche se ogni servizio offre un set univoco di metodi, molti servizi offrono il metodo getObject. Questi metodi possono essere utilizzati per richiamare un oggetto dello stesso tipo dall'API. Ad esempio, il richiamo del metodo getObject sul servizio SoftLayer_Network_Subnet restituirà un oggetto tipo di dati SoftLayer_Network_Subnet.

Metodi

Un metodo è un'azione specifica che può essere eseguita per un servizio SLAPI. Ogni metodo restituisce un tipo di dati scalare o strutturato e, per l'esecuzione, può richiedere delle intestazioni, delle autorizzazioni o dei parametri specifici. I parametri del metodo devono essere passati utilizzando le tecniche descritte nella documentazione di ciascun linguaggio o endpoint. Nelle situazioni in cui sono richiesti più parametri, passarli nell'ordine in cui si presentano nella pagina Metodo, dall'alto verso il basso. La schermata qui di seguito visualizza i parametri richiesti per il metodo SoftLayer_Monitoring_Agent::getGraph. Quando si esegue questo metodo, passare i parametri nel seguente ordine: configurationValues, beginDate, endDate.
NOT FOUND: parameters.png
In ciascuna pagina Metodo è disponibile un elenco completo di parametri, autorizzazioni e intestazioni.

Tipi di dati

Un tipo di dati è una struttura e contiene una raccolta di valori scalari e altri tipi di dati. Oltre ai tipici valori scalari quali string, bool o int, la SLAPI utilizza anche tipi di dati complessi che contengono proprietà che definiscono gli oggetti passati ai, e restituiti dai, metodi nella SLAPI. Ogni tipo di dati contiene, potenzialmente, diverse proprietà locali, relazionali e di conteggio.

Proprietà locali

Una proprietà locale è un elemento child diretto di un tipo di dati. Le proprietà locali vengono di norma restituite quando viene richiamato getObject(). Quando si crea un'istanza di questo tipo di dati quando si richiama createObject(), sono richieste alcune proprietà locali, se non tutte.

Proprietà relazionali

Una proprietà relazionale è un elemento child indiretto di un tipo di dati. Le proprietà relazionali sono definite in altri tipi di dati o nelle loro proprietà. Ad esempio, il tipo di dati SoftLayer_Account ha una proprietà relazionale per hardware. La proprietà relazionale è un array di tipi di dati SoftLayer_Hardware. Quando ne viene eseguito il tapping con una maschera oggetto, questa proprietà restituirà un array che contiene un oggetto SoftLayer_Hardware per ogni dispositivo hardware sull'account.

Proprietà di conteggio

Una proprietà di conteggio è una proprietà offerta per tua comodità che può essere utilizzata per determinare il numero totale di oggetti associato a una proprietà. Possiamo ad esempio richiamare il numero totale di VLAN associate a uno specifico server utilizzando una maschera oggetto che includeva Softlayer_Hardware_Server->networkVlanCount.

Concetti API avanzati

Oltre alle tipiche azioni di creazione, lettura, aggiornamento ed eliminazione, la SLAPI consente agli sviluppatori di definire in che modo vengono restituiti i dati da ciascuna chiamata mediante l'uso di intestazioni di chiamata API speciali. Tali intestazioni consentono un livello di controllo aggiuntivo sulla quantità di dati restituita dall'API.

Limiti dei risultati

Un limite dei risultati è un metodo di supporto che consente di definire un offset e la quantità per gli oggetti da restituire. Questo consente di impaginare dataset di grandi dimensioni.

Maschere oggetto

Una maschera oggetto consente all'utente di specificare quali proprietà locali restituire da un metodo e di richiamare le informazioni rilevate sia nelle proprietà relazionali che in quelle di conteggio. Una mappa, o "maschera" viene creata per definire gli specifici dati da includere nel valore restituito. Ad esempio, è possibile raccogliere gli ID per ciascuna VLAN o unSoftLayer_Hardware_Server specificando una maschera oggetto per "networkVlans.id" quando si richiama SoftLayer_Hardware_Server::getObject.

Parte dell'arte di padroneggiare la SLAPI consiste nello spostarsi nelle maschere oggetto per ottenere i risultati desiderati. Il più delle volte, c'è più di un modo per raggiungere uno specifico punto dati e alcuni possono essere più efficienti di altri.

Con cosa proseguire

Ora che conosci le basi, è tempo di iniziare a scrivere codice. Per le procedure per creare un utente API e fare la tua prima chiamata, consulta la nostra guida introduttiva. Provvediamo anche a fornire diverse guide per specifici linguaggi:

Altri link utili: