Programando com os métodos de download do Customer Data Service do MapPoint Web Service

Chandu Thota

Microsoft Corporation

Novembro de 2004

Aplica-se a:

• Microsoft MapPoint Web Service, versão 3.5 e posterior

Resumo: Aprenda a programar com os novos métodos de download do Customer Data Service para baixar dados personalizados de interesse do CSS (Customer Services Site - Site de Atendimento ao Cliente) do MapPoint Web Service. (7 páginas impressas)

Nesta página

Introdução
Implementando um cliente de download de dados
Sobre os formatos de arquivo de dados
Conclusão
Apêndice A — Referência à API de download

Introdução

O Customer Data Service, que pode ser usado para carregar os dados de interesse para o CSS por meio de programação, foi introduzido com o MapPoint Web Service, versão 3.5. Agora, o Customer Data Service foi aprimorado para que você também possa baixar os dados de interesse. Um novo conjunto de APIs foi adicionado ao serviço para facilitar os downloads programáticos.

Depois de carregar uma fonte de dados para os servidores do MapPoint Web Service, você pode usar as ferramentas do CSS do MapPoint Web Service para corrigir os endereços que não puderam ser codificados corretamente quanto ao local ou para adicionar entidades à fonte de dados. No entanto, se você carregar essa fonte de dados novamente mais tarde, as alterações realizadas através do CSS serão perdidas. Ao baixar com regularidade suas fontes de dados e atualizar o banco de dados local, você poderá garantir que as fontes de dados nos servidores do MapPoint Web Service e no seu banco de dados local permaneçam sincronizadas.

Este artigo descreve os novos métodos de download e mostra como programar com eles. O código de exemplo abordado neste artigo está disponível para download a partir da Central de Download da Microsoft. Este artigo assume que você esteja familiarizado com a API SOAP do MapPoint Web Service e a API do Customer Data Service. Para obter mais informações, consulte Developing with MapPoint Web Service (Desenvolvendo com o MapPoint Web Service) e Introducing Customer Data Service (Apresentando o Customer Data Service) no SDK do MapPoint Web Service (em inglês).

Implementando um cliente de download de dados

Ao chamar os novos métodos de download da API, os dados não são retornados diretamente para o aplicativo na forma de uma matriz de bytes. Em vez disso, o Customer Data Service baixa seus dados de interesse para um arquivo, armazena-os em servidores do MapPoint Web Service e retorna uma URL que pode ser usada para acessar o arquivo. Esse arquivo somente pode ser acessado com o uso de credenciais por um canal (SSL/TLS) seguro. Quando você acessar o arquivo, poderá facilmente recuperar os dados usando APIs típicas do cliente da Web, como System.Net.WebClient no Microsoft .NET Framework. O tempo de vida da URL é de duas semanas.

Seu cliente de download de dados deve se comunicar com o serviço da Web Customer Data Service, cujo documento WSDL (Web Service Description Language) está disponível no seguinte local:

https://mappoint-css.partners.extranet.microsoft.com/CustomerData-30/CustomerDataService.wsdl

Ao adicionar o documento WSDL ao projeto como uma referência da Web no Microsoft Visual Studio .NET, as classes de proxy dos métodos de download são geradas automaticamente para você. Você pode, então, implementar o cliente de download de dados em três etapas simples:

1. Crie um novo trabalho de download de dados.

2. Pesquise o status do trabalho.

3. Quando o trabalho for concluído com êxito, baixe e armazene os dados no disco rígido local.

As seções a seguir tratam dessas etapas em detalhes.

Crie um novo trabalho de download

Nessa etapa, você cria um novo trabalho de download usando o método CustomerDataService.StartDownload. Você especifica também diversos parâmetros específicos do trabalho, como o ambiente (de produção ou temporário), o tipo de entidade, o nome da fonte de dados e assim por diante, usando o novo objeto DownloadSpecification. Uma chamada com êxito a StartDownload retorna uma identificação exclusiva do trabalho que é usada em etapas subseqüentes. Essa etapa também inicia o processo de download real, no qual o Customer Data Service baixa os dados de interesse para um local seguro que pode ser acessado por uma URL.

O exemplo de código a seguir demonstra como iniciar um novo trabalho de download:

[C#]
//Define the DownloadSpecification object.
DownloadSpecification specification = new DownloadSpecification();

//Create the Customer Data Service proxy.
CustomerDataService DownloadService = new CustomerDataService();

//Set the PreAuthenticate property to true.
DownloadService.PreAuthenticate = true;

//Assign your CSS credentials to access the 
//Web service API.
DownloadService.Credentials = 
     new System.Net.NetworkCredential(userName, password);
         
//Start the download job.
string jobID = DownloadService.StartDownload(specification);	
	

Pesquise o status do trabalho

Usando a identificação do trabalho obtida na etapa anterior, você pesquisa o serviço da Web Customer Data Service para determinar se o trabalho de download foi concluído com êxito.

O exemplo de código a seguir demonstra como pesquisar o status do trabalho até a conclusão do trabalho de download:

	[C#]
	//Get the job state.
	JobState jobState = DownloadService.GetJobState(jobID);
	
	//Call IsWaitingState to check the
	//status of the job.
	while(IsWaitingState(jobState))
	{
	    //Wait for 60 seconds before polling
	    //again.
	    Thread.Sleep(60 * 1000);
	    //Get the job state again.
	    jobState = DownloadService.GetJobState(jobID);
	}	
	

O método IsWaitingState verifica o valor da enumeração JobState para determinar se o trabalho está pendente ou em andamento. O código a seguir mostra a implementação do método IsWaitingState:

// Determine whetehr the job is still being processed.
bool IsWaitingState(JobState state)
{
   switch (state)
   {
      //If the job is in progress
                //or pending
                //IsWaitingState returns a value of true..
      case JobState.Pending:
      case JobState.InProcess:
         return true;
      default:
         return false;
   }
}	
	

Baixe o arquivo de dados

Quando JobState for definido como CompletedSuccess, você pode obter a URL para o arquivo de dados usando o método CustomerDataService.GetDownloadFileURL. O código a seguir mostra como invocar esse método:

[C#]
//Get the URL to the download file.
string fileUrl = DownloadService.GetDownloadFileURL(jobID);	
	

Agora que você tem a URL, pode baixar os dados para um arquivo local usando a classe System.Net.WebClient a partir do .NET Framework:

[C#]
//Define a valid local file path.
string localFile = @"C:\Downloads\data.csv";
//Create a new WebClient instance.
System.Net.WebClient client = new System.Net.WebClient();
//Assign your CSS credentials.
client.Credentials = DownloadService.Credentials;
//Download the data to a local file.
client.DownloadFile(fileUrl, localFile);	
	

Você acabou de baixar seus dados do CSS para um arquivo local com êxito.

Sobre os formatos de arquivo de dados

Os novos métodos de download oferecem suporte a vários formatos de arquivo, tanto compactados quanto descompactados. Se nenhum formato de dados for especificado no objeto DownloadSpecification, o serviço de download usará o formato XML do Microsoft Access 2003 por padrão. A tabela a seguir lista os formatos de arquivo com suporte.

Ao solicitar um arquivo compactado com o uso do sinalizador DownloadSpecification.Compressed, seus dados serão compactados como um arquivo .zip.

Conclusão

Neste artigo, você aprendeu como os métodos de download funcionam e como criar um cliente de download de dados usando os novos métodos de download e o .NET Framework. Com a adição dos métodos de download, você agora pode usar o Customer Data Service para carregar e baixar os dados de interesse por meio de programação.

Apêndice A — Referência à API de download

Esta seção contém documentação de referência para as novas classes adicionadas ao Customer Data Service.

Classe DownloadSpecification

Contém as especificações para um trabalho de download de dados.

Campos públicos

Método CustomerDataService.StartDownload

Inicia um trabalho de download de dados de local. Esse método retorna uma identificação exclusiva do trabalho que deve ser usada em chamadas subseqüentes.

Sintaxe

[Visual Basic]
Public Function StartDownload (specification As DownloadSpecification)
      _ As System.String
[C#]
public System.String StartDownload (DownloadSpecification specification);	
	

Parâmetros

specification

As especificações (objeto DownloadSpecification) do trabalho de download de dados.

Comentários

• Chamar esse método cria um trabalho com uma identificação exclusiva no servidor do MapPoint Web Service. A identificação do trabalho é usada em chamadas subseqüentes ao método GetDownloadFileURL.

• Defina sempre a propriedade PreAuthenticate do proxy de carga de dados como true (True no Microsoft Visual Basic .NET) para evitar erros durante o processo de carga de dados.

Método CustomerDataService.GetDownloadFileURL

Retorna uma URL que pode ser usada para acessar o arquivo de dados de um determinado trabalho.

Sintaxe

[Visual Basic]
Public Function GetDownloadFileURL (jobID as string)
      _ As System.String
[C#]
public System.String GetDownloadFileURL (string jobID);	
	

Parâmetros

jobID

A identificação exclusiva do trabalho de download de dados.