Visual Basic .NET

SOAP WSDL 사용

SoftLayer의 API WSDL을 사용자 프로젝트로 가져오는 방법은 두 가지가 있습니다. Visual Studio에서 SOAP 서비스를 사용하여 사용자 프로젝트에서 액세스 가능한 웹 참조로 이동합니다. Visual Studio에는 하나 이상의 WSDL 파일을 읽어온 후 이 파일을 사용자 프로젝트에 추가할 수 있는 소스 코드로 바로 변환하기 위해 명령 프롬프트에서 실행하는 wsdl.exe 유틸리티가 제공됩니다. 일반적으로 웹 서비스는 Visual Studio에서 사용하는 것이 간편하지만, 많은 SoftLayer API 서비스를 사용하는 프로젝트인 경우에는 웹 서비스가 번거롭고 손이 많이 갈 수 있습니다. Wsdl.exe는 많은 API 서비스를 필요로 하는 프로젝트에 특히 유용합니다.

이 기사에 나와 있는 코드 샘플은 wsdl.exe를 통해 SoftLayer API 서비스에서 생성되는 코드를 보여줍니다.

웹 참조 작성

  1. Visual Studio에서 프로젝트 메뉴를 클릭합니다.
  2. 프로젝트 메뉴 드롭 다운 상자에서 서비스 참조 추가를 선택합니다.
  3. 서비스 참조 추가 창에서 고급을 클릭합니다.
    참고: 서비스 참조 설정 창이 나타납니다.
  4. 서비스 참조 설정 창에서 웹 참조 추가 단추를 클릭합니다.
  5. 사용할 SoftLayer API 서비스의 WSDL에 대한 URLURL 필드에 입력합니다.
  6. URL 필드 오른쪽에서 녹색 화살표를 클릭합니다.
    참고: Visual Studio에서 WSDL 파일을 다운로드하여 파일에 포함된 메소드 및 데이터 유형을 분석합니다.
  7. 웹 참조 이름 필드에 새로운 웹 참조의 이름을 입력합니다.
    참고: 프로젝트에 추가된 API 서비스를 참조할 때는 이름 기준으로 참조합니다.
  8. 참조 추가 단추를 클릭하여 새로운 웹 서비스를 가져옵니다.
    참고: 이제 프로젝트로 돌아가 Visual Studio의 솔루션 탐색기에서 새로운 API 서비스를 확인할 수 있습니다.

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 호출에 대한 자세한 정보는 시작하기 기사를 참조하십시오.

더 많은 API 서비스를 프로젝트로 가져오려면 이 명령을 다시 실행합니다.

코드 파일이 작성된 후 이 파일을 프로젝트에 추가해야 합니다.

  1. Visual Studio 솔루션 탐색기에서 프로젝트의 이름을 마우스 오른쪽 단추로 클릭합니다.
  2. 펼친 메뉴에서 추가 옵션 위로 스크롤합니다.
  3. 추가 메뉴에서 기존 항목 단추를 클릭합니다.
  4. 기존 항목 추가 대화 상자 창에서 생성된 코드 파일을 찾습니다.
  5. 생성된 코드 파일을 클릭하여 강조표시합니다.
  6. 확인 단추를 클릭하여 계속 진행합니다.

마지막으로, 가져온 코드에서 SOAP 호출을 작성하려면 프로젝트에 System.Web.Services 서비스 참조가 포함되어 있어야 합니다.

  1. Visual Studio에서 프로젝트 메뉴를 클릭하여 펼칩니다.
  2. 참조 추가를 선택합니다.
  3. .NET 탭을 클릭합니다.
  4. System.Web.Services를 선택합니다.
  5. 확인 단추를 클릭하여 해당 참조를 프로젝트에 추가합니다.

이제 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 호출을 인증하려면 API 사용자 이름과 키를 사용하여 authenticate 오브젝트를 정의합니다. 인증 오브젝트의 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 특성을 하나 포함합니다. init 매개변수 오브젝트를 호출하는 API 서비스에 해당하는 서비스 오브젝트의 InitParameterValue 특성으로 설정하여 init 매개변수 오브젝트를 서비스 오브젝트에 바인딩합니다.
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 오브젝트입니다. 오브젝트 마스크의 마스크 특성에서 검색할 관계형 특성을 이들 특성의 데이터 유형을 나타내는 새로운 오브젝트로 인스턴스화합니다. 관계형 특성이 배열 유형인 경우, 검색할 관계형 특성의 데이터 유형을 나타내는 하나의 오브젝트를 포함한 한 개 항목 배열을 선언합니다.

사용자의 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()

결과 제한 사용

데이터, 특히 대형 그룹에서 정보 조각을 가져오는 쿼리를 호출할 때 결과 제한을 사용하면 리턴 대기 시간이 대폭 줄어듭니다.

API 호출에서 결과의 수를 제한하려면 새로운 resultLimit 오브젝트를 작성하고 이 오브젝트를 API 서비스 오브젝트에 바인딩합니다. ResultLimit는 두 가지 특성을 갖습니다.

  • 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 핸들러에 예외로 전송됩니다. 올바른 처리를 위해 SoftLayer에 대한 호출을 Try/Catch 블록에 배치합니다.

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

주의 사항

Visual Studio에서 SoftLayer API의 생성된 코드에 대해 작업하려면 SoftLayer API 오브젝트를 작성하거나 사용할 때 한 두 단계를 추가로 수행해야 할 수 있습니다. "지정된" 특성을 설정하고 API 서비스에서 변경을 처리하는 단계가 여기에 포함됩니다.

"지정된" 특성 설정

생성된 코드에 나와 있는 일부 오브젝트 유형은 오브젝트 특성 외에 "지정된" 특성을 갖습니다. 이 특성을 명시적으로 설정하는 경우, 해당 지정된 특성을 True로 설정해야 합니다. 어떤 특성에 지정된 특성이 연결되어 있는지 확인하려면 Visual Studio의 IntelliSense를 사용합니다.

API 서비스 변경 시 해야 할 일

새로운 제품과 서비스가 출시되면 SoftLayer는 API WSDL을 업데이트합니다. 새로운 기능을 활용하려면 이러한 업데이트된 WSDL을 사용합니다.
SoftLayer API를 사용자 프로젝트에 웹 참조로 가져온 경우, Visual Studio 솔루션 탐색기에서 웹 참조의 이름을 마우스 오른쪽 단추로 클릭하고 "웹 참조 업데이트"를 선택합니다. Visual Studio에서 웹 서비스를 다시 가져오는 데 약간의 시간이 걸리므로 잠시 후에 사용자 프로젝트에서 최신 SoftLayer 기능을 사용할 수 있습니다.
wsdl.exe를 사용하여 SoftLayer의 API WSDL에서 코드 파일을 생성한 경우에는 전체 wsdl.exe 명령을 재실행하여 SoftLayer의 최신 API WSDL을 사용자 프로젝트로 다시 가져오십시오.

참조된 API 구성요소

서비스

데이터 유형

메소드