你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

迁移必应地图“获取图像元数据”API

2024-05-27

本文介绍如何将必应地图获取图像元数据 API 迁移到 Azure Maps 获取地图图块 API。

Azure Maps“获取地图图块”API 提供用于 Azure Maps Web SDK 或第三方地图控件的矢量或光栅格式的地图图块。可以请求的一些示例磁贴包括 Azure Maps 道路、卫星/航空或天气雷达。

先决条件

显著差异

必应地图“获取图像元数据”API 在 HTML 响应的正文中提供地图图块元数据，包括用于获取地图图块图像的 URL (ImageUrl)。 Azure Maps“获取地图图块”API 直接在 HTML 响应中提供地图图块图像，但不包括元数据。
必应地图“获取图像元数据”API 在 HTML 响应的正文中提供地图图块元数据，包括地图图块老式信息（vintageStart 和 vintageEnd）。 Azure Maps“获取地图图块”API 在响应头 (Data-Capture-Date-Range) 而不是 HTML 响应正文中提供地图图块老式信息。
必应地图“获取图像元数据”API 在 HTML 响应的正文中提供地图图块元数据，包括地图图块的版权信息。对于 Azure Maps“获取地图图块”API，可以从 Azure Maps 获取地图归属 API 获取地图版权归属信息。版权归属信息应根据 Azure Maps 产品条款在地图上显示。
Azure Maps“获取地图图块”API 不提供以下必应地图“获取图像元数据”API 地图样式：街边、鸟瞰和地形测量。
Azure Maps“获取地图图块”API 目前不提供带有道路标签的卫星/航拍地图样式，如必应地图“获取图像元数据”API AerialWithLabelsOnDemand 地图样式。但是，Azure Maps Web SDK 确实提供了一种称为 satellite_road_labels 的类地图样式。
必应地图“获取图像元数据”API 提供 256 x 256 像素图块大小。 Azure Maps“获取地图图块”API 提供 256 x 256 像素图块大小和 512 x 512 像素图块大小。有关详细信息，请参阅 MapTileSize。
必应地图“获取图像元数据”API 支持 XML 和 JSON 响应格式，而 Azure Maps“获取地图图块”API 仅支持 JSON。
必应地图“获取图像元数据”API 使用 imagerySet URI 参数提供地图样式的基图，如道路和卫星/混合基图。 Azure Maps“获取地图图块”API 使用 TilesetID URI 参数提供类似的产品/服务基图。 Azure Maps TilesetID 不支持“获取地图图块”中的 AerialWithLabelsOnDemand 或 AerialWithLabels 图块。混合图块仅在 Azure Maps Web SDK 地图控件中可用。
与必应地图企业版不同，Azure Maps 是一项支持指定地理范围的全球服务，允许将数据驻留限制为欧洲 (EU) 或美国 (US) 地理区域（地区）。所有请求（包括输入数据）都专门在指定的地理区域进行处理。有关详细信息，请参阅 Azure Maps 服务地理范围。

安全性和身份验证

必应地图企业版仅支持 API 密钥身份验证。 Azure Maps 支持通过多种方式对 API 调用进行身份验证，例如订阅密钥、Microsoft Entra ID 和共享访问签名 (SAS) 令牌。有关 Azure Maps 中的安全性和身份验证的详细信息，请参阅 Azure Maps 身份验证和 Azure Maps“获取地图图块”文档中的“安全性”部分。

请求参数

下表列出了必应地图“获取图像元数据”请求参数和 Azure Maps 等效参数：

必应地图请求参数	必应地图请求参数别名	Azure Maps 请求参数	Azure Maps 中必需	Azure Maps 数据类型	说明
imagerySet	无	tilesetId	True	TilesetID	Azure Maps 具有必应地图“获取图像元数据”API 没有的一些地图样式。必应地图“获取图像元数据”API 具有 Azure Maps 没有的一些地图样式。有关 Azure Maps 提供的地图样式的详细信息，请参阅 TilesetID。
centerPoint	无	x y	True	整数 (int32)	有关 X、Y 坐标的详细信息，请参阅缩放级别和图块网格。
culture	c	语言	False	字符串	有关详细信息，请参阅 Azure Maps 支持的语言。
include	incl	NA	NA	NA	必应地图中此参数的唯一选项是 `ImageryProviders`。指定后，将在响应中返回有关图像提供商的归属信息，该信息应在地图上显示。对于 Azure Maps“获取地图图块”API，可以从 Azure Maps 获取地图归属 API 获取地图版权归属信息。版权归属信息应根据 Azure Maps 产品条款在地图上显示。
mapLayer	ml	NA	N/A	NA
orientation	dir	NA	NA	NA	适用于 Azure Maps 中不支持的必应地图鸟瞰地图样式。
uriScheme		NA	NA	NA
zoomLevel	zl	zoom	True	整数 (int32)	有关 X、Y 坐标的详细信息，请参阅缩放级别和图块网格。

有关 Azure Maps 请求参数的详细信息，请参阅 URI 参数。

请求示例

必应地图“获取图像元数据”API 请求：

http://dev.virtualearth.net/REST/V1/Imagery/Metadata/road/37.770864,-122.467217?zl=15&key={YourBingMapsKey}

Azure Maps“获取地图图块”API 请求：

https://atlas.microsoft.com/map/tile?api-version=2022-08-01&tilesetId=microsoft.base.&zoom=15&x=5236&y=12665&tileSize=256&subscription-key={Your-Azure-Maps-Subscription-key}

响应字段

下表列出了运行必应地图“获取图像元数据”API 和 Azure Maps 等效 API 时，HTTP 响应中可能出现的字段：

必应地图响应字段	Azure Maps 响应字段	说明
imageHeight (Json) ImageWidth (XML)	不支持	Azure Maps“获取地图图块”API 直接在 HTML 响应中提供地图图块图像（二进制图像字符串），并提供 256 x 256 和 512 x 512 像素图块大小。
imageUrl (Json) ImageUrl (XML)	不支持	Azure Maps 获取地图磁贴 API 可直接在 HTML 响应中提供地图磁贴图像（二进制图像字符串），而不是图像 URL。
imageUrlSubdomains (Json) ImageUrlSubdomains (XML)	不支持	Azure Maps 获取地图磁贴 API 可直接在 HTML 响应中提供地图磁贴图像（二进制图像字符串），而不是图像 URL。
imageWidth (Json) ImageWidth (XML)	不支持	Azure Maps“获取地图图块”API 直接在 HTML 响应中提供地图图块图像（二进制图像字符串），并提供 256 x 256 和 512 x 512 像素图块大小。
vintageEnd (Json) VintageEnd (XML)	不支持	Azure Maps“获取地图图块”API 在响应头 (Data-Capture-Date-Range¹) 而不是响应正文中提供地图图块老式信息。
vintageStart (Json) VintageStart (XML)	不支持	Azure Maps“获取地图图块”API 在响应头 (Data-Capture-Date-Range¹) 而不是响应正文中提供地图图块老式信息。
zoomMax (Json) ZoonMax (XML)	不支持	有关地图图块样式支持的缩放级别和最大缩放的信息，请参阅缩放级别和图块网格和 TilesetID。
zoomMin (Json) ZoomMin (XML)	不支持	有关地图图块样式支持的缩放级别和最大缩放的信息，请参阅缩放级别和图块网格和 TilesetID。

¹ 使用 Azure Maps API 获取 RGB 卫星图像时，还可以检索有关获取日期的信息。 HTTP 响应包括名为 Data-Capture-Date-Range 的标头，该标头提供用于指示图像捕获时间的日期范围。例如，它可能显示为“7/31/2022-9/1/2023”。请记住，由于需要批处理或将不同日期的多个图像拼接在一起以创建无缝地图，卫星图像通常会跨越一个日期范围。因此，当单个日期并不始终适用时，日期范围可让你了解图像数据是何时收集的。

有关 Azure Maps“获取地图图块”API 响应字段的详细信息，请参阅响应。

响应示例

以下 JSON 示例显示了执行必应地图“获取图像元数据”请求时，HTTP 响应正文中返回的内容：

{ 
    "authenticationResultCode": "ValidCredentials", 
    "brandLogoUri": "https://dev.virtualearth.net/Branding/logo_powered_by.png", 
    "copyright": "Copyright © 2024 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.", 
    "resourceSets": [ 
        { 
            "estimatedTotal": 1, 
            "resources": [ 
                { 
                    "__type": "ImageryMetadata:http://schemas.microsoft.com/search/local/ws/rest/v1", 
                    "imageHeight": 256, 
                    "imageUrl": "http://ecn.t2.tiles.virtualearth.net/tiles/r023010203332102.jpeg?g=14374&mkt={culture}&shading=hill", 
                    "imageUrlSubdomains": null, 
                    "imageWidth": 256, 
                    "imageryProviders": null, 
                    "vintageEnd": "02 Dec 2019 GMT", 
                    "vintageStart": "02 Dec 2019 GMT", 
                    "zoomMax": 15, 
                    "zoomMin": 15 
                } 
            ] 
        } 
    ], 
    "statusCode": 200, 
    "statusDescription": "OK", 
    "traceId": "c0630758c8475d6f60d65af81b548c6f|MWH0032BEB|0.0.0.1" 
}

以下 JSON 示例显示了执行 Azure Maps“获取地图图块”请求时，HTTP 响应正文中返回的内容：

状态代码：200

Content-Type: application/vnd.mapbox-vector-tile

响应正文

"binary image string"

事务使用情况

必应地图“获取图像元数据”API 会针对每个 API 请求生成一个计费事务。 Azure Maps“获取地图图块”API 会针对每 15 个图块生成一个计费事务。有关 Azure Maps 事务的详细信息，请参阅了解 Azure Maps 事务。

其他信息

如需了解更多 Azure Maps 呈现 API，请参阅：

获取地图归属：用于获取图块的地图版权归属信息。
获取地图静态图像：用于呈现用户定义的矩形图像，其中包含某个地图部分。

支持

Microsoft Q&A 论坛