Introduction
In Cerberus SOAP API with PowerShell, we used a small script to issue a simple command to Cerberus FTP Server. It is not necessary to completely understand SOAP to make use of Cerberus SOAP API. However, being casually aware of the infrastructure behind your code is a good idea. This document pulls back the curtain a bit, providing insight into how SOAP bridges the gap between PowerShell and your Cerberus FTP Server.
From WSDL to PowerShell
Cerberus.wsdl and ns1.xsd are in two XML formats, Web Service Definition Language and Xml Schema Definition. Generally, you will not need to read these files directly to know how to call SOAP APIs; The .NET toolchain automatically creates PowerShell object types according to the definitions in these files. As an exercise, however, we will trace the definitions for the ServerInformation operation used by HelloCerberus.ps1.
Here is the excerpt from Cerberus.wsdl which first defines the ServerInformation operation:
<operation name="ServerInformation">
<documentation>
Service definition of function tns__ServerInformation
</documentation>
<input message="tns:ServerInformationRequestMessage" />
<output message="tns:ServerInformationResponseMessage" />
</operation>
The above fragment describes an operation named ServerInformation supported by Cerberus FTP Server. The operation takes a ServerInformationRequestMessage object and replies with a ServerInformationResponseMessage. To see what these message objects contain, the references must be followed within Cerberus.wsdl:
<message name="ServerInformationRequestMessage">
<part name="in" element="tns:ServerInformationRequest" />
</message>
<message name="ServerInformationResponseMessage">
<part name="out" element="tns:ServerInformationResponse" />
</message>
The messages are composed of ServerInformationRequest and ServerInformationResponse parts, respectively. These are further defined within Cerberus.wsdl:
<!-- operation request xsd:element -->
<xsd:element name="ServerInformationRequest">
<xsd:complexType>
<xsd:complexContent>
<xsd:extension base="ns1:AuthenticatedRequest">
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<!-- operation response xsd:element -->
<xsd:element name="ServerInformationResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="result" type="ns1:ServerInformation" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
These lines describe the request and response objects as complex types, defined in the ns1 namespace. The ns1 namespace is defined near the top of Cerberus.wsdl:
<xsd:schema
targetNamespace="http://cerberusllc.com/service/cerberusftpservice"
xmlns:ns1="http://cerberusllc.com/common"
attributeFormDefault="qualified"
elementFormDefault="qualified">
<xsd:import
namespace="http://cerberusllc.com/common"
schemaLocation="./ns1.xsd" />
This fragment says further schema definitions can be found in external file, ns1.xsd. Within ns1.xsd, the definitions of the AuthenticatedRequest and ServerInformation types can be found:
<xsd:complexType name="Credentials">
<xsd:sequence>
<xsd:element name="user" type="xsd:string" />
<xsd:element name="password" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="AuthenticatedRequest">
<xsd:sequence>
<xsd:element name="credentials" type="ns1:Credentials" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="ServerInformation">
<xsd:sequence>
<xsd:element name="version" type="ns1:Version" />
<xsd:element name="hostname" type="xsd:string" />
<xsd:element name="isStarted" type="xsd:boolean" />
</xsd:sequence>
<xsd:attribute name="isSuccess" type="xsd:boolean" use="optional" />
<xsd:attribute name="message" type="xsd:string" use="optional" />
</xsd:complexType>
<xsd:complexType name="Version">
<xsd:sequence>
</xsd:sequence>
<xsd:attribute name="maj" type="xsd:int" use="required" />
<xsd:attribute name="min" type="xsd:int" use="required" />
<xsd:attribute name="maint" type="xsd:int" use="required" />
<xsd:attribute name="build" type="xsd:int" use="required" />
</xsd:complexType>
With the fragment above, the definition is complete. The AuthenticatedRequest and ServerInformation types contain nested objects of Credentials and Version types, respectively.
When New-WebServiceProxy consumes the WSDL and XSD files, it generates corresponding .NET types, usable to PowerShell. You can run the New-WebServiceProxy command interactively to examine these types.
Here is an example:
PS C:\> $CerberusFtpSvc = New-WebServiceProxy -Uri "https://localhost:8443/wsdl/cerberus.wsdl" -Namespace CerberusFtp -Class CerberusFtp PS C:\> [CerberusFtp.AuthenticatedRequest].DeclaredProperties | Select-Object Name,PropertyType Name PropertyType ---- ------------ credentials CerberusFtp.Credentials PS C:\> [CerberusFtp.ServerInformation].DeclaredProperties | Select-Object Name,PropertyType Name PropertyType ---- ------------ version CerberusFtp.Version hostname System.String isStarted System.Boolean isSuccess System.Boolean isSuccessSpecified System.Boolean message System.String
The above console transcript first creates a new web service proxy object using New-WebServiceProxy. Passing the -Namespace parameter instructs the command to create necessary types within the “CerberusFtp” namespace.
The bracket syntax allows us to view and query type information of any type visible to PowerShell. Above, we examine declared properties of AuthenticatedRequest and ServerInformation. ServerInformation is nearly identical to its corresponding XML in ns1.xsd.
Where to Go From Here
Once New-WebServiceProxy is finished processing the WSDL file, everything you need to make SOAP requests is available within PowerShell. The $CerberusFtpSvc object can be examined using the built-in PowerShell command Get-Member.
Here is an example that yields the 87 basic Cerberus API operations on the proxy object:
PS C:\>$CerberusFtpSvc |Get-Member -Type Method |Where-Object {$_.definition -like "CerberusFtp*" -and $_.name -notlike "Begin*" -and $_.name -notlike "End*"}
Pick and interesting one and start examining its associated request and response objects:
PS C:\>$CerberusFtpSvc |Get-Member -Type Method -Name AddUser |fl * TypeName : CerberusFtp.CerberusFTPService Name : AddUser MemberType : Method Definition : CerberusFtp.AddUserResponse AddUser(CerberusFtp.AddUserRequest AddUserRequest)
Here, for instance, we have the AddUser method, which returns a CerberusFtp.AddUserResponse object and takes a CerberusFtp.AddUserRequest object. We can drill-down on these types to get an idea of what the AddUser will do and how to correctly call it:
PS C:\> [CerberusFtp.AddUserRequest].DeclaredProperties |Select-Object Name,PropertyType Name PropertyType ---- ------------ User CerberusFtp.User saveToDisk System.Nullable`1[System.Boolean] saveToDiskSpecified System.Boolean createNonExistentDirectories System.Nullable`1[System.Boolean] createNonExistentDirectoriesSpecified System.Boolean
We see that AddUser requires a CerberusFtp.User object, so we can repeat the above to get insight into what kind of information a User object contains:
PS C:\> [CerberusFtp.User].DeclaredProperties |Select-Object Name,PropertyType Name PropertyType ---- ------------ password CerberusFtp.Password isAllowPasswordChange CerberusFtp.UserPropertyBool isAnonymous CerberusFtp.UserPropertyBool isSimpleDirectoryMode CerberusFtp.UserPropertyBool isDisabled CerberusFtp.UserPropertyBool maxLoginsAllowed CerberusFtp.UserPropertyInt requireSecureControl CerberusFtp.UserPropertyBool requireSecureData CerberusFtp.UserPropertyBool disableAfterTime CerberusFtp.UserPropertyDateTime authMethod CerberusFtp.UserPropertyAuthentication protocols CerberusFtp.ProtocolsAllowed maxUploadFilesize CerberusFtp.UserPropertyULong ipAllowedList CerberusFtp.UserPropertyString groupList CerberusFtp.groupMember[] rootList CerberusFtp.VirtualDirectory[] lastLogin System.DateTime lastLoginSpecified System.Boolean createDate System.DateTime createDateSpecified System.Boolean notifiedExpiringPassword System.Boolean notifiedExpiringPasswordSpecified System.Boolean requirePasswordChange System.Boolean requirePasswordChangeSpecified System.Boolean email System.String tel System.String mobile System.String desc System.String fname System.String sname System.String name System.String
Conclusion
We've covered how the WSDL and XSD files describe Cerberus FTP Server's SOAP API, traced from those definitions to live .NET objects and types, and demonstrated how they are self-describing using PowerShell's Get-Member command. We've only scratched the surface on the AddUser method, as there will be other code examples and tutorials demonstrating its use.
In closing, here is the complete list of Cerberus SOAP API's 87 operations, current as of 10.0.10:
Cerberus SOAP API Operations (as of version 10.0.10)
Name Definition ---- ---------- AddDirectoryToGroup CerberusFtp.AddDirectoryToGroupResponse AddDirectoryToGroup(CerberusFtp.AddDirectoryToGroupRequest AddDirectoryToGroupRequest) AddDirectoryToUser CerberusFtp.AddDirectoryToUserResponse AddDirectoryToUser(CerberusFtp.AddDirectoryToUserRequest AddDirectoryToUserRequest) AddGroup CerberusFtp.AddGroupResponse AddGroup(CerberusFtp.AddGroupRequest AddGroupRequest) AddIp CerberusFtp.AddIpResponse AddIp(CerberusFtp.AddIpRequest AddIpRequest) AddUser CerberusFtp.AddUserResponse AddUser(CerberusFtp.AddUserRequest AddUserRequest) BackupServerConfiguration CerberusFtp.BackupServerConfigurationResponse BackupServerConfiguration(CerberusFtp.BackupServerConfigurationRequest BackupServerConfigurationRequest) BackupStatisticsDatabase CerberusFtp.BackupStatisticsDatabaseResponse BackupStatisticsDatabase(CerberusFtp.BackupStatisticsDatabaseRequest BackupStatisticsDatabaseRequest) BlockAddress CerberusFtp.BlockAddressResponse BlockAddress(CerberusFtp.BlockAddressRequest BlockAddressRequest) ChangePassword CerberusFtp.ChangePasswordResponse ChangePassword(CerberusFtp.ChangePasswordRequest ChangePasswordRequest) CommitSettings CerberusFtp.CommitSettingsResponse CommitSettings(CerberusFtp.CommitSettingsRequest CommitSettingsRequest) CreateDirectory CerberusFtp.CreateDirectoryResponse CreateDirectory(CerberusFtp.CreateDirectoryRequest CreateDirectoryRequest) CreateStatisticsDatabase CerberusFtp.CreateStatisticsDatabaseResponse CreateStatisticsDatabase(CerberusFtp.CreateStatisticsDatabaseRequest CreateStatisticsDatabaseRequest) CurrentStatus CerberusFtp.CurrentStatusResponse CurrentStatus(CerberusFtp.CurrentStatusRequest CurrentStatusRequest) DeleteDirectory CerberusFtp.DeleteDirectoryResponse DeleteDirectory(CerberusFtp.DeleteDirectoryRequest DeleteDirectoryRequest) DeleteDirectoryFromGroup CerberusFtp.DeleteDirectoryFromGroupResponse DeleteDirectoryFromGroup(CerberusFtp.DeleteDirectoryFromGroupRequest DeleteDirectoryFromGroupRequest) DeleteDirectoryFromUser CerberusFtp.DeleteDirectoryFromUserResponse DeleteDirectoryFromUser(CerberusFtp.DeleteDirectoryFromUserRequest DeleteDirectoryFromUserRequest) DeleteGroup CerberusFtp.DeleteGroupResponse DeleteGroup(CerberusFtp.DeleteGroupRequest DeleteGroupRequest) DeleteIp CerberusFtp.DeleteIpResponse DeleteIp(CerberusFtp.DeleteIpRequest DeleteIpRequest) DeletePublicShares CerberusFtp.DeletePublicSharesResponse DeletePublicShares(CerberusFtp.DeletePublicSharesRequest DeletePublicSharesRequest) DeleteRequestedAccounts CerberusFtp.DeleteRequestedAccountsResponse DeleteRequestedAccounts(CerberusFtp.DeleteRequestedAccountsRequest DeleteRequestedAccountsRequest) DeleteUser CerberusFtp.DeleteUserResponse DeleteUser(CerberusFtp.DeleteUserRequest DeleteUserRequest) DropStatisticsDatabase CerberusFtp.DropStatisticsDatabaseResponse DropStatisticsDatabase(CerberusFtp.DropStatisticsDatabaseRequest DropStatisticsDatabaseRequest) GenerateStatistics CerberusFtp.GenerateStatisticsResponse GenerateStatistics(CerberusFtp.GenerateStatisticsRequest GenerateStatisticsRequest) GetAdminAccounts CerberusFtp.GetAdminAccountsResponse GetAdminAccounts(CerberusFtp.GetAdminAccountsRequest GetAdminAccountsRequest) GetAllCurrentConnectionCount CerberusFtp.GetAllCurrentConnectionCountResponse GetAllCurrentConnectionCount(CerberusFtp.GetAllCurrentConnectionCountRequest GetAllCurrentConnectionCountRequest) GetAppPaths CerberusFtp.GetAppPathsResponse GetAppPaths(CerberusFtp.GetAppPathsRequest GetAppPathsRequest) GetAuthenticationList CerberusFtp.GetAuthenticationListResponse GetAuthenticationList(CerberusFtp.GetAuthenticationListRequest GetAuthenticationListRequest) GetAutoBlockList CerberusFtp.GetAutoBlockListResponse GetAutoBlockList(CerberusFtp.GetAutoBlockListRequest GetAutoBlockListRequest) GetBackupServers CerberusFtp.GetBackupServersResponse GetBackupServers(CerberusFtp.GetBackupServersRequest GetBackupServersRequest) GetConfiguration CerberusFtp.GetConfigurationResponse GetConfiguration(CerberusFtp.GetConfigurationRequest GetConfigurationRequest) GetConnectedUserList CerberusFtp.GetConnectedUserListResponse GetConnectedUserList(CerberusFtp.GetConnectedUserListRequest GetConnectedUserListRequest) GetCurrentBandwidth CerberusFtp.GetCurrentBandwidthResponse GetCurrentBandwidth(CerberusFtp.GetCurrentBandwidthRequest GetCurrentBandwidthRequest) GetCurrentConnectionCount CerberusFtp.GetCurrentConnectionCountResponse GetCurrentConnectionCount(CerberusFtp.GetCurrentConnectionCountRequest GetCurrentConnectionCountRequest) GetEventRules CerberusFtp.GetEventRulesResponse GetEventRules(CerberusFtp.GetEventRulesRequest GetEventRulesRequest) GetFeatures CerberusFtp.GetFeaturesResponse GetFeatures(CerberusFtp.GetFeaturesRequest GetFeaturesRequest) GetFileTransfers CerberusFtp.GetFileTransfersResponse GetFileTransfers(CerberusFtp.GetFileTransfersRequest GetFileTransfersRequest) GetFolderMonitors CerberusFtp.GetFolderMonitorsResponse GetFolderMonitors(CerberusFtp.GetFolderMonitorsRequest GetFolderMonitorsRequest) GetGroupInformation CerberusFtp.GetGroupInformationResponse GetGroupInformation(CerberusFtp.GetGroupInformationRequest GetGroupInformationRequest) GetGroupList CerberusFtp.GetGroupListResponse GetGroupList(CerberusFtp.GetGroupListRequest GetGroupListRequest) GetGroups CerberusFtp.GetGroupsResponse GetGroups(CerberusFtp.GetGroupsRequest GetGroupsRequest) GetHostname CerberusFtp.GetHostnameResponse GetHostname(CerberusFtp.GetHostnameRequest GetHostnameRequest) GetInterfaceByID CerberusFtp.GetInterfaceResponse GetInterfaceByID(CerberusFtp.GetInterfaceByIDRequest GetInterfaceByIDRequest) GetInterfaceList CerberusFtp.GetInterfaceListResponse GetInterfaceList(CerberusFtp.GetInterfaceListRequest GetInterfaceListRequest) GetInterfaces CerberusFtp.GetInterfacesResponse GetInterfaces(CerberusFtp.GetInterfacesRequest GetInterfacesRequest) GetIPBlockList CerberusFtp.GetIPBlockListResponse GetIPBlockList(CerberusFtp.GetIPBlockListRequest GetIPBlockListRequest) GetLicenseInfo CerberusFtp.GetLicenseInfoResponse GetLicenseInfo(CerberusFtp.GetLicenseInfoRequest GetLicenseInfoRequest) GetLogMessages CerberusFtp.GetLogMessagesResponse GetLogMessages(CerberusFtp.GetLogMessagesRequest GetLogMessagesRequest) GetMimeMappings CerberusFtp.GetMimeMappingsResponse GetMimeMappings(CerberusFtp.GetMimeMappingsRequest GetMimeMappingsRequest) GetProfiles CerberusFtp.GetProfilesResponse GetProfiles(CerberusFtp.GetProfilesRequest GetProfilesRequest) GetPublicShares CerberusFtp.GetPublicSharesResponse GetPublicShares(CerberusFtp.GetPublicSharesRequest GetPublicSharesRequest) GetRequestedAccounts CerberusFtp.GetRequestedAccountsResponse GetRequestedAccounts(CerberusFtp.GetRequestedAccountsRequest GetRequestedAccountsRequest) GetStatistics CerberusFtp.GetStatisticsResponse GetStatistics(CerberusFtp.GetStatisticsRequest GetStatisticsRequest) GetUserCustomSettings CerberusFtp.GetUserCustomSettingsResponse GetUserCustomSettings(CerberusFtp.GetUserCustomSettingsRequest GetUserCustomSettingsRequest) GetUserInformation CerberusFtp.GetUserInformationResponse GetUserInformation(CerberusFtp.GetUserInformationRequest GetUserInformationRequest) GetUserList CerberusFtp.GetUserListResponse GetUserList(CerberusFtp.GetUserListRequest GetUserListRequest) InitializeInterface CerberusFtp.InitializeInterfaceResponse InitializeInterface(CerberusFtp.InitializeInterfaceRequest InitializeInterfaceRequest) InitializeServer CerberusFtp.InitializeServerResponse InitializeServer(CerberusFtp.InitializeServerRequest InitializeServerRequest) ModifyInterface CerberusFtp.ModifyInterfaceResponse ModifyInterface(CerberusFtp.ModifyInterfaceRequest ModifyInterfaceRequest) RenameGroup CerberusFtp.RenameGroupResponse RenameGroup(CerberusFtp.RenameGroupRequest RenameGroupRequest) RenameUser CerberusFtp.RenameUserResponse RenameUser(CerberusFtp.RenameUserRequest RenameUserRequest) RestoreServerConfiguration CerberusFtp.RestoreServerConfigurationResponse RestoreServerConfiguration(CerberusFtp.RestoreServerConfigurationRequest RestoreServerConfigurationRequest) RestoreStatisticsDatabase CerberusFtp.RestoreStatisticsDatabaseResponse RestoreStatisticsDatabase(CerberusFtp.RestoreStatisticsDatabaseRequest RestoreStatisticsDatabaseRequest) SaveBackupServers CerberusFtp.SaveBackupServersResponse SaveBackupServers(CerberusFtp.SaveBackupServersRequest SaveBackupServersRequest) SaveBlockList CerberusFtp.SaveBlockListResponse SaveBlockList(CerberusFtp.SaveBlockListRequest SaveBlockListRequest) SaveConfiguration CerberusFtp.SaveConfigurationResponse SaveConfiguration(CerberusFtp.SaveConfigurationRequest SaveConfigurationRequest) SaveMimeMappings CerberusFtp.SaveMimeMappingsResponse SaveMimeMappings(CerberusFtp.SaveMimeMappingsRequest SaveMimeMappingsRequest) SaveProfiles CerberusFtp.SaveProfilesResponse SaveProfiles(CerberusFtp.SaveProfilesRequest SaveProfilesRequest) ServerInformation CerberusFtp.ServerInformationResponse ServerInformation(CerberusFtp.ServerInformationRequest ServerInformationRequest) ServerStarted CerberusFtp.ServerStartedResponse ServerStarted(CerberusFtp.ServerStartedRequest ServerStartedRequest) ServerSummaryStatus CerberusFtp.ServerSummaryStatusResponse ServerSummaryStatus(CerberusFtp.ServerSummaryStatusRequest ServerSummaryStatusRequest) SetAdminAccounts CerberusFtp.SetAdminAccountsResponse SetAdminAccounts(CerberusFtp.SetAdminAccountsRequest SetAdminAccountsRequest) SetAuthenticationList CerberusFtp.SetAuthenticationListResponse SetAuthenticationList(CerberusFtp.SetAuthenticationListRequest SetAuthenticationListRequest) SetEventRules CerberusFtp.SetEventRulesResponse SetEventRules(CerberusFtp.SetEventRulesRequest SetEventRulesRequest) SetFolderMonitors CerberusFtp.SetFolderMonitorsResponse SetFolderMonitors(CerberusFtp.SetFolderMonitorsRequest SetFolderMonitorsRequest) SetPublicShares CerberusFtp.SetPublicSharesResponse SetPublicShares(CerberusFtp.SetPublicSharesRequest SetPublicSharesRequest) SetRequestedAccounts CerberusFtp.SetRequestedAccountsResponse SetRequestedAccounts(CerberusFtp.SetRequestedAccountsRequest SetRequestedAccountsRequest) SetUserCustomSettings CerberusFtp.SetUserCustomSettingsResponse SetUserCustomSettings(CerberusFtp.SetUserCustomSettingsRequest SetUserCustomSettingsRequest) SetWANIP CerberusFtp.SetWANIPResponse SetWANIP(CerberusFtp.SetWANIPRequest SetWANIPRequest) SharePublicFile CerberusFtp.SharePublicFileResponse SharePublicFile(CerberusFtp.SharePublicFileRequest SharePublicFileRequest) ShutdownConnectionsOnInterface CerberusFtp.ShutdownConnectionsOnInterfaceResponse ShutdownConnectionsOnInterface(CerberusFtp.ShutdownConnectionsOnInterfaceRequest ShutdownConnectionsOnInterfaceRequest) ShutdownInterface CerberusFtp.ShutdownInterfaceResponse ShutdownInterface(CerberusFtp.ShutdownInterfaceRequest ShutdownInterfaceRequest) ShutdownServer CerberusFtp.ShutdownServerResponse ShutdownServer(CerberusFtp.ShutdownServerRequest ShutdownServerRequest) StartServer CerberusFtp.StartServerResponse StartServer(CerberusFtp.StartServerRequest StartServerRequest) StopServer CerberusFtp.StopServerResponse StopServer(CerberusFtp.StopServerRequest StopServerRequest) TerminateConnection CerberusFtp.TerminateConnectionResponse TerminateConnection(CerberusFtp.TerminateConnectionRequest TerminateConnectionRequest) TestAndVerifyDatabase CerberusFtp.TestAndVerifyDatabaseResponse TestAndVerifyDatabase(CerberusFtp.TestAndVerifyDatabaseRequest TestAndVerifyDatabaseRequest) VerifyLicense CerberusFtp.VerifyLicenseResponse VerifyLicense(CerberusFtp.VerifyLicenseRequest VerifyLicenseRequest)
Comments
0 comments
Please sign in to leave a comment.