Visual Basic .NET

Utilizzo di WSDL SOAP

I WSDL API di SoftLayer possono essere importati nel tuo progetto in due modi. Visual Studio può utilizzare un servizio SOAP in un riferimento web accessibile dal tuo progetto. Visual Studio è anche dotato di un programma di utilità denominato wsdl.exe che viene eseguito da un prompt dei comandi per leggere uno o più file WSDL e convertirli direttamente in codice sorgente che puoi aggiungere al tuo progetto. I servizi web sono di solito più facili da usare in Visual Studio, ma possono diventare scomodi da gestire se il tuo progetto utilizza molti servizi API SoftLayer. Wsdl.exe è utile se il tuo progetto richiede molti servizi API.

Gli esempi di codice nel presente articolo riflettono il codice generato dai servizi API SoftLayer da wsdl.exe.

Creazione di riferimenti web

  1. Fai clic sul menu Progetto in Visual Studio.
  2. Seleziona Aggiungi riferimento al servizio dall'elenco a discesa del menu Progetto.
  3. Fai clic sul pulsante Avanzate nella finestra Aggiungi riferimento al servizio.
    Nota: verrà visualizzata la finestra Impostazioni riferimento al servizio.
  4. Fai clic sul pulsante Aggiungi riferimento Web nella finestra Impostazioni riferimento al servizio.
  5. Immetti l'URL al WSDL del servizio API SoftLayer che desideri utilizzare nel campo URL.
  6. Fai clic sulla freccia verde a destra del campo URL.
    Nota: Visual Studio scaricherà il file WSDL e analizzerà i metodi e i tipi di dati che contiene.
  7. Immetti un nome per il nuovo riferimento web nel campo Nome riferimento Web.
    Nota: questo nome verrà utilizzato per tutti i riferimenti al servizio API aggiunto al progetto.
  8. Fai clic sul pulsante Aggiungi riferimento per importare il tuo nuovo servizio web.
    Nota: verrai riportato al tuo progetto e il tuo nuovo servizio API sarà visibile in Esplora soluzioni di Visual Studio.

Utilizzo di wsdl.exe

Wsdl.exe è disponibile in C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\ e deve essere eseguito con i seguenti switch per convertire i WSDL API di SoftLayer in codice Visual Basic:

  • /language:VB - indica a wsdl.exe di esportare codice Visual Basic .NET.
  • /sharetypes - i file WSDL di SoftLayer condividono vari tipi di dati simili. Lo switch /sharetypes compila questi tipi di dati in singoli file di classe, con una conseguente riduzione dell'ingombro del codice sorgente e un aumento dell'efficienza quando si lavora in Visual Studio.
  • /out:C:\path\to\project\SoftLayer_API.vb - esporta il codice generato in un percorso all'interno della gerarchia del tuo progetto. In questo caso, salveremo il codice in fileSoftLayer_API.vb.

Termina il comando con un elenco separato da spazi degli URL dei WSDL API che desideri importare. Puoi importare tutti i file WSDL che vuoi.

wsdl.exe /language:VB /out:"C:\Path\to\Project\SoftLayer_API.vb" /sharetypes 
https://api.softlayer.com/soap/v3/SoftLayer_Account?wsdl 
https://api.softlayer.com/soap/v3/SoftLayer_Hardware_Server?wsdl 
https://api.softlayer.com/soap/v3/SoftLayer_Dns_Domain?wsdl

Nota: per effettuare delle chiamate API private, al posto di https://api.softlayer.com
metti http://api.service.softlayer.com. Per ulteriori informazioni
sull'effettuazione di chiamate API private, consulta il nostro articolo Introduzione.

Esegui nuovamente questo comando se desideri importare ulteriori servizi API nel tuo progetto.

Dopo che il file di codice è stato creato, devi aggiungerlo al tuo progetto.

  1. Fai clic con il pulsante destro del mouse sul nome del tuo progetto in Esplora soluzioni di Visual Studio.
  2. Vai all'opzione Aggiungi nel menu espanso.
  3. Fai clic sul pulsante Elemento esistente nel menu Aggiungi.
  4. Individua il tuo file di codice generato nella finestra di dialogo Aggiungi elemento esistente.
  5. Fai clic per evidenziare il tuo file di codice generato.
  6. Fai clic sul pulsante OK per continuare.

Infine, il tuo progetto deve includere il riferimento al servizio System.Web.Services per effettuare chiamate SOAP dal tuo codice importato.

  1. Fai clic per espandere il menu Progetto in Visual Studio.
  2. Seleziona Aggiungi riferimento.
  3. Fai clic sulla scheda .NET.
  4. Seleziona System.Web.Services
  5. Fai clic sul pulsante OK per aggiungere il riferimento al tuo progetto.

Ora puoi utilizzare gli oggetti API di SoftLayer come oggetti locali nel tuo progetto.

Effettuazione di chiamate API

Creazione di oggetti servizio

A ogni servizio API nel tuo progetto è associata una classe di servizio responsabile dell'effettuazione delle chiamate API. Le classi di servizio sono denominate in base al servizio API che si desidera richiamare. Ad esempio, il nome classe per il servizio API SoftLayer_Account è SoftLayer_AccountService e il nome classe per il servizio SoftLayer_Hardware_Serverservice è SoftLayer_Hardware_ServerService. Gli oggetti servizio hanno delle proprietà corrispondenti alle funzioni API quali l'autenticazione, i parametri di inizializzazione, le maschere oggetto e i limiti dei risultati. Anche le chiamate di metodo API vengono effettuate direttamente su tali oggetti.

Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()

Associazione dell'autenticazione

Autentica le tue chiamate API con il tuo nome utente e la tua chiave API definendo un oggetto authenticate. Imposta le proprietà username e apiKey dell'oggetto di autenticazione sul tuo nome utente e sulla tua chiave API. Associa l'oggetto di autenticazione al tuo oggetto servizio API impostandone la proprietà authenticateValue sul tuo oggetto di autenticazione.

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
accountService.authenticateValue = authenticate

Impostazione dei parametri di inizializzazione

Anche i parametri di inizializzazione (init) di chiamate API hanno delle classi definite che corrispondono al servizio API che stai richiamando. Le classi di parametro init sono denominate in base al servizio API che stai richiamando. Ad esempio, il nome della classe di parametro init per il servizio SoftLayer_Account è SoftLayer_AccountInitParameters e il nome della classe di parametro init per il
servizio SoftLayer_Hardware_Server è SoftLayer_Hardware_ServerInitParameters. Gli oggetti parametro init hanno ciascuno una proprietà id di tipo numero intero singolo corrispondente al numero id dell'oggetto SoftLayer di cui vuoi eseguire la query. Associa il tuo oggetto parametro init impostandolo sulla proprietà InitParameterValue del tuo oggetto servizio, dove corrisponde al servizio API che stai richiamando.
Se la chiamata API non corrisponde a uno specifico oggetto SoftLayer, non hai bisogno di associare un valore di parametro di inizializzazione al tuo oggetto servizio.

Dim serverId As Integer = 1234
 
Dim hardwareServerInitParameters As SoftLayer_Hardware_ServerInitParameters = New SoftLayer_Hardware_ServerInitParameters()
hardwareServerInitParameters.id = serverId
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters

Effettuazione della chiamata API

Quando l'oggetto servizio è pronto, effettua la tua chiamata del metodo API direttamente sull'oggetto servizio. L'esempio di seguito riportato descrive l'effettuazione della chiamata API.

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
' Initialize the SoftLayer_Account API service.
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
Dim account as SoftLayer_Account = accountService.getObject()
 
 
' Work directly with the SoftLayer_Hardware_Server record with the 
' hardware id 1234.
Dim serverId As Integer = 1234
 
Dim hardwareServerService As SoftLayer_Hardware_ServerService = New SoftLayer_Hardware_ServerService()
hardwareServerService.authenticateValue = authenticate
 
Dim hardwareServerInitParameters As SoftLayer_Hardware_ServerInitParameters = New SoftLayer_Hardware_ServerInitParameters()
hardwareServerInitParameters.id = serverId
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters
 
Dim server as SoftLayer_Hardware_Server = hardwareServerService.getObject()

Il codice importato nel tuo progetto definisce le classi per ogni tipo di dati definito nell'API SoftLayer. Istanzia i nuovi oggetti tipo di dati come necessario come parametri della chiamata o come risultati della chiamata.

Dim username As String = "set me"
Dim apiKey As String = "set me"
Dim domainId As Integer = 1234
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim domainService As SoftLayer_Dns_DomainService = New SoftLayer_Dns_DomainService()
domainService.authenticateValue = authenticate
 
Dim domainInitParameters As SoftLayer_Dns_DomainInitParameters = New SoftLayer_Dns_DomainInitParameters()
domainInitParameters.id = domainId
domainService.SoftLayer_Dns_DomainInitParametersValue = domainInitParameters
 
' Create a new A record in a domain.
Dim newRecord As SoftLayer_Dns_Domain_ResourceRecord_AType = domainService.createARecord("myhost", "127.0.0.1", 86400)
Console.WriteLine("New A record id: " + newRecord.id.toString())
 
 
' Create a new domain record.
'
' This requires a null init parameter and a single SoftLayer_Dns_Domain
' object defined.
domainService.SoftLayer_Dns_DomainInitParametersValue = Nothing
 
Dim domain As SoftLayer_Dns_Domain = New SoftLayer_Dns_Domain()
Dim domainResourceRecords As SoftLayer_Dns_Domain_ResourceRecord_AType() = {New SoftLayer_Dns_Domain_ResourceRecord_AType()}
domainResourceRecords(0).host = "@"
domainResourceRecords(0).data = "127.0.0.1"
domainResourceRecords(0).type = "a"
domain.name = "example.org"
domain.resourceRecords = domainResourceRecords
 
Dim newDomain As SoftLayer_Dns_Domain = domainService.createObject(domain)
Console.WriteLine("New A record id: " + newDomain.id.toString())

Utilizzo delle maschere oggetto

Associa una maschera oggetto alle tue chiamate API dichiarando un oggetto maschera oggetto. I nomi classe di maschera oggetto corrispondono al servizio API che stai usando, iniziando con il nome del tuo servizio API seguito da "ObjectMask". Ad esempio, una maschera oggetto per il servizio API SoftLayer_Account ha il nome classe SoftLayer_AccountObjectMask e il nome classe di maschera oggetto corrispondente del servizio SoftLayer_Hardware_Server è SoftLayer_Hardware_ServerObjectMask.

Ogni classe di maschera oggetto ha una proprietà mask che modella i dati relazionali che desideri richiamare. La proprietà mask è un oggetto del tipo dati rappresentato dal tuo servizio API. Ad esempio, SoftLayer_AccountObjectMask.mask è un oggettoSoftLayer_Account e SoftLayer_Hardware_ServerObjectMask.mask è un oggetto SoftLayer_Hardware_Server. Istanzia le proprietà relazionali che desideri richiamare nella proprietà maschera della tua maschera oggetto come nuovi oggetti che rappresentano il tipo di dati di tali proprietà. Se la proprietà relazionale è un tipo array, dichiara un array di un solo elemento, che contiene un singolo oggetto che rappresenta il tipo di dati della proprietà relazionale che desideri richiamare.

Il tuo oggetto servizio API ha una proprietà corrispondente a un valore di maschera oggetto facoltativo. I nomi delle proprietà dei valori della maschera oggetto corrispondono al nome del servizio API che stai utilizzando, iniziando con il nome del tuo servizio API seguito da "ObjectMaskValue". Associa il tuo nuovo oggetto maschera oggetto al tuo oggetto servizio assegnandolo alla proprietà ObjectMaskValue del tuo oggetto servizio. Ad esempio, associa una maschera oggetto a un oggetto servizio SoftLayer_Account assegnandone la relativa SoftLayer_AccountObjectMaskValueproperty al tuo oggetto maschera oggetto.

Questo esempio richiama i record di hardware fisico di un account insieme al record di sistema operativo di detto hardware, al record di sistema operativo, alle password del sistema operativo, ai componenti di rete, al datacenter su cui si trova l'hardware e al numero di processori in ciascun hardware:

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
' Retrieve items related to hardware.
'
' Operating system, operating system passwords, all network components, the
' datacenter the server is located in, and the number of processors in each 
' server.
Dim objectMask As SoftLayer_AccountObjectMask = New SoftLayer_AccountObjectMask()
objectMask.mask = New SoftLayer_Account
 
Dim objectMaskHardware As SoftLayer_Hardware_Server() = {New SoftLayer_Hardware_Server()}
Dim objectMaskHardwareNetworkComponents As SoftLayer_Network_Component() = {New SoftLayer_Network_Component()}
Dim objectMaskHardwareOperatingSystemPasswords As SoftLayer_Software_Component_Password() = {New SoftLayer_Software_Component_Password()}
objectMaskHardware(0).operatingSystem = New SoftLayer_Software_Component_OperatingSystem()
objectMaskHardware(0).operatingSystem.passwords = objectMaskHardwareOperatingSystemPasswords
objectMaskHardware(0).networkComponents = objectMaskHardwareNetworkComponents
objectMaskHardware(0).datacenter = New SoftLayer_Location_Datacenter()
objectMaskHardware(0).processorCount = New UInteger
objectMaskHardware(0).processorCountSpecified = True
 
objectMask.mask.hardware = objectMaskHardware
accountService.SoftLayer_AccountObjectMaskValue = objectMask
 
Dim hardware As SoftLayer_Hardware_Server() = accountService.getHardware()

Utilizzo dei limiti dei risultati

Quando si richiamano i dati, in particolar modo nel caso di query che comportano l'estrazione di frammenti di informazioni da gruppi più grandi, l'utilizzo dei limiti dei risultati ridurrà notevolmente il tempo di attesa per la restituzione dei dati.

Limita il numero di risultati nella tua chiamata API creando un nuovo oggetto resultLimit e associandolo al tuo oggetto servizio API. ResultLimit ha due proprietà:

  • limit: il numero di risultati a cui limitare la tua chiamata.
  • offset: un offset facoltativo per l'inizio del set di risultati.

Associa il tuo nuovo limite dei risultati al tuo oggetto servizio API impostando la proprietà resultLimitValue dell'oggetto servizio al tuo oggetto limite dei risultati.

Dim username As String = "set me"
Dim apiKey As String = "set me"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
' Retrieve our first two open support tickets
Dim resultLimit As resultLimit = New resultLimit()
resultLimit.limit = 2
resultLimit.offset = 0
 
accountService.resultLimitValue = resultLimit
 
Dim tickets As SoftLayer_Ticket() = accountService.getOpenTickets()

Gestione degli errori

Gli errori delle chiamate API SoftLayer vengono inviati al gestore SOAP di .NET come eccezioni. Effettua le chiamate a SoftLayer in blocchi Try/Catch per assicurare una corretta gestione.

Dim username As String = "set me"
Dim apiKey As String = "an incorrect key"
 
Dim authenticate As authenticate = New authenticate()
authenticate.username = username
authenticate.apiKey = apiKey
 
Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()
accountService.authenticateValue = authenticate
 
' Exit the script with the message:
' "Unable to retrieve account information: Invalid API key"
Try
    Dim account As SoftLayer_Account = accountService.getObject()
Catch ex As Exception
    Console.WriteLine("Unable to retrieve account information: " + ex.Message)
End Try

Avvertenze

Lavorare con codice generato dell'API SoftLayer in Visual Studio può richiedere una o due operazioni supplementari quando si creano o si utilizzano oggetti API SoftLayer. Tali operazioni includono l'impostazione di proprietà “specified” e la gestione delle modifiche nei servizi API.

Impostazione delle proprietà "specified"

Alcuni tipi di oggetto nel codice generato hanno una proprietà "specified" insieme alla proprietà dell'oggetto. Se stai impostando tali proprietà in modo esplicito, devi importare la loro proprietà "specified" corrispondenti su True. Utilizza IntelliSense di Visual Studio per determinare a quali proprietà sono associate delle proprietà "specified".

Cosa fare quando i servizi API subiscono variazioni

SoftLayer aggiorna i WSDL API quando vengono rilasciati nuovi prodotti e servizi. Riutilizza tali WSDL per utilizzare queste nuove funzioni.
Se l'API SoftLayer viene importata come un riferimento web nel tuo progetto, fai clic con il pulsante destro del mouse sul nome del riferimento web in Esplora soluzioni di Visual Studio e seleziona "Aggiorna riferimento Web". In pochi minuti, Visual Studio reimporterà il servizio web, operazione dopo la quale le offerte SoftLayer più recenti saranno disponibili nel tuo progetto.
Se hai utilizzato wsdl.exe per generare i file di codice dai WSDL API di SoftLayer, esegui nuovamente il comando wsdl.exe completo per reimportare i WSDL API più recenti di SoftLayer nel tuo progetto.

Componenti API a cui si fa riferimento

Servizi

Tipi di dati

Metodi