Using SOAP to access ArcGIS Server web services
ArcGIS Server SOAP web services are based on two standard XML-based W3C specifications: WSDL (Web Service Description Language) and SOAP.
WSDL is a specification used to describe networked XML-based services. In general, WSDL provides a simple way for service providers to describe the basic format of requests to their services, regardless of the underlying protocol. One of those protocols, and by far the most popular, is SOAP. SOAP is used to describe the format of a message sent to a networked service and allow computers to communicate independently of an operating system or platform. SOAP messages can be transmitted to a service via a number of transport protocols, including HTTP.
Consuming SOAP services
Developer environments, such as .NET or Java, provide SOAP toolkits to automate the process of generating a set of local, native classes for a consumer. The WSDL provides the client all it needs to generate the native proxy and value objects, thus no proprietary components related to the web service are necessary.
Value objects are simply objects that store values or properties. Depending on the WSDL, there can be many different types of value objects. On the other hand, there is only one proxy class per SOAP service type. The proxy has both properties and methods. The methods are designed to create and submit a SOAP request and return a SOAP response. The proxy uses the value objects to construct (serialize) a SOAP request. The proxy also deserializes the SOAP response and constructs value objects to be used by the client. So working with a rich client object environment makes it much easier to consume and utilize a SOAP service because you are using native objects to store properties (value objects) and manage SOAP requests and responses (proxy) on the client.
Consuming ArcGIS Server web services
A WSDL is used to generate the proxy classes and value objects for each ArcGIS Server service type. There is one WSDL and thus one SOAP proxy class for each service type. The capabilities of a ArcGIS Server SOAP web services are defined by the methods of the proxy. The proxy is designed to work with ArcGIS Server services in a stateless manner, thus the proxy class provides methods to initiate stateless requests to an ArcGIS Server service and return results. The ArcGIS Server SOAP proxy uses value objects when calling a method and returning results. SOAP proxies and value objects are usually generated by a SOAP toolkit designed for a specific development environment such as .NET and Java. For example, Visual Studio 2005 contains an integrated SOAP toolkit (wsdl.exe) for .NET developers and the Java community maintains a number of options such as Apache Axis. It is important to note that no ESRI components need to be installed or available on the client. Thus a client application can utilize ArcGIS Server web services much like any other SOAP-based web service.
ArcGIS Server SOAP web services use the following URL pattern:
http://<host name>:<port number>/<arcgis instance>/services/<FolderName>/<ServiceName>/<ServiceType>
- <host name> is the hostname of the web server which is used as the entry point into your ArcGIS Server site. This can be where ArcGIS Server or the ArcGIS Web Adaptor application is deployed.
- <port number> is the port on which the ArcGIS Server application is configured to run on. The default is 6080. If your server administrator has installed the ArcGIS Web Adaptor in front of your server deployment, the port number will vary depending on the Web Adaptor configuration. For more information, see About the ArcGIS Web Adaptor.
- <arcgis instance> is the name of the virtual directory in which the web services are made available. The default is arcgis. If your server administrator has installed the ArcGIS Web Adaptor in front of your server deployment, the instance name will vary depending on the Web Adaptor configuration. For more information, see About the ArcGIS Web Adaptor.
- <FolderName> is the name of a virtual folder on ArcGIS Server. One or more services may reside within a folder. Exposing services in a folder is optional. If a service is not in a folder (it is exposed at the root), the FolderName portion of the URL is omitted. See the Catalog proxy's GetFolders method to determine if an ArcGIS Server site has folders.
- <ServiceName> is the name of the ArcGIS Server service.
- <ServiceType> is the service or service extension type. This type must provide a WSDL to be utilized via SOAP. Valid service types are listed in the table below.
The WSDL for a service or extension will provide the necessary information to determine how to interact, via SOAP, with the web service. The WSDL can be returned by appending ?wsdl to the end of the URL.
ArcGIS Server web service proxies and value objects
The proxy and value objects for an ArcGIS Server service only need to be generated once per service type. Once the web service proxy and value objects for an ArcGIS Server service have been created, they can be reused with other ArcGIS Server web services of the same type, even though the proxy class name contains the original service name (dynamic proxies only). For example, if a web service proxy class is generated dynamically using a map service named NorthAmerica, the proxy class name will be NorthAmerica_MapServer. The default endpoint for the MapServer proxy will be associated with the NorthAmerica map service. To use another ArcGIS Server web map service named Europe, set the URL property to define the web service endpoint to the Europe ArcGIS Server web map service. The same applies for all ArcGIS Server service types. A comprehensive list of service types and descriptions are provided below:
Use to access to service lists and properties on an ArcGIS Server site.
Use to query and edit features.
Use to assign locations to address attribute information.
Use to create local copies of remote data, execute geodatabase queries, and synchronize edits with other geodatabases. Designed to work with geodatabases directly.
Provides a set of useful and common operations (buffer, projection, etc.) on arrays of geometries.
Use to interact with GIS operations for data analysis, data management, and data conversion.
Use to access to ArcGIS Globe layers for query and display in a 3D environment. It is designed to be used in ArcGIS for Desktop applications only.
Use to generate map content from raster data.
Use to generate and retrieve map content or query attributes and features.
Use to provide map and data access to applications developed using the Mobile SDK. It is designed for Mobile SDK clients only.
Use to generate network solutions, such as routing, service area generation, determining closest facilities, and calculating Origin-Destination cost matrices.