|
|
|
Introduction: |
SOAP support comes from the SOAP::Lite module for Perl.
Download This Example
Fundamental Assumptions: As with all examples outlined below, we will assume a few things about
the environment:
* Your SOAP key is 12345678-12345678-12345678-12345678
* The endpoint is https://cp.assmule.apisnetworks.com/soap.php
* The WSDL is located at https://cp.assmule.apisnetworks.com/esprit.wsdl
* Authentication is done via the URL and not through HTTP Authorization
* Scalar example will be from common_get_mail_server_name
* Vector example will be from common_get_disk_quota
|
|
|
Non-WSDL Mode: |
First thing first is to initialize the SOAP client from your Perl script:
#!/usr/bin/perl -w
use strict;
# Dumps variable structure
use Data::Dumper;
# We'll be using the SOAP::Lite package
use SOAP::Lite;
my ($authkey, $endpoint) = ('12345678-12345678-12345678-12345678',
'https://cp.assmule.apisnetworks.com/soap.php');
# First step, initialize the SOAP client:
# URL Authentication Method
my $client = SOAP::Lite->uri('urn:net.esprit.soap')
->proxy($endpoint.'?authkey='.$authkey);
# HTTP Authentication Method
# Override the get_basic_credentials() function to supply
# a password.
sub SOAP::Transport::HTTP::Client::get_basic_credentials {
return 'soap' => '990777fd76e03fdee29d9430bff2bf7b';
}
# Alternatively, the argument supplied to proxy() can be rewritten as:
# proxy('https://soap:'.$authkey.'@cp.assmule.apisnetworks.com/soap.php')
my $client = SOAP::Lite->uri('urn:net.esprit.soap')->proxy($endpoint);
Notes: You can also use auto-dispatch mode in SOAP::Lite to let the module handle all calls to unknown functions.
|
|
|
Handling Scalars: |
# Step two, call the operation on the endpoint:
# Scalar test
my $mail_server_name = $client->common_get_mail_server_name()->result;
print "Mail server name: ".$mail_server_name."\n";
# Outputs:
# mail.demosite.apisnetworks.com
Notes: Scalars are treated as single data variables.
|
|
|
Handling Structs: |
# Reuse the $client object
my $diskSpaceArr = $client->common_get_disk_quota()->result;
# Now we have a hash of two elements, total and used. As with PHP, to find
# out your used disk space print $diskSpaceArr->{'used'} and to find the
# amount of space free:
# print $diskSpaceArr->{'total'} - $diskSpaceArr->{'used'}
# Want to output the data structure? Use Data::Dumper
print Dumper($diskSpaceArr);
# Prints:
# $VAR1 = {
# 'used' => '10908',
# 'total' => '10240'
# };
# Want to know the keys for the hash?
print Dumper(keys(%$diskSpaceArr));
# Prints:
# $VAR1 = 'used';
# $VAR2 = 'total';
# As another example, we'll print out disk space used and free.
# The following code below will output:
# Disk space used: 13000
# Disk space free: 18500
print "Disk space used: ".$diskSpaceArr->{'used'}."\n".
"Disk space free: ".($diskSpaceArr->{'total'}-$diskSpaceArr->{'used'}).
"\n";
Notes: Structs are treated just like hashes in SOAP::Lite. If you're ever curious about the structure, dump the variable returned from the SOAP call
via Data::Dumper().
|
|
|
Handling SOAP Faults: |
# Handle a SOAP Fault
$client->common_non_existent_function();
# When a SOAP Fault occurs, the $fault property will be set within
# the call object.
if ($client->call->fault) {
print "Oops! We got an error: ".$client->call->faultstring."\n";
}
# Prints:
# Oops! We got an error: Procedure 'common_non_existent_function' not present
Notes: If a fault occurs, the $fault property will be set.
|
|