迁移

从 Bing Maps REST Services 迁移

Bing Maps REST Services 有一种辨识度很高的响应结构:一个顶层对象包含 resourceSets 数组,每个元素包含 resources,每个资源带有一个 point 对象,其坐标嵌套在 coordinates 数组中,而不是分开的纬度和经度字段。基于它进行开发的开发者(通常在以 .NET 为主、Bing Maps 是自然之选的团队中)对这种结构了如指掌,而围绕另一种结构重写代码,正是那种让迁移一拖数月、迟迟排不上日程的默默无闻又乏味的工作。

通过 Bing Maps Dev Center 生成的密钥以查询参数的形式发送,这是大多数面向消费者的地图 API 共有的模式。集成的这一部分通常最不让人担心;真正的耦合在于响应解析。

My Geocode 运行着一个 Bing Maps 兼容主机,完全重现这种 resourceSets 结构,因此读取 resourceSets[0].resources[0].point.coordinates 的解析代码在切换后可以继续工作。响应中唯一与 Bing 原始结构不同的内容是版权、条款和隐私文本,这部分必须是我们自己的。完整详情见 /compatibility/bing-maps/

切换之前值得检查的几件事:

  • 确认您的代码是否读取置信度或匹配代码字段,因为这些字段值得快速并排比较一下
  • 确认您的客户端库使用哪种认证方式;密钥可以通过 X-API-KeyAuthorization: Bearer、HTTP Basic 认证或查询参数发送,因此您的库现在使用的任何一种方式都应继续有效
  • 决定是否要通过 mg_extras=1 开启可选的附加字段(海拔、IP 威胁、网络详情),因为它们与标准结构并存,而不是取而代之

相比之下,商业方面就简单多了。没有设置结算账户的步骤:完全不用密钥即可每天免费请求 2,500 次,每个密钥还有自己的每天 2,500 次免费请求,按网络计算。超出这一额度后,可以使用每次请求 €0.0001 的预付额度,或每月 €50 的 Unlimited 密钥,兼容主机的费用与平台上其他所有端点相同。

对于将地理编码作为大型 .NET 或企业应用一部分运行的团队来说,迁移的范围通常比从外部看起来要小,因为 resourceSets 包装结构通常是通过少数几个封装良好的访问器方法读取的,而不是以内联方式散落在整个代码库中。先找到这些访问点,然后在预发布环境中将它们指向新主机,是在触及生产流量之前验证切换的合理方法。

如果您的集成在地理编码之外还调用了 Bing 的时区或海拔端点,这些需要单独处理,因为 My Geocode 自己的时区和海拔查询独立于地理编码兼容主机工作,值得按其自身的方式单独接入,而不是强行让它们走同一条代码路径。完整的配额详情,包括每个请求都带有的 X-Quota-Limit 及相关响应头,记录在 /docs/rate-limits/