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

Render - Get Map Tile

服务:: Maps

API 版本:: 2024-04-01

用于请求矢量或光栅格式的地图磁贴。
该 Get Map Tiles API 使用户能够请求矢量或栅格格式的地图切片，通常用于集成到地图控件或 SDK 中。支持的瓦片类型包括Azure Maps道路瓦片和实时天气雷达瓦片。默认情况下，Azure Maps Web SDK 使用矢量图块来渲染其网页地图控件。

Important

使用 Get Map Tile API时，你还必须调用 Get Map Attribution API，获取所需的地图数据归属文本。

返回的归属必须显示在从 Get Map Tile 提取的图块渲染处，包括第三方地图控件或自定义渲染实现。

GET {endpoint}/map/tile?api-version=2024-04-01&tilesetId={tilesetId}&zoom={zoom}&x={x}&y={y}

具有可选参数:

GET {endpoint}/map/tile?api-version=2024-04-01&tilesetId={tilesetId}&zoom={zoom}&x={x}&y={y}&timeStamp={timeStamp}&tileSize={tileSize}&language={language}&view={view}

URI 参数

名称	在	必需	类型	说明
endpoint	path	True	string (uri)	Azure Maps 服务主机名。 Azure公有云使用`https://atlas.microsoft.com`。要针对特定Azure Maps地理或主权云，请参见Azure Maps地理范围。
api-version	query	True	string minLength: 1	用于此作的 API 版本。
tilesetId	query	True	TilesetID	图块集是一组光栅或矢量数据，按照预设的缩放级别被划分为统一的方形图块网格。每个图块集都有一个在发出请求时要使用的 tilesetId。 Azure Maps提供的现成图块集如下所示。例如，microsoft.base。
x	query	True	integer (int32)	缩放网格上磁贴的 X 坐标。值必须位于 [0， 2^zoom -1] 范围内。有关详细信息，请参阅缩放级别和磁贴网格。
y	query	True	integer (int32)	缩放网格上磁贴的 Y 坐标。值必须位于 [0， 2^zoom -1] 范围内。有关详细信息，请参阅缩放级别和磁贴网格。
zoom	query	True	integer (int32)	所需磁贴的缩放级别。有关详细信息，请参阅缩放级别和磁贴网格。
language	query		string	应返回搜索结果的语言。应该是受支持的 IETF 语言标记之一，不区分大小写。当指定语言中的数据不适用于特定字段时，将使用默认语言。有关详细信息，请参阅支持的语言。
tileSize	query		MapTileSize	返回的地图磁贴的大小（以像素为单位）。
timeStamp	query		string (date-time)	所请求磁贴的所需日期和时间。此参数必须采用标准日期/时间格式（例如 2019-11-14T16：03：00-08：00），ISO 8601定义。仅当 tilesetId 参数设置为以下值之一时，才支持此参数。 microsoft.weather.infrared.main：我们过去最多提供 3 小时的磁贴。磁贴的间隔为 10 分钟。我们将 timeStamp 值舍入为最接近的 10 分钟时间范围。 microsoft.weather.radar.main：我们过去提供最多 1.5 小时的磁贴，将来最多提供 2 小时。磁贴的间隔为 5 分钟。我们将 timeStamp 值舍入到最接近的 5 分钟时间范围。
view	query		LocalizedMapView	View 参数（也称为“用户区域”参数）允许为地缘政治争议区域显示特定国家/地区的正确地图。不同的国家/地区具有此类区域的不同视图，并且 View 参数允许应用程序符合应用程序将提供服务的国家/地区所需的视图。默认情况下，即使尚未在请求中定义该参数，View 参数也会设置为“Unified”。由你负责确定用户的位置，然后为该位置正确设置 View 参数。或者，可以选择设置“View=Auto”，这将基于请求的 IP 地址返回地图数据。 Azure Maps中的视图参数必须遵守相关法律，包括地图、图片及其他数据和您被授权通过Azure Maps访问的第三方内容所在国家/地区的相关法律。示例：view=IN。有关详细信息，请参阅支持的视图，并查看可用的视图。

请求标头

名称	必需	类型	说明
x-ms-client-id		string	表示该账户用于Microsoft Entra ID安全模型。该Azure Maps账户的唯一ID可从Azure Maps管理平面账户API获得。有关在Azure Maps中使用Microsoft Entra ID安全的更多信息，请参见管理认证在Azure Maps。

响应

名称	类型	说明
200 OK	string	请求已成功。 Media Types: "application/json", "image/jpeg", "image/png", "image/pbf", "application/vnd.mapbox-vector-tile"
Other Status Codes	ErrorResponse	意外错误响应。 Media Types: "application/json", "image/jpeg", "image/png", "image/pbf", "application/vnd.mapbox-vector-tile"

名称

类型

说明

200 OK

string

请求已成功。

Media Types: "application/json", "image/jpeg", "image/png", "image/pbf", "application/vnd.mapbox-vector-tile"

Other Status Codes

ErrorResponse

意外错误响应。

Media Types: "application/json", "image/jpeg", "image/png", "image/pbf", "application/vnd.mapbox-vector-tile"

安全性

AadToken

这些是Microsoft Entra OAuth 2.0流量。当与Azure基于角色的访问控制配合使用时，可以用来控制对Azure Maps REST API的访问。 Azure 基于角色的访问控制用于指定对一个或多个 Azure Maps 资源账户或子资源的访问。任何用户、组或服务主体都可以通过内置角色或由一个或多个对 Azure Maps REST API 的权限组成的自定义角色授予访问权限。

若要实现方案，建议查看身份验证概念。总之，此安全定义提供了一种解决方案，用于通过能够针对特定 API 和范围进行访问控制的对象对应用程序建模。

注释

此安全定义要求使用 x-ms-client-id 标头来指示应用程序请求访问的 Azure Maps 资源。这可以从地图管理 API获取。
Authorization URL 特定于 Azure 公有云实例。主权云拥有独特的授权URL和Microsoft Entra ID配置。
Azure 基于角色的访问控制是通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 从 Azure 管理平面配置的。
使用 Azure Maps Web SDK 允许为多个用例设置基于应用程序的配置。
有关Microsoft标识平台的详细信息，请参阅 Microsoft标识平台概述。

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/authorize

作用域

名称	说明
https://atlas.microsoft.com/.default

subscription-key

这是在 Azure 门户中或使用 PowerShell、CLI、Azure SDK 或 REST API 创建 Azure Maps 帐户时预配的共享密钥。

使用此密钥，任何应用程序都可以访问所有 REST API。换句话说，此密钥可用作颁发密钥的帐户中的主密钥。

对于公开的应用程序，我们建议使用机密客户端应用程序方法来访问 Azure Maps REST API，以便安全地存储密钥。

类型: apiKey
在: header

SAS Token

这是一个共享访问签名令牌，它通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面在 azure Maps 资源上的列表 SAS 操作创建。

使用此令牌，任何应用程序都有权使用 Azure 基于角色的访问控制进行访问，并精细控制特定令牌的过期、速率和区域。换句话说，SAS 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。

对于公开的应用程序，建议在映射帐户资源上配置允许的源的特定列表，以限制呈现滥用并定期续订 SAS 令牌。

类型: apiKey
在: header

示例

Successful Tile Request

示例请求

HTTP

GET https://atlas.microsoft.com/map/tile?api-version=2024-04-01&tilesetId=microsoft.base&zoom=6&x=10&y=22

示例响应

状态代码:: 200

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

"binary image string"

定义

名称	说明
ErrorAdditionalInfo	资源管理错误附加信息。
ErrorDetail	错误详细信息。
ErrorResponse	所有 Azure 资源管理器 API 的通用错误响应，用于返回失败操作的错误细节。（这也遵循 OData 错误响应格式）。
LocalizedMapView	View 参数（也称为“用户区域”参数）允许为地缘政治争议区域显示特定国家/地区的正确地图。不同的国家/地区具有此类区域的不同视图，并且 View 参数允许应用程序符合应用程序将提供服务的国家/地区所需的视图。默认情况下，即使尚未在请求中定义该参数，View 参数也会设置为“Unified”。由你负责确定用户的位置，然后为该位置正确设置 View 参数。或者，可以选择设置“View=Auto”，这将基于请求的 IP 地址返回地图数据。 Azure Maps中的视图参数必须遵守相关法律，包括地图、图片及其他数据和您被授权通过Azure Maps访问的第三方内容所在国家/地区的相关法律。示例：view=IN。有关详细信息，请参阅支持的视图，并查看可用的视图。
MapTileSize	返回的地图磁贴的大小（以像素为单位）。
TilesetID	图块集是一组光栅或矢量数据，按照预设的缩放级别被划分为统一的方形图块网格。每个图块集都有一个在发出请求时要使用的 tilesetId。 Azure Maps提供的现成图块集如下所示。例如，microsoft.base。

ErrorAdditionalInfo

对象

资源管理错误附加信息。

名称	类型	说明
info		其他信息。
type	string	其他信息类型。

ErrorDetail

对象

错误详细信息。

名称	类型	说明
additionalInfo	ErrorAdditionalInfo[]	错误附加信息。
code	string	错误代码。
details	ErrorDetail[]	错误详细信息。
message	string	错误消息。
target	string	错误目标。

ErrorResponse

对象

所有 Azure 资源管理器 API 的通用错误响应，用于返回失败操作的错误细节。（这也遵循 OData 错误响应格式）。

名称	类型	说明
error	ErrorDetail	错误对象。

LocalizedMapView

枚举

View 参数（也称为“用户区域”参数）允许为地缘政治争议区域显示特定国家/地区的正确地图。不同的国家/地区具有此类区域的不同视图，并且 View 参数允许应用程序符合应用程序将提供服务的国家/地区所需的视图。默认情况下，即使尚未在请求中定义该参数，View 参数也会设置为“Unified”。由你负责确定用户的位置，然后为该位置正确设置 View 参数。或者，可以选择设置“View=Auto”，这将基于请求的 IP 地址返回地图数据。 Azure Maps中的视图参数必须遵守相关法律，包括地图、图片及其他数据和您被授权通过Azure Maps访问的第三方内容所在国家/地区的相关法律。示例：view=IN。

有关详细信息，请参阅支持的视图，并查看可用的视图。

值	说明
AE	阿拉伯联合酋长国（阿拉伯视图）
AR	阿根廷（阿根廷视图）
BH	巴林（阿拉伯视图）
IN	印度（印度视图）
IQ	伊拉克（阿拉伯视图）
JO	约旦（阿拉伯视图）
KW	科威特（阿拉伯视图）
LB	黎巴嫩（阿拉伯视图）
MA	摩洛哥（摩洛哥视图）
OM	阿曼（阿拉伯视图）
PK	巴基斯坦（巴基斯坦视图）
PS	巴勒斯坦权力机构（阿拉伯视图）
QA	卡塔尔（阿拉伯视图）
SA	沙特阿拉伯（阿拉伯视图）
SY	叙利亚（阿拉伯视图）
US	美国
YE	也门（阿拉伯视图）
Auto	根据请求的 IP 地址返回映射数据。
Unified	统一视图（其他）

MapTileSize

枚举

返回的地图磁贴的大小（以像素为单位）。

值	说明
256	返回 256 x 256 像素磁贴。
512	返回 512 x 512 像素磁贴。

TilesetID

枚举

图块集是一组光栅或矢量数据，按照预设的缩放级别被划分为统一的方形图块网格。每个图块集都有一个在发出请求时要使用的 tilesetId。 Azure Maps提供的现成图块集如下所示。例如，microsoft.base。

值	说明
microsoft.base	基本地图是一种标准地图，它显示道路、自然特征和人工特征以及矢量图块中这些功能的标签。支持缩放级别 0 到 22。格式：矢量（pbf）。
microsoft.base.labels	在矢量磁贴中显示道路、自然和人工特征的标签。支持缩放级别 0 到 22。格式：矢量（pbf）。
microsoft.base.hybrid	在矢量图块中显示道路、边界和标签数据。支持缩放级别 0 到 22。格式：矢量（pbf）。
microsoft.terra.main	着色浮雕层和地层。支持缩放级别 0 到 6。格式：光栅（png）。
microsoft.base.road	所有具有主样式的层。支持缩放级别 0 到 22。格式：光栅（png）。
microsoft.base.darkgrey	具有深灰色样式的所有层。支持缩放级别 0 到 22。格式：光栅（png）。
microsoft.base.labels.road	在主样式中标记数据。支持缩放级别 0 到 22。格式：光栅（png）。
microsoft.base.labels.darkgrey	标记深灰色样式中的数据。支持缩放级别 0 到 22。格式：光栅（png）。
microsoft.base.hybrid.road	主要样式中的道路、边界和标签数据。支持缩放级别 0 到 22。格式：光栅（png）。
microsoft.base.hybrid.darkgrey	以深灰色样式标记道路、边界和标签数据。支持缩放级别 0 到 22。格式：光栅（png）。
microsoft.imagery	卫星或空中图像的组合。支持缩放级别 1 到 19。格式：光栅（png）。
microsoft.weather.radar.main	天气雷达图块。最新的天气雷达图像，包括雨、雪、冰和混合条件。有关Azure Maps气象服务覆盖的更多信息，请参见Azure Maps天气服务报道。有关雷达数据的更多信息，请参见Azure Maps中的气象服务。支持缩放级别 0 到 15。格式：光栅（png）。
microsoft.weather.infrared.main	天气红外磁贴。最新的红外卫星图像按温度显示云。更多信息请参见Azure Maps气象服务报道。有关卫星数据的更多信息，请参见Azure Maps<>中的气象服务。支持缩放级别 0 到 15。格式：光栅（png）。
microsoft.traffic.absolute	矢量中的绝对流量磁贴
microsoft.traffic.absolute.main	光栅中以主要样式表示的绝对交通磁贴。
microsoft.traffic.relative	矢量中的相对流量磁贴
microsoft.traffic.relative.main	我们主要样式中光栅中的相对交通磁贴。
microsoft.traffic.relative.dark	我们深色样式中光栅中的相对交通磁贴。
microsoft.traffic.delay	矢量中的流量磁贴
microsoft.traffic.delay.main	主样式光栅中的交通磁贴
microsoft.traffic.reduced.main	在主样式中减少光栅中的交通磁贴
microsoft.traffic.incident	矢量中的事件磁贴