Render - Get Map Tile

使用 來要求向量或點陣格式的地圖底圖。
該 Get Map Tiles API 使用戶能夠請求矢量或點陣格式的地圖圖塊,通常用於集成到地圖控件或 SDK 中。 支援的磁磚類型包括 Azure 地圖服務 道路磁磚和即時天氣雷達磁磚。 預設情況下,Azure 地圖服務 Web SDK 使用向量圖塊來渲染其網頁地圖控制。

Important

使用 地圖圖塊 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 參數

名稱 位於 必要 類型 Description
endpoint
path True

string (uri)

Azure 地圖服務 服務的主機名稱。 Azure公有雲用 https://atlas.microsoft.com。 若要鎖定特定Azure 地圖服務地理或主權雲,請參見 Azure 地圖服務 地理範圍。

api-version
query True

string

minLength: 1

用於此作業的 API 版本。

tilesetId
query True

TilesetID

地圖底圖集是點陣或向量資料的集合,分為預設縮放層級的方形地圖底圖統一方格。 每個磚集都有一個 tilesetId,以在提出要求時使用。 Azure 地圖服務提供的現成圖塊集如下。 例如,microsoft.base。

x
query True

integer (int32)

縮放方格上磚的 X 座標。 值必須介於 [0, 2zoom -1] 範圍內。

如需詳細資訊,請參閱 縮放層級和磚網格線。

y
query True

integer (int32)

縮放方格上磚的 Y 座標。 值必須介於 [0, 2zoom -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 地圖服務 中的檢視參數必須遵守適用法律,包括地圖相關法規,適用於你被授權透過 Azure 地圖服務 存取的地圖、影像及其他資料和第三方內容的國家/地區。 範例:view=IN。

如需詳細資訊,請參閱 支援的檢視,並查看可用的檢視。

要求標頭

名稱 必要 類型 Description
x-ms-client-id

string

表示該帳號用於 Microsoft Entra ID 安全模型。 這個Azure 地圖服務帳號的唯一 ID 可以從 Azure 地圖服務 管理平面的 Account API 取得。 欲了解更多在Azure 地圖服務中使用Microsoft Entra ID安全,請參見管理 Azure 地圖服務 認證。

回覆

名稱 類型 Description
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 地圖服務 REST API 的存取。 Azure 角色基礎存取控制用於指定對一個或多個 Azure 地圖服務 資源帳號或子資源的存取權限。 任何使用者、群組或服務主體都可以透過內建角色或由一或多個 Azure 地圖服務 REST API 許可權所組成的自定義角色來授與存取權。

若要實作案例,建議您檢視 驗證概念。 總而言之,此安全性定義會透過能夠針對特定 API 和範圍進行訪問控制的物件,提供模型化應用程式的解決方案。

Note

  • 此安全性定義 需要 使用 x-ms-client-id 標頭來指出應用程式要求存取的 Azure 地圖服務資源。 這可以從 地圖管理 API取得。
  • Authorization URL 專屬於 Azure 公用雲端實例。 主權雲擁有獨特的授權網址和 Microsoft Entra ID 設定。
  • Azure 角色型訪問控制是從 azure 管理平面 設定, 透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API。
  • Azure 地圖服務 Web SDK 的使用,可讓您針對多個使用案例設定應用程式。
  • 如需Microsoft身分識別平臺的詳細資訊,請參閱 Microsoft 身分識別平臺概觀。

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱 Description
https://atlas.microsoft.com/.default

subscription-key

這是當您 在 Azure 入口網站或使用 PowerShell、CLI、Azure SDK 或 REST API 建立 Azure 地圖服務帳戶時所佈建的共用密鑰。

使用此金鑰,任何應用程式都可以存取所有 REST API。 換句話說,此金鑰可用來做為帳戶中核發的主要密鑰。

針對公開的應用程式,我們建議使用 機密用戶端應用程式 方法來存取 Azure 地圖服務 REST API,以便安全地儲存您的密鑰。

類型: apiKey
位於: header

SAS Token

這是透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API,從 azure 地圖服務資源 列表 SAS 作業建立共用存取簽章令牌。

使用此令牌時,任何應用程式都有權使用 Azure 角色型訪問控制進行存取,並更精細地控制特定令牌的到期、速率和區域。 換句話說,SAS 令牌可用來讓應用程式以比共用密鑰更安全的方式控制存取。

對於公開的應用程式,我們建議在 對應帳戶資源上設定允許的來源特定清單, 以限制轉譯濫用,並定期更新 SAS 令牌。

類型: apiKey
位於: header

範例

Successful Tile Request

範例要求

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

範例回覆

Content-Type: application/vnd.mapbox-vector-tile
"binary image string"

定義

名稱 Description
ErrorAdditionalInfo

資源管理錯誤其他資訊。

ErrorDetail

錯誤詳細數據。

ErrorResponse

所有 Azure Resource Manager API 的常見錯誤回應,用於回傳失敗操作的錯誤細節。 (這也遵循 OData 錯誤回應格式。)。

LocalizedMapView

View 參數(也稱為「用戶區域」參數)可讓您針對地緣政治爭議區域顯示特定國家/地區的正確地圖。 不同的國家/地區對這類區域有不同的檢視,而 View 參數可讓應用程式符合您的應用程式將提供服務的國家/地區所需的檢視。 根據預設,即使您尚未在要求中定義 View 參數,仍會設定為 “Unified”。 您必須負責判斷使用者的位置,然後正確設定該位置的 View 參數。 或者,您可以選擇設定 'View=Auto',這會根據要求的IP位址傳回地圖數據。 Azure 地圖服務 中的檢視參數必須遵守適用法律,包括地圖相關法規,適用於你被授權透過 Azure 地圖服務 存取的地圖、影像及其他資料和第三方內容的國家/地區。 範例:view=IN。

如需詳細資訊,請參閱 支援的檢視,並查看可用的檢視。

MapTileSize

傳回地圖底圖的大小,以像素為單位。

TilesetID

地圖底圖集是點陣或向量資料的集合,分為預設縮放層級的方形地圖底圖統一方格。 每個磚集都有一個 tilesetId,以在提出要求時使用。 Azure 地圖服務提供的現成圖塊集如下。 例如,microsoft.base。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱 類型 Description
info

其他資訊。

type

string

其他信息類型。

ErrorDetail

錯誤詳細數據。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤其他資訊。

code

string

錯誤碼。

details

ErrorDetail[]

錯誤詳情

message

string

錯誤訊息。

target

string

錯誤目標。

ErrorResponse

所有 Azure Resource Manager API 的常見錯誤回應,用於回傳失敗操作的錯誤細節。 (這也遵循 OData 錯誤回應格式。)。

名稱 類型 Description
error

ErrorDetail

error 物件。

LocalizedMapView

View 參數(也稱為「用戶區域」參數)可讓您針對地緣政治爭議區域顯示特定國家/地區的正確地圖。 不同的國家/地區對這類區域有不同的檢視,而 View 參數可讓應用程式符合您的應用程式將提供服務的國家/地區所需的檢視。 根據預設,即使您尚未在要求中定義 View 參數,仍會設定為 “Unified”。 您必須負責判斷使用者的位置,然後正確設定該位置的 View 參數。 或者,您可以選擇設定 'View=Auto',這會根據要求的IP位址傳回地圖數據。 Azure 地圖服務 中的檢視參數必須遵守適用法律,包括地圖相關法規,適用於你被授權透過 Azure 地圖服務 存取的地圖、影像及其他資料和第三方內容的國家/地區。 範例:view=IN。

如需詳細資訊,請參閱 支援的檢視,並查看可用的檢視。

值 Description
AE

阿拉伯聯合大公國 (阿拉伯文檢視)

AR

阿根廷 (阿根廷文檢視)

BH

巴林 (阿拉伯文檢視)

IN

印度 (印度文檢視)

IQ

伊拉克 (阿拉伯文檢視)

JO

約旦 (阿拉伯文檢視)

KW

科威特 (阿拉伯文檢視)

LB

黎巴嫩 (阿拉伯文檢視)

MA

摩洛哥 (摩洛哥文檢視)

OM

阿曼 (阿拉伯文檢視)

PK

巴基斯坦 (巴基斯坦文檢視)

PS

巴勒斯坦民族權力機構 (阿拉伯文檢視)

QA

卡達 (阿拉伯文檢視)

SA

沙烏地阿拉伯 (阿拉伯文檢視)

SY

敘利亞 (阿拉伯文檢視)

US

美國

YE

葉門 (阿拉伯文檢視)

Auto

根據要求的IP位址傳回地圖數據。

Unified

整合檢視 (其他)

MapTileSize

傳回地圖底圖的大小,以像素為單位。

值 Description
256

傳回 256 x 256 像素磚。

512

傳回 512 x 512 像素磚。

TilesetID

地圖底圖集是點陣或向量資料的集合,分為預設縮放層級的方形地圖底圖統一方格。 每個磚集都有一個 tilesetId,以在提出要求時使用。 Azure 地圖服務提供的現成圖塊集如下。 例如,microsoft.base。

值 Description
microsoft.base

基本地圖是標準地圖,可顯示道路、自然和人工特徵,以及向量圖格中這些功能的標籤。

支援縮放層級 0 到 22。 格式:向量(pbf)。

microsoft.base.labels

在向量磚中顯示道路、自然和人工特徵的標籤。

支援縮放層級 0 到 22。 格式:向量(pbf)。

microsoft.base.hybrid

在向量磚中顯示道路、界限和標籤數據。

支援縮放層級 0 到 22。 格式:向量(pbf)。

microsoft.terra.main

陰影浮雕和 terra 層次。

支援縮放層級 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 地圖服務氣象服務報導資訊,請參閱 Azure 地圖服務 天氣服務報導。 欲了解更多雷達資料資訊,請參閱Azure 地圖服務<>中的氣象服務。

支援縮放層級 0 到 15。 格式:點陣(png)。

microsoft.weather.infrared.main

天氣紅外磚。 最新的紅外衛星圖像會依其溫度顯示雲層。 欲了解更多資訊,請參閱Azure 地圖服務氣象服務報導。 欲了解更多衛星資料資訊,請參閱氣象服務Azure 地圖服務。

支援縮放層級 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

向量中的事件磚