Invoking Bing Maps REST API through an Orchestration in BizTalk Server 2013

• Download source - 27.1 KB

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.  

• BizTalk Server 2010: Invoke ReSTful Web Services 
• BizTalk Server 2013: REST Support through WCF-WebHttp  

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

1. Finalize the Bing URL for Geocoding and generate XML document.

   http://dev.virtualearth.net/REST/v1
   /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.

2. Generate the XML document by placing the URL in the browser.

   

3. Right click on the browser and select View Source and then save it locally as BingRESTResponse.xml.
4. 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

1. Open BizTalk Administration Console to create a new Send Port.
2. Choose the default ‘BizTalk Application 1’ or any other BizTalk Application of your choice.
3. 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.

4. 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.

5. 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}.

6. 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.

   

7. 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.

1. The 3^rd shape in the orchestration is used to send a GET request to the Bing Geocoding Service.

2. 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

3. The 4^th 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.
4. 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

1. 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

2. 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.

   

3. Make changes to the Query Address XML tag and save the file.
4. Import the bindings file (DSHS.GeoCoding.Bindings.xml) into BizTalk and deploy the solution correctly. Start the BizTalk Application.
5. Copy + Paste the file into the BizTalk Input Folder ‘C:\BizTalkDropLocations\DSHS.GeoCode\In’
6. Observe the GeoCode values in the BizTalk Output Folder ‘C:\BizTalkDropLocations\DSHS.GeoCode\Out’. See screenshot below.

   

7. 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.