Introduction
This article quickly explains how to connect to a REST based service using BizTalk. A BizTalk Orchestration is used to talk to a simple Bing Geocoding service via REST API. BizTalk 2013 introduces a new adapter for REST which is WCF-WebHttp
and also a new concept known as '
Variable
mapping'
.
Quick References for further reading
If you want a detailed introduction about REST and want to read further before reading this article,
refer to the following articles.
Invoking Bing Geocoding REST API through BizTalk
Step 0: Apply for the Bing Maps API Application Key
Refer to this URL [http://msdn.microsoft.com/en-us/library/ff428642.aspx]
The following are the steps to invoke the Bing Geocoding
REST API through BizTalk.
Step 1: Finalize the Bing Geocoding URL
- Finalize
the Bing URL for Geocoding and generate XML document.
http:
/Locations?query=One%20Dell%20Way,%20Round%20Rock,%20TX%2078682&
key=Ag_GDRUeN3ghulGjTGIAW1ziMR8j-aQ5cu8SbKI0x4wsL8WykRPdSV4lOb9XeptU&o=xml
Notice the various parameters used in the URL.
Parameter Name | Explanation |
Query | Address of the Geocode location |
Key | Bing MAPS Application ID |
O | Output value in XML or JSON.
|
- Generate
the XML document by placing the URL in the browser.
- Right
click on the browser and select View Source and then save it locally as
BingRESTResponse.xml.
- Generate a schema (BingRESTResponse.xsd) out of the XML file saved in
the previous step. This schema shall be imported into the BizTalk solution.
Step 2 BizTalk Administration Console Configuration
- Open
BizTalk Administration Console to create a new Send Port.
- Choose
the default ‘BizTalk Application 1’ or any other BizTalk Application of your choice.
- Observe the settings for the Send Port:'
SP_BingMaps:REST
'. Note that
the send port is automatically created when you import the bindings file into the
BizTalk application.
Use the download link to download the Visual Studio 2012
BizTalk project and take a look at the BizTalk bindings file in the BindingFiles
folder.
- The Receive Pipeline is set to XMLReceive, as the schema for the
response has been generated in Step 1.
Fill in all the details as shown in the screenshot.
- Click
on the Configure button. See the screenshot below.
HTTP Method and URL Mapping
Notice the attributes Name
, Method
and Url
for every HTTP URL being mapped.
<BtsHttpUrlMapping>
<Operation Name="GetGeoCode" Method="GET" Url="?query={userAddressQuery}&key={BingMapsKey}&o=xml" />
</BtsHttpUrlMapping>
What is variable mapping?
The technique of mapping the
parameters with the actual values from the BizTalk Orchestration is known as
Variable mapping. The variable mapping is done using the parenthesis
{parameter}.
- Click on the Edit… button. NOTE that a BizTalk Property schema
has to be created for the variable mapping. Note that the schema can be created
after setting the values in the Variable mapping dialog. Click ‘OK’ and select
the ‘Messages’ Tab.
The screenshot below represents
the Property schema specified in the Variable mapping dialog.
- Specify
GET on the Outbound Message tab and click OK.
Click OK several times and close all the dialog boxes to
create a new Send Port for Bing Geocode.
Note that the send port is automatically created when you
import the bindings file into the BizTalk application.
Step 3: Open the BizTalk solution
Open the BizTalk solution ‘DSHS.GeoCoding.sln’ and
note the following points.
- The
3rd shape in the orchestration is used to send a GET request to the
Bing Geocoding Service.
- The elements of the message on the 3rd shape is mapped as BizTalk Message
Context variables due to the property promotion (BingMapsRestParams.xsd).
The elements in the input message are mapped as shown in the following table.
Request Message Variables | Message Context Variables |
ApplicationID | BingMapsAPIKey |
QueryAddress | UserAddressQuery |
- The
4th shape is a receive shape where the response from the Bing Maps
Service call is returned. This is mapped onto the schema (BingRESTResponse.xsd)
which has been created in Step 1.
- The
BizTalk map in the solution converts the Bing Maps API response into the appropriate
XML format required by the consumer. This is very straightforward process.
Step 4: Create the BizTalk Drop file locations on
the local box
- Create
the BizTalk Drop locations
BizTalk Input Folder | C:\BizTalkDropLocations\DSHS.GeoCode\In |
BizTalk Output Folder | C:\BizTalkDropLocations\DSHS.GeoCode\Out |
BizTalk Sample Input files | C:\BizTalkDropLocations\DSHS.GeoCode |
- Open the sample file DSHS_GeoCodingRequest_sample_1.xml located in
the ‘SampleFiles’ directory. Note that the ApplicationID must be generated
correctly, refer to Step 0 for obtaining the key correctly.
- Make
changes to the Query Address XML tag and save the file.
- Import
the bindings file (DSHS.GeoCoding.Bindings.xml) into BizTalk and deploy the
solution correctly. Start the BizTalk Application.
- Copy
+ Paste the file into the BizTalk Input Folder ‘C:\BizTalkDropLocations\DSHS.GeoCode\In’
- Observe
the GeoCode values in the BizTalk Output Folder ‘C:\BizTalkDropLocations\DSHS.GeoCode\Out’.
See screenshot below.
- Validate
the output file for the correct Geocode values.
Conclusion
In this article we have attempted to connect to a REST based
service using just the HTTP GET verb through a BizTalk orchestration. In future
I shall attempt to connect to a complex REST based service.