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

本文链接：https://blog.youkuaiyun.com/xuxiaoping_cumt/article/details/549216

摘要：了解如何用新的客户数据服务下载方法来编程，以便从 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。