PowerShell Web Service Proxies

Last month, in "Getting Started with SOAP-Based Web Services and PowerShell," I started showing you how to use SOAP/XML-based Web services with PowerShell. You saw that to exploit any given SOAP service, you need to first phrase your query in the form of an XML file, and that the layout of that XML file must follow the specific requirements of the desired service. Then, you used the Invoke-WebRequest cmdlet to POST (not GET, as is usually the case) that file to the Web service, and from there just used Select-XML to read the XML returned by the Web service to pluck out just the data you wanted.

That was useful, but building those XML query files for those picky SOAP services probably doesn't make your list or top 10 favorite things to do (probably not even your top 1,000 favorite things). Fortunately, the SOAP world shares your feelings on the matter, and so has created the notion of a "Web service proxy."

Web service proxies make querying SOAP services easier by essentially building the XML query for you on the fly. Proxies can do that because every SOAP Web service's site includes a page of another kind of XML that describes that service's desired inputs and resultant outputs. That service-describing XML is sometimes called a "contract" and is built in a format called the Web Services Definition Language (WSDL). Almost every SOAP-based Web service's site includes a WSDL page describing its service.

For example, you can see the WSDL page for the mortgage payment calculator I shared last month at http://www.webservicex.net/mortgage.asmx?wsdl. Yes, that is ugly, but it's meant to be read not by you and me, but instead by computers—including PowerShell's New-WebServiceProxy cmdlet. Just three cmdlets will reveal what www.webservicex.net/mortgage.asmx can do for you:

$URI="http://www.webservicex.net/mortgage.asmx?wsdl"$Proxy = New-WebserviceProxy $URI –Namespace X$Proxy | get-member -MemberType Method Get*

First, I just put the URI for the page we'll use into a variable, as I did last month, pointing this time to the WSDL page. Then I invoked the New-WebServiceProxy cmdlet, which read the WSDL page and created a new type of PowerShell data structure ("class" is the more exact name) that works like a PowerShell object, creating PowerShell methods (remember those?) corresponding to the query-able things in the Web service. Finally, I used Get-Member to display the methods (remember them?) in our new $Proxy object to help find the particular method to do my loan calculation. In that Get-Member command, I said to show me only methods, rather than properties or events, and told it to show me only the methods with names that start with Get. Why Get? Well, in the SOAP world, most interfaces that retrieve data or answers have names that start with Get, as do PowerShell cmdlets.

The methods returned included a promising-looking one, GetMortgagePayment. Recall from a few columns back that you can get PowerShell to cough up some information about any method by just typing the method name without parentheses, as in

$Proxy.GetMortgagePayment

Doing so produced a screen that looks like this:

As you can see, the definition eventually gets down to business with GetMortgagePayment( int Years… and so on, offering a pretty clear blueprint on how to call it. So let's give it a try with a period, loan rate, amount, and so on:

Even better, we didn't have to dig through a lot of XML to get the result, and we could have done something like this to get the monthly payment in just one line:

$Payment = $Proxy.GetMortgagePayment(30,4.2,250000,0,0)

If you find that accessing a SOAP Web service via PowerShell might help you get your job done, then I think you'll be using New-WebServiceProxy a lot. And if you'd like another example of a public SOAP Web service that delivers some neat data, try playing with http://www.webservicex.net/uszip.asmx?wsdl. Given area code, state name, or ZIP code, it'll dump out each city in that group, supplying the city's name, state, ZIP code(s), area code, and time zone.

Web service proxies, then, unlock some of the power of SOAP services. Before leaving this topic, though, let me offer a couple pieces of advice.

First, double-check that the service is still useful. I run into a lot of seemingly cool Web services that produce astronomical, meteorological, or economic data that are patently wrong, and although they're clearly still running, they haven't been looked at in ages and produce unreliable junk. For example, the service I just pointed to seems not to know that the Lynchburg, Virginia, area code went from 804 to 434 in 2001.  The fact is, as I've noted before, very few new SOAP services are appearing, and the existing ones are fading away.

Second, if you're not quite sure about how to find the URI to the WSDL, a good first thing to try is to take the URI of the Web service itself, like www.webservicex.net/uszip.asmx, and add ?wsdl, yielding http://www.webservicex.net/uszip.asmx?wsdl.

Armed with proxies and a bit of caution, you're now equipped to "clean out" the SOAP-based Web service world. See you next time for more Web services!