C Sharp

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

La creazione dei riferimenti web è la prima attività richiesta quando si utilizzano WSDL SOAP. Attieniti alla procedura qui di seguito indicata per creare un riferimento web in Visual Studio.

  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 del 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

Questo esempio crea un riferimento servizio denominato "com.softlayer.api", ma tu puoi creare i servizi web con qualsiasi nome desideri. Il nome dei riferimenti web è uno spazio dei nomi nel tuo progetto. Utilizza l'istruzione using all'inizio del tuo programma in modo da non dover digitare il nome del tuo riferimento web per ogni istruzione correlata all'API che usi. Ad esempio, usa l'istruzione:

using projectName.com.softlayer.api;

Sostituisci a "projectName" il nome del tuo progetto Visual Studio per impostare il tuo riferimento web come spazio dei nomi predefinito.

Utilizzo di wsdl.exe

Wsdl.exe si trova nella directory C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin. Esegui wsdl.exe con i seguenti switch per convertire i WSDL API di SoftLayer in codice C#:

  • /language:CS - indica a wsdl.exe di esportare codice C#.
  • /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.cs - esporta il codice generato in un percorso all'interno della gerarchia del tuo progetto. In questo caso, salveremo il codice in fileSoftLayer_API.cs.

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:CS /out:"C:\Path\to\Project\SoftLayer_API.cs" /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. Per aggiungere il file di codice appena creato al tuo progetto, attieniti a questa procedura:

  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

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_Server è 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. Ad esempio:
SoftLayer_AccountService 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.

String username = "set me";
String apiKey = "set me";
 
authenticate 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. Questo scenario è delineato nel seguente frammento di codice:

int serverId = 1234;
 
SoftLayer_Hardware_ServerInitParameters hardwareServerInitParameters = 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. Utilizza il codice qui di seguito per completare questa azione:

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
// Initialize the SoftLayer_Account API service.
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
SoftLayer_Account account = accountService.getObject();
 
 
// Work directly with the SoftLayer_Hardware_Server record with the 
// hardware id 1234.
int serverId = 1234;
 
SoftLayer_Hardware_ServerService hardwareServerService = new SoftLayer_Hardware_ServerService();
 
SoftLayer_Hardware_ServerInitParameters hardwareServerInitParameters = new SoftLayer_Hardware_ServerInitParameters();
hardwareServerInitParameters.id = serverId;
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters;
 
SoftLayer_Hardware_Server 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.

String username = "set me";
String apiKey = "set me";
int domainId = 1234;
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_Dns_DomainService domainService = new SoftLayer_Dns_DomainService();
domainService.authenticateValue = authenticate;
 
SoftLayer_Dns_DomainInitParameters domainInitParameters = new SoftLayer_Dns_DomainInitParameters();
domainInitParameters.id = domainId;
domainService.SoftLayer_Dns_DomainInitParametersValue = domainInitParameters;
 
// Create a new A record in a domain.
SoftLayer_Dns_Domain_ResourceRecord_AType newRecord = 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 = null;
 
SoftLayer_Dns_Domain domain = new SoftLayer_Dns_Domain();
SoftLayer_Dns_Domain_ResourceRecord_AType[] domainResourceRecords = new SoftLayer_Dns_Domain_ResourceRecord_AType[1];
domainResourceRecords[0].host = "@";
domainResourceRecords[0].data = "127.0.0.1";
domainResourceRecords[0].type = "a";
domain.name = "example.org";
domain.resourceRecords = domainResourceRecords;
 
SoftLayer_Dns_Domain newDomain = domainService.createObject(domain);
Console.WriteLine("New domain 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 maschere oggetto corrispondono al servizio API che stai usando, iniziando con il nome del 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à mask 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 proprietà SoftLayer_AccountObjectMaskValue 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:

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService 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.
SoftLayer_AccountObjectMask objectMask = new SoftLayer_AccountObjectMask();
objectMask.mask = new SoftLayer_Account();
 
SoftLayer_Hardware_Server[] objectMaskHardware = new SoftLayer_Hardware_Server[1];
SoftLayer_Network_Component[] objectMaskHardwareNetworkComponents = new SoftLayer_Network_Component[1];
SoftLayer_Software_Component_Password[] objectMaskHardwareOperatingSystemPasswords = new SoftLayer_Software_Component_Password[1];
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 uint();
objectMaskHardware[0].processorCountSpecified = true;
objectMask.mask.hardware = objectMaskHardware;
accountService.SoftLayer_AccountObjectMaskValue = objectMask;
 
SoftLayer_Hardware_Server[] hardware = (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 dei risultati nella tua chiamata API creando un nuovo oggetto resultLimit e associandolo all'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.

String username = "set me";
String apiKey = "set me";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
// Retrieve our first two open support tickets
resultLimit resultLimit = new resultLimit();
resultLimit.limit = 2;
resultLimit.offset = 0;
 
accountService.resultLimitValue = resultLimit;
 
SoftLayer_Ticket[] tickets = 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. Ad esempio:

String username = "set me";
String apiKey = "an incorrect key";
 
authenticate authenticate = new authenticate();
authenticate.username = username;
authenticate.apiKey = apiKey;
 
SoftLayer_AccountService accountService = new SoftLayer_AccountService();
accountService.authenticateValue = authenticate;
 
// Exit the script with the message:
// "Unable to retrieve account information: Invalid API key"
try 
{
    SoftLayer_Account account = accountService.getObject();
}
catch (Exception ex)
{
    Console.WriteLine("Unable to retrieve account information: " + ex.Message);
}

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. Al termine dell'operazione, 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