[Virtual Earth] Développement Microsoft Virtual Earth Web Services – Part 1

Au travers de mes stages et autres projets personnels, j’ai été amené à travailler avec des outils cartographiques divers (de Microsoft MapPoint à GoogleMap en passant par d’autres éditeurs dont je ne citerai pas le nom). Travaillant aujourd’hui majoritairement en environnement .NET, j’ai décidé de me pencher sur l’offre cartographique de Microsoft : Microsoft Virtual Earth.

Liens des posts sur blog:

1. Introduction à Microsoft Virtual Earth (Part 1)
2. Géocoding / Géocoding Inverse (Part 2)
3. Récupération des images satellites (Part 3)
4. Calcul d’itinéraires (Part 4)

Microsoft Virtual Earth ?

Virtual Earth est composé d’une série d’outils et de services Internet fournissant des informations cartographiques. Ces informations peuvent être de plusieurs types :

• Images satellites
• Du Géocoding : Traduire une adresse postale en coordonnées géographiques.
• Géocoding Inverse : Traduire des coordonnées géographiques en adresse postale.
• Moteur de recherche : A partir de données diverses, on récupère un ou plusieurs localisations (avec un degré de précision/confiance).
• Calcul d’itinéraire : A partir de deux adresses/localisations, on récupère l’ensemble du chemin à effectuer en voiture (orientation lors des croisements, distance entre chaque croisement…).

Microsoft Virtual Earth : Comment ça marche ?

A l’inverse de Microsoft MapPoint où les données devait être stockés sur le poste client (ou sur des postes serveurs proche du client), les données de Virtual Earth sont stockées sur les datacenter Microsoft à travers le monde et l’utilisateur ne demande que les données qu’il souhaite visualiser.

Ces données ne sont pas accessible directement depuis les datacenters. Il faut passer par une couche de services Web pour y accéder. Il existe deux façons de faire :

• Utilisation d’un contrôle ASP.NET Ajax fourni avec le SDK de Virtual Earth (démonstration : http://maps.live.com/)
• Utilisation du Web Service Virtual Earth (SOAP over HTTP)

Nous ne parlerons pas du contrôle ASP.NET dans ce tutorial. Vous pourrez trouver les informations voulues pour le développement avec ce type de contrôle à l’adresse suivante : http://dev.live.com/Virtualearth/sdk/

Microsoft Virtual Earth Web Service

Virtual Earth est composé de 5 Web Services :

• Common (asmx) : Web Service contenant l’ensemble des données communes à tous les services Virtual Earth ainsi que les fonctions d’authentification et de sécurité.
• Geocode Service (WCF) : Web Service de Géocoding/Géocoding Inverse.
• Route Service (WCF) : Web Service de calcul d’itinéraire.
• Imagery Service (WCF) : Web Service de récupération des images.
• Search Service (WCF) : Web Service du moteur de recherche.

Microsoft Virtual Earth Web Service : Authentification

L’authentification à Virtual Earth se réalise en deux étapes :

1. Le client fournit un couple login/password au Web Service Common.
2. Si les informations sont correctes, le Web Service renvoie un token d’authentification sous la forme d’une longue chaine de caractères.

Les appels suivants à l’ensemble des Web Services  Virtual Earth se fera toujours en fournissant ce token.

Dans ce tutorial, nous allons voir comment récupérer un token d’authentification puis faire un appel à une fonction de Geocoding.

• Récupération Login/Password sur la plateforme développeur Virtual Earth

Avant toute chose, il faut récupérer un couple login/password auprès de Microsoft. Pour cela, il faut une Windows Live ID (https://login.live.com).

Il faut ensuite se connecter sur la plateforme développeur Virtual Earth (https://mappoint-css.live.com/mwssignup) pour demander un compte “free evaluation developer account”. Ce type de compte est gratuit et comporte certaines limitations comme des images contenant des messages “Staging" au milieu des images satellites et une déconnexion automatique en cas d’un nombre trop important de requêtes (j’ai été très peu déconnecté pour ce motif en utilisant les services).

Une fois inscrit, aller dans “Manage account” pour récupérer votre “Account ID”  (i.e login) et pour définir votre mot de passe.

• Configuration de la solution Visual Studio

Créer une nouvelle solution (selon le type de projet que vous souhaitez faire).

Nous allons ajouter une référence Web vers le Web Service Common. Cliquer droit sur le projet puis aller dans “Add Service Reference”. Au sein de cette fenêtre, cliquer sur “Advanced” en bas à gauche puis sur “Add Web Reference”. Indiquer dans URL l’adresse : https://staging.common.virtualearth.net/find-30/common.asmx?wsdl. Il est possible qu’une popup vous demande vos informations de login/password. Une fois validé, indiquer un nom pour la Web Reference (TokenService dans notre exemple) puis cliquer sur “Add Reference”. Il est à noter que cette opération est longue car le Web Service Common est un service asmx (ancienne génération).

Pour chacun des autres Web Service WCF, il suffit de faire “Add Service Reference” puis d’indiquer une des quatre adresses suivantes puis cliquer sur “GO” puis donner un nom de namespace (le nom des services dans la liste suivante est un convention de ma part) puis cliquer sur “Add Reference”:

• GeoCodeService : http://staging.dev.virtualearth.net/webservices/v1/geocodeservice/geocodeservice.svc 
• ImageryService : http://staging.dev.virtualearth.net/webservices/v1/imageryservice/imageryservice.svc
• RouteService : http://staging.dev.virtualearth.net/webservices/v1/routeservice/routeservice.svc 
• SearchService : http://staging.dev.virtualearth.net/webservices/v1/searchservice/searchservice.svc
• Récupération d’un Token Virtual Earth

Ne pas oublier d’inclure les lignes suivantes au début du code :

using VETutorial.TokenService;
using System.Net;

//Récupération de l'adresse locale
string ipadr = "127.0.0.1";
var host = Dns.GetHostEntry(Dns.GetHostName());
foreach (IPAddress ip in host.AddressList)
{
	if (ip.AddressFamily == System.Net.Sockets.AddressFamily.InterNetwork ||
	    ip.AddressFamily == System.Net.Sockets.AddressFamily.InterNetworkV6)
	{
		ipadr = ip.ToString();
	}
}
//Création du proxy d'accès au CommonService
CommonService common = new VETutorial.TokenService.CommonService();
common.Credentials = new NetworkCredential("AccountID", "password");
TokenSpecification tokenSpec = new TokenSpecification();
//Adresse IP de la machine du client
tokenSpec.ClientIPAddress = ipadr;
//Durée de validité du token (entre 15 et 480 minutes)
tokenSpec.TokenValidityDurationMinutes = 20;  

//Appel au Web Service Common pour récupération du token
string token = common.GetClientToken(tokenSpec);

On commence par récupérer l’adresse IP locale visible de l’extérieur. Cette adresse nous sera nécessaire pour la partie d’authentification (cette étape est inutile pour les applications Web).

On instancie ensuite la classe proxy CommonService puis on lui fournit le couple login/password récupéré sur la plateforme développeur. Cela se fait grâce à la propriété Credential de CommonService. On crée un NetworkCredential auquel on passe les informations nécessaires et on attribut ce NetworkCredential à la propriété Credential de CommonService.

La récupération d’un token se réalise grâce à la méthode GetClientToken (existe en version synchrone et asynchrone) à laquelle on passe un objet TokenSpecification.

Le TokenSpécification contient :

• Propriété TokenValidityDurationMinutes: Le temps de validité du token en minutes (entre 15 et 480 minutes)
• Propriété ClientIPAddress : L’adresse IP du client (inutile pour une application Web).

GetClientToken renvoie une chaine de caractères contenant le token.

• Appel à une méthode Géocoding

Afin de vérifier que tout est bien configurer, on va demander les coordonnées géographiques de la ville de Paris.

GeocodeServiceClient geoCodeSvc = new GeocodeServiceClient();
GeocodeRequest geoCodeRequest = new GeocodeRequest();
geoCodeRequest.Credentials = new Credentials();
geoCodeRequest.Credentials.Token = token;
geoCodeRequest.Query = "Paris";
var result = geoCodeSvc.Geocode(geoCodeRequest);

On instancie un proxy pour GeocodeService. On crée un objet GeocodeServiceClient contenant une méthode GeoCode qui prend un paramètre un GeocodeRequest contenant les informations nécessaires à la requête. En général, les paramètres de requêtes des Web Services Virtual Earth demandent le token d’authentification dans la propriété Credential.Token. Afin de faire la recherche la plus simple possible, on fournit une chaine de caractères contenant “Paris” à la propriété Query. (nous reviendrons sur les requêtes plus complexe de Géocoding dans un autre post).

On obtient un GeoCodeResponse en retour qui nous fournit un certain nombre d’informations dont la localisation exacte de la ville de Paris.

Dans un prochain post, nous verrons plus en détail le Géocoding (et Géocoding Inverse) ainsi que les requêtes basiques au Web Service d’imagerie satellite.