Visual Basic .NET

SOAP WSDL のコンシューム

SoftLayer の API WSDL をプロジェクトにインポートするには 2 つの方法があります。Visual Studio は SOAP サービスを、プロジェクトからアクセス可能な Web 参照にコンシュームできます。Visual Studio には、wsdl.exe というユーティリティーも付随します。これは、コマンド・プロンプトから実行され、1 つ以上の WSDL ファイルを読み込み、それをプロジェクトに追加可能なソース・コードに直接変換します。通常、Web サービスの方が Visual Studio で使いやすいのですが、プロジェクトで多数の SoftLayer API サービスを使用する場合は扱いにくくなることがあります。プロジェクトに多数の API サービスが必要な場合は、Wsdl.exe が便利です。

この記事のコード・サンプルは、wsdl.exe によって SoftLayer API サービスから生成されたコードを表します。

Web 参照の作成

  1. Visual Studio で「プロジェクト」メニューをクリックします。
  2. 「プロジェクト」メニューのドロップダウン・ボックスから、「サービス参照の追加」を選択します。
  3. 「サービス参照の追加」ウィンドウで「詳細」ボタンをクリックします。
    注: 「サービス参照設定」ウィンドウが表示されます。
  4. 「サービス参照設定」ウィンドウの「Web 参照の追加」ボタンをクリックします。
  5. 「URL」フィールドに、使用したい SoftLayer API サービスの WSDL への URL を入力します。
  6. 「URL」フィールドの右側にある緑色の矢印をクリックします。

    注: Visual Studio は、WSDL ファイルをダウンロードし、そのファイルに含まれているメソッドとデータ・タイプを分析します。
  7. 「Web 参照名」フィールドに、新しい Web 参照の名前を入力します。
    注: プロジェクトに追加される API サービスの参照はすべて、この名前で参照されます。
  8. 「参照の追加」ボタンをクリックして、新しい Web サービスをインポートします。
    注: これでプロジェクトに戻り、新しい API サービスが Visual Studio のソリューション エクスプローラーに表示されます。

Wsdl.exe の使用

Wsdl.exeC:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\ にあり、SoftLayer の API WSDL を Visual Basic コードに変換するために以下のスイッチで実行する必要があります。

  • /language:VB- wsdl.exe に、Visual Basic .NET コードのエクスポートを指示します。
  • /sharetypes - SoftLayer の WSDL ファイルはいくつかの類似したデータ・タイプを共有します。/sharetypes スイッチは、これらのデータ型をコンパイルして単一のクラス・ファイルにすることで、ソースの専有スペースを削減し、Visual Studio での作業をより効率的にします。
  • /out:C:\path\to\project\SoftLayer_API.vb - 生成されたコードをプロジェクト階層内のパスにエクスポートします。この場合、コードは fileSoftLayer_API.vb に保存されます。

コマンドは、インポートする API WSDLS の URL のスペース区切りのリストで終了します。WSDL ファイルはいくつでも必要なだけインポートできます。

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

注: プライベート API 呼び出しを実行するには、https://api.softlayer.com
http://api.service.softlayer.com で置換します。プライベート API 呼び出しの詳細については、 Getting Started 記事を参照してください。

その他の API サービスをプロジェクトにインポートしたい場合は、このコマンドを再実行します。

コード・ファイルが作成されたら、それをプロジェクトに追加する必要があります。

  1. Visual Studio Solution Explorer 内でプロジェクトの名前を右クリックします。
  2. 展開されたメニューで「追加」オプションまでスクロールします。
  3. 「追加」メニューの 「既存の項目」ボタンをクリックします。
  4. 「既存の項目」ダイアログ・ウィンドウ内で、生成されたコード・ファイルを見つけます。
  5. 生成されたコード・ファイルをクリックして強調表示します。
  6. 「OK」ボタンをクリックして続行します。

最後に、インポート済みコードから SOAP 呼び出しを実行するために、プロジェクトに System.Web.Services サービス参照を含める必要があります。

  1. クリックして Visual Studio で「プロジェクト」メニューを展開します。
  2. 「参照の追加」を選択します。
  3. 「.NET」タブをクリックします。
  4. 「System.Web.Services」を選択します
  5. 「OK」ボタンをクリックして、プロジェクトへの参照を追加します。

これで、SoftLayer の API オブジェクトを、プロジェクトのローカル・オブジェクトとして使用できるようになります。

API 呼び出しの実行

サービス・オブジェクトの作成

プロジェクト内の各 API サービスは、API 呼び出しの実行を行う関連付けられたサービス・クラスを持ちます。サービス・クラスは、呼び出したい API サービスに基づいた名前になります。例えば、SoftLayer_Account API サービスのクラス名は SoftLayer_AccountService で、SoftLayer_Hardware_Serverservice のサービス・クラス名は SoftLayer_Hardware_ServerService です。サービス・オブジェクトは、認証、初期化パラメーター、オブジェクト・マスク、結果制限などの API 機能に対応するプロパティーを持ちます。API メソッド呼び出しはこれらのオブジェクトに対しても直接実行されます。

Dim accountService As SoftLayer_AccountService = New SoftLayer_AccountService()

認証のバインド

API ユーザー名とキーを使用して authenticate オブジェクトを定義することにより、API 呼び出しを認証します。認証オブジェクトの usernameapiKey のプロパティーを、お使いの API のユーザー名とキーに設定します。認証オブジェクトを、authenticateValue プロパティーを自分の認証オブジェクトに設定することにより、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
 
accountService.authenticateValue = authenticate

初期化パラメーターの設定

API 呼び出し初期化 (init) パラメーターは、呼び出す API サービスに対応する定義済みクラスも持ちます。Init パラメーター・クラスは、呼び出す API サービスに基づいた名前になります。例えば、SoftLayer_Account サービスの init パラメーター・クラス名は SoftLayer_AccountInitParameters で、SoftLayer_Hardware_Server サービスの init パラメーター・クラス名は SoftLayer_Hardware_ServerInitParameters です。Init パラメーター・オブジェクトはそれぞれ、照会しようとする SoftLayer オブジェクトの id 番号に対応する単一の整数タイプの id プロパティーを持ちます。サービス・オブジェクトの InitParameterValue プロパティーに init パラメーター・オブジェクトを設定することによって、サービス・オブジェクトにバインドします。ここで は、呼び出している API サービスに対応します。
API 呼び出しが特定の SoftLayer オブジェクトに対応しない場合、初期化パラメーター値をサービス・オブジェクトにバインドする必要はありません。

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

API 呼び出しの実行

サービス・オブジェクトが使用可能になったら、API メソッド呼び出しをサービス・オブジェクトに直接配置します。以下の例に 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()

プロジェクトにインポートされたコードは、SoftLayer API で定義されたすべてのデータ・タイプのクラスを定義します。新規データ・タイプ・オブジェクトを、呼び出しパラメーターまたは呼び出し結果、必要に応じてインスタンス化します。

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())

オブジェクト・マスクの使用

まず、オブジェクト・マスク・オブジェクトを宣言することにより、オブジェクト・マスク を API 呼び出しにバインドします。オブジェクト・マスク・クラス名は、使用する API サービスに対応し、API サービスの名前から始まり、その後に「ObjectMask」が続きます。例えば、SoftLayer_Account API サービスのオブジェクト・マスクはクラス名 SoftLayer_AccountObjectMask を持ち、 SoftLayer_Hardware_Server サービスの対応するオブジェクト・マスク・クラス名は SoftLayer_Hardware_ServerObjectMask です。

すべてのオブジェクト・マスク・クラスは、取得したいリレーショナル・データをモデリングする mask プロパティーを持ちます。mask プロパティーは、API サービスで指し示されたデータ・タイプのオブジェクト上にあります。例えば、SoftLayer_AccountObjectMask.maskSoftLayer_Account オブジェクトで、SoftLayer_Hardware_ServerObjectMask.maskSoftLayer_Hardware_Server オブジェクトです。リレーショナル・プロパティーのデータ・タイプを表す新規オブジェクトとして、オブジェクト・マスクの mask プロパティーで取得したいリレーショナル・プロパティーをインスタンス化します。リレーショナル・プロパティーが配列型の場合は、取得したいリレーショナル・プロパティーのデータ・タイプを表す単一オブジェクトを含む 1 項目配列を宣言します。

API サービス・オブジェクトは、オプションのオブジェクト・マスク値に対応するプロパティーを持ちます。オブジェクト・マスク値のプロパティー名は、使用する API サービスの名前に対応し、API サービスの名前から始まり、その後に「ObjectMaskValue」が続きます。新規オブジェクト・マスク・オブジェクトを、サービス・オブジェクトの ObjectMaskValue プロパティーにそれを割り当てることによって、サービス・オブジェクトにバインドします。例えば、SoftLayer_AccountObjectMaskValueproperty をオブジェクト・マスク・オブジェクトに割り当てることによって、オブジェクト・マスクを SoftLayer_Account サービス・オブジェクトにバインドします。

この例では、アカウントの物理ハードウェア記録を取得します。これには、そのハードウェアのオペレーティング・システム記録、オペレーティング・システム・パスワード、ネットワーク・コンポーネント、ハードウェアが存在するデータ・センター、各ハードウェア内のプロセッサーの数が含まれます。

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()

結果制限の使用

データを呼び出す際、特に大規模グループから情報のほんの一部を引き出す照会を呼び出す場合、結果の制限を使用することで、戻りまでの待ち時間を大幅に減らすことができます。

新しい resultLimit オブジェクトを作成し、API サービス・オブジェクトにバインドすることによって、API 呼び出しの結果の数を制限します。ResultLimit には次の 2 つのプロパティーがあります。

  • limit: 呼び出しを制限するための結果の数。
  • offset: 結果セットを開始するオプションのオフセット。

新規の結果制限を、resultLimitValue プロパティーを自分の結果制限オブジェクトに設定することにより、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
 
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()

エラー処理

SoftLayer API 呼び出しエラーは .NET の SOAP ハンドラーに exceptions として送信されます。 適切な処理を確実にするには、Try/Catch ブロックで SoftLayer を呼び出してください。

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

注意事項

SoftLayer API の生成コードを使用して Visual Studio で作業する場合、SoftLayer API オブジェクトを作成または使用するときにいくつかの追加のステップが必要になります。これらのステップには、「specified」プロパティーの設定と API サービスの変更の処理があります。

「Specified」プロパティーの設定

生成されたコード内の一部のオブジェクト・タイプには、オブジェクトのプロパティーと一緒に「specified」プロパティーがあります。これらのプロパティーを明示的に設定する場合は、対応する specified プロパティーを True に設定する必要があります。どのプロパティーが specified プロパティーに関連しているかを確認するには、Visual Studio の IntelliSense を使用してください。

API サービスが変更になったときに行うこと

新規製品およびサービスがリリースされると、SoftLayer は API WSDL を更新します。これらの新機能を使用するには、これらの WSDL を再コンシュームしてください。
SoftLayer API が Web 参照としてプロジェクトにインポートされる場合、Visual Studio のソリューション エクスプローラーで Web 参照の名前を右クリックし、「Web 参照の更新」を選択します。Visual Studio が Web サービスを再インポートするのに少し時間がかかります。その後、最新の SoftLayer オファリングがプロジェクトで使用可能になります。
wsdl.exe を使用して SoftLayer の API WSDL からコード・ファイルを生成した場合は、wsdl.exe コマンド全体を再実行して、SoftLayer の最新の API WSDL をプロジェクトに再インポートしてください。

参照 API コンポーネント

サービス

データ・タイプ

メソッド