用 MapPoint Web Service 客户数据服务下载方法进行编程[转]

摘要：了解如何用新的客户数据服务下载方法来编程，以便从 MapPoint Web Service 客户服务站点 (CSS) 下载自定义的兴趣点数据。

单击此处下载本文中的代码示例。

本页内容

简介实现数据下载客户端关于数据文件格式小结附录 A — 下载 API 参考

简介

MapPoint Web Service 3.5 版引入了客户数据服务，您可以使用它以编程方式向 CSS 上载兴趣点数据。现在，客户数据服务已经进行了增强，以便您还可以下载兴趣点数据。该服务中已经添加了一组新的 API，以便于通过编程下载。

在向 MapPoint Web Service 服务器上载数据源之后，就可以使用 MapPoint Web Service 客户服务站点 (CSS) 上的工具来纠正无法正确进行地理编码的地址，或者向数据源中添加实体。但是，如果您以后重新上载该数据源，则通过 CSS 进行的更改将丢失。通过定期下载数据源并更新本地数据库，您可以确保 MapPoint Web Service 服务器上的数据源和本地数据库保持同步。

本文描述新的下载方法以及如何用它们编程。您可以从 Microsoft 下载中心下载本文中讨论的示例代码。本文假定您熟悉 MapPoint Web Service SOAP API 和客户数据服务 API。有关详细信息，请参阅 MapPoint Web Service SDK 中的 Developing with MapPoint Web Service 和 Introducing Customer Data Service。

返回页首

实现数据下载客户端

当您调用新的下载 API 方法时，数据并未以字节数组的形式直接返回到您的应用程序。相反，客户数据服务将您的兴趣点数据下载到某个文件，将该文件存储到 MapPoint Web Service 服务器上，然后返回一个可以用来访问该文件的 URL。该文件只能通过使用安全 (SSL/TLS) 通道上的凭据进行访问。在访问该文件之后，您就可以使用 Microsoft .NET Framework 中的典型 Web 客户端 API（例如，System.Net.WebClient）来轻松地检索数据了。该 URL 的有效期为两周。

数据下载客户端必须与客户数据服务 Web 服务进行通信，该服务的 Web 服务说明语言 (WSDL) 文档可以从以下位置获得：

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

当您在 Microsoft Visual Studio .NET 中将 WSDL 文档作为 Web 引用添加到项目中的时候，系统将自动为您生成下载方法的代理类。然后，您可以用三个简单的步骤来实现数据下载客户端：

1.

创建一个新的数据下载作业。

2.

轮询该作业的状态。

3.

在成功完成该作业以后，下载数据并将其存储到本地硬盘中。

下面各个部分将详细描述这些步骤。

创建一个新的下载作业

在该步骤中，您将使用 CustomerDataService.StartDownload 方法来创建一个新的下载作业。您还需要使用新的 DownloadSpecification 对象来指定多个特定于作业的参数，例如，环境（生产或阶段测试）、实体类型、数据源名称等等。对 StartDownload 的成功调用会返回一个唯一的作业 ID，以供您在随后的步骤中使用。该步骤还会启动实际的下载过程，在该过程中，客户数据服务会将您的兴趣点数据下载到某个您可以通过 URL 访问的安全位置。

以下代码示例演示了如何启动新的下载作业：

[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);

轮询该作业的状态

使用在前面的步骤中获得的作业 ID 来轮询客户数据服务 Web 服务，以确定下载作业是否成功完成。

以下代码示例演示了如何轮询作业状态直到下载作业完成：

[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);}

IsWaitingState 方法会检查 JobState 枚举的值，以确定作业是挂起还是正在进行。以下代码说明了 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;   }}

下载数据文件

当 JobState 设置为 CompletedSuccess 时，您可以使用 CustomerDataService.GetDownloadFileURL 方法来获得指向数据文件的 URL。以下代码说明了如何调用该方法：

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

现在您获得了 URL，接下来就可以使用 .NET Framework 中的 System.Net.WebClient 类将数据下载到本地文件：

[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);

现在，您已经成功地将数据从 CSS 下载到本地文件。

返回页首

关于数据文件格式

新的下载方法支持多种文件格式，包括压缩格式和非压缩格式。如果没有在 DownloadSpecification 对象中指定数据格式，则下载服务使用 Microsoft Access 2003 XML 格式作为默认格式。下表列出了受支持的文件格式。

文件格式说明

AccessXml2003

Microsoft Access 2003 XML 格式。这是下载方法所使用的默认格式。

AccessXml2002

Microsoft Access 2002 XML 格式。

TabDelimitedTextLatin1

带有 Latin 1 [ISO 8859-1] 编码的制表符分隔文本格式。

TabDelimitedTextUTF8

带有 UTF-8 [ISO 10646-1:2000 Annex D] 编码的制表符分隔文本格式。

PipeDelimitedTextLatin1

带有 Latin 1 [ISO 8859-1] 编码的管道线分隔文本格式。

PipeDelimitedTextUTF8

带有 UTF-8 [ISO 10646-1:2000 Annex D] 编码的管道线分隔文本格式。

CommaDelimitedTextLatin1

带有 Latin 1 [ISO 8859-1] 编码的逗号分隔文本格式。

CommaDelimitedTextUTF8

带有 UTF-8 [ISO 10646-1:2000 Annex D] 编码的逗号分隔文本格式。

当您使用 DownloadSpecification.Compressed 标志请求压缩文件时，数据将被压缩为 .zip 文件。

返回页首

小结

在本文中，您已经了解了下载方法的工作方式，以及如何使用新的下载方法和 .NET Framework 来生成数据下载客户端。在添加了下载方法以后，您现在就可以使用客户数据服务以编程方式上载和下载兴趣点数据。

返回页首

附录 A — 下载 API 参考

本部分包含添加到客户数据服务中的新类的参考文档。

DownloadSpecification 类

包含数据下载作业的规范。

公共字段名称说明

DataSourceName

代表包含要下载的兴趣点数据 (System.String) 的数据源的名称（DataSource.Name 属性）。

EntityTypeName

代表要下载的数据 (System.String) 的实体类型的名称（EntityType.Name 属性）。

Environment

指示应当从哪个环境下载数据。默认值为 Staging ([Namespace].LocationDataEnvironment)。

Format

所下载的数据的文件格式。默认值为 AccessXml2003 ([Namespace].FileFormat)。

Compressed

指示是否应当压缩数据的标志。默认值为 false (System.bool)。

CustomerDataService.StartDownload 方法

启动位置数据下载作业。该方法返回一个应当在随后的调用中使用的唯一作业 ID。

语法

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

参数

specification

数据下载作业的规范（DownloadSpecification 对象）。

备注

•

调用该方法将在 MapPoint Web Service 服务器上创建一个带有唯一 ID 的作业。该作业 ID 在随后对 GetDownloadFileURL 方法的调用中使用。

•

请始终将数据上载代理的 PreAuthenticate 属性设置为 true（在 Microsoft Visual Basic .NET 中为 True），以防止在数据上载过程中出现错误。

CustomerDataService.GetDownloadFileURL 方法

返回一个可以用来访问给定作业的数据文件的 URL。

语法

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

参数

jobID

数据下载作业的唯一 ID。