C #

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 参照の作成

Web 参照の作成は、SOAP WSDL を使用するときに必要な最初のタスクです。Visual Studio で 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 のソリューション エクスプローラーに表示されます。

この例では、「com.softlayer.api」と呼ばれるサービス参照を作成しますが、お好きな任意の名前で Web サービスを作成できます。Web 参照名が、プロジェクトの名前空間です。プログラムの開始時に using ステートメントを使用します。したがって、使用する各 API 関連ステートメントで Web 参照の名前を入力する必要がなくなります。例えば、以下のステートメントを使用します:

using projectName.com.softlayer.api;

Web 参照をデフォルトの名前空間として設定するには、「projectName」を Visual Studio プロジェクトの名前で置き換えます。

Wsdl.exe の使用

Wsdl.exe は、C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin にあります。SoftLayer の API WSDL を C# コードに変換するために以下のスイッチで Wsdl.exe を実行します。

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

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

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

注: プライベート API 呼び出しを実行するには、https://api.softlayer.comhttp://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」ボタンをクリックして、プロジェクトへの参照を追加します

API 呼び出しの実行

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

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

認証のバインド

API ユーザー名とキーを使用して authenticate オブジェクトを定義することにより、API 呼び出しを認証します。認証オブジェクトの usernameapiKey のプロパティーを、お使いの API のユーザー名とキーに設定します。認証オブジェクトを、authenticateValue プロパティーを自分の認証オブジェクトに設定することにより、API サービス・オブジェクトにバインドします。

String username = "set me";
String apiKey = "set me";
 
authenticate 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 オブジェクトに対応しない場合、初期化パラメーター値をサービス・オブジェクトにバインドする必要はありません。以下のコード・スニペットが、このシナリオの概要を示しています。

int serverId = 1234;
 
SoftLayer_Hardware_ServerInitParameters hardwareServerInitParameters = new SoftLayer_Hardware_ServerInitParameters();
hardwareServerInitParameters.id = serverId;
hardwareServerService.SoftLayer_Hardware_ServerInitParametersValue = hardwareServerInitParameters;

API 呼び出しの実行
サービス・オブジェクトが使用可能になったら、API メソッド呼び出しをサービス・オブジェクトに直接配置します。このアクションを実行するには、以下のコードを使用します。

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

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

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

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

まず、オブジェクト・マスク・オブジェクトを宣言することにより、オブジェクト・マスク を 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_AccountObjectMaskValue プロパティーをオブジェクト・マスク・オブジェクトに割り当てることによって、オブジェクト・マスクを SoftLayer_Account サービス・オブジェクトにバインドします。

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

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

結果制限の使用

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

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

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

新規の結果制限を、resultLimitValue プロパティーを自分の結果制限オブジェクトに設定することにより、API サービス・オブジェクトにバインドします。

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

エラー処理

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

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);
}

注意事項

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 コンポーネント

サービス

データ・タイプ

メソッド