Render - Get Map Static Image

服務:
Maps
API 版本:
2024-04-01

此轉譯 API 會產生使用者定義區域的靜態點陣化地圖檢視。 它適用於輕量型 Web 應用程式、所需的用戶體驗不需要互動式地圖控件，或頻寬有限時。 此 API 也適用於將地圖內嵌在瀏覽器外部的應用程式、後端服務、報表產生或桌面應用程式中。

此 API 包含基本資料視覺效果的參數：

  • 標示為多個樣式的圖釘。
  • 轉譯圓形、路徑和多邊形幾何類型。

如需詳細資訊和詳細範例，請參閱 轉譯點陣地圖上的自定義資料。

bbox 參數的維度會根據縮放層級而受到限制。 這可確保產生的影像具有適當的詳細數據層級。

縮放等級 明隆山脈 最大 Lon 範圍 最小緯度範圍 最大 Lat 範圍
0 56.25 360.0 30.1105585173 180.0
1 28.125 360.0 14.87468995 180.0
2 14.063 351.5625 7.4130741851 137.9576312246
3 7.03125 175.78125 3.7034501005 73.6354071932
4 3.515625 87.890625 1.8513375155 35.4776115315
5 1.7578125 43.9453125 0.925620264 17.4589959239
6 0.87890625 21.97265625 0.4628040687 8.6907788223
7 0.439453125 10.986328125 0.2314012764 4.3404320789
8 0.2197265625 5.4931640625 0.1157005434 2.1695927024
9 0.1098632812 2.7465820312 0.0578502599 1.0847183194
10 0.0549316406 1.3732910156 0.0289251285 0.5423494021
11 0.0274658203 0.6866455078 0.014462564 0.2711734813
12 0.0137329102 0.3433227539 0.007231282 0.1355865882
13 0.0068664551 0.171661377 0.003615641 0.067793275
14 0.0034332275 0.0858306885 0.0018078205 0.0338966351
15 0.0017166138 0.0429153442 0.0009039102 0.0169483173
16 0.0008583069 0.0214576721 0.0004519551 0.0084741586
17 0.0004291534 0.0107288361 0.0002259776 0.0042370793
18 0.0002145767 0.005364418 0.0001129888 0.0021185396
19 0.0001072884 0.002682209 5.64944E-05 0.0010592698
20 5.36442E-05 0.0013411045 2.82472E-05 0.0005296349

附注：必須將 中心 或 bbox 參數提供給 API。

GET {endpoint}/map/static?api-version=2024-04-01
含選擇性參數: 
GET {endpoint}/map/static?api-version=2024-04-01&tilesetId={tilesetId}&trafficLayer={trafficLayer}&zoom={zoom}&center={center}&bbox={bbox}&height={height}&width={width}&language={language}&view={view}&pins={pins}&path={path}

URI 參數

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

string (uri)

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

string

minLength: 1

用於此作業的 API 版本。
bbox
 query

number[]

周框方塊是由兩個緯度和兩個經度所定義，代表地球上矩形區域的四側。 格式：'minLon、minLat、maxLon、maxLat' （雙精度浮點數）。

注意：bbox 或 center 都是必要參數。 它們是互斥的。 bbox 不應該與高度或寬度搭配使用。

Lat 和 Lon 的最大和最小允許範圍會針對此頁面頂端表格中的每個縮放層級定義。
center
 query

number[]

雙精度浮點中心點的座標。 格式：'lon，lat'。 經度範圍：-180 到 180。 緯度範圍：-90 至 90。

注意：中心或 bbox 都是必要參數。 它們是互斥的。
height
 query

integer (int32)

minimum: 80
maximum: 1500

產生的影像高度，以像素為單位。 範圍從80到1500。 預設為 512。 它不應該與 bbox 搭配使用。
language
 query

string

應該傳回搜尋結果的語言。 應該是其中一個支援的 IETF 語言標記，不區分大小寫。 當特定欄位無法使用指定語言的數據時，會使用預設語言。

如需詳細資訊，請參閱 支援的語言。
path
 query

string[]

路徑樣式和位置（雙精度浮點數）。 使用此參數選擇性地將線條、多邊形或圓形新增至影像。 路徑樣式描述線條和填滿的外觀。 （請務必正確使用此參數的 URL 編碼值，因為它會包含管道和標點符號等保留字元。

你可以指定多個路徑參數實例，以渲染不同風格的多重幾何體。 每個請求最多支援 10 個路徑參數及最多 100 個位置。

若要使用默認樣式來轉譯半徑為 100 公尺且中心點為緯度 45°N 和經度 122°W 的圓圈，請新增 querystring 參數

path=ra100||-122 45

請注意，經度是在緯度之前。 URL 編碼之後，看起來會像這樣

path=ra100%7C%7C-122+45

此處的所有範例都會顯示不含 URL 編碼的路徑參數，以清楚明瞭。

若要轉譯一行，請使用管道字元分隔每個位置。 例如，使用

path=||-122 45|-119.5 43.2|-121.67 47.12

多邊形是以封閉路徑指定，其中第一個和最後一個點相等。 例如，使用

path=||-122 45|-119.5 43.2|-121.67 47.12|-122 45

線條和多邊形位置的經度值可以介於從 -360 到 360 的範圍內，以允許轉譯跨越反經線的幾何。

樣式修飾詞

您可以藉由新增樣式修飾詞來修改路徑的外觀。 這些會在位置之前新增。 樣式修飾詞各有兩個字母的名稱。 這些縮寫名稱可用來協助減少 URL 的長度。

若要變更外框的色彩，請使用 『lc』 樣式修飾詞，並使用 HTML/CSS RGB 色彩格式指定色彩，這是六位數十六進位數位（不支援三位數表單）。 例如，若要使用深粉紅色色彩，您會在 CSS 中指定為 #FF1493，請使用

path=lcFF1493||-122 45|-119.5 43.2

可以結合多個樣式修飾詞來建立更複雜的視覺樣式。

lc0000FF|lw3|la0.60|fa0.50||-122.2 47.6|-122.2 47.7|-122.3 47.7|-122.3 47.6|-122.2 47.6

樣式修飾詞摘要

修飾語 說明 類型 範圍
立法會 線條色彩 字串 000000 到FFFFFFFF
fc 填滿色彩 字串 000000 到FFFFFFFF
la 線條 Alpha （不透明度） float 0 到 1
發 填滿 Alpha （不透明度） float 0 到 1
lw 線條寬度 int32 (0, 50]
ra 圓半徑（公尺） float 大於 0
pins
 query

string[]

圖釘樣式和實例。 使用此參數選擇性地圖釘新增至映像。 圖釘樣式描述圖釘的外觀，而實例會指定圖釘的座標（雙精度浮點數），以及每個圖釘的選擇性標籤。 （請務必正確使用此參數的 URL 編碼值，因為它會包含管道和標點符號等保留字元。

你可以指定最多 25 個 pins 參數實例，以使用多種 pin 樣式。 每個實例最多支援 50 個地點。

若要使用預設的內建圖釘樣式，在緯度 45°N 和經度 122°W 轉譯圖釘，請新增 querystring 參數

pins=default||-122 45

請注意，經度是在緯度之前。 URL 編碼之後，看起來會像這樣

pins=default%7C%7C-122+45

此處的所有範例都會顯示沒有 URL 編碼的 pins 參數，以清楚明瞭。

若要在多個位置轉譯針腳，請使用管道字元分隔每個位置。 例如，使用

pins=default||-122 45|-119.5 43.2|-121.67 47.12

樣式修飾詞

您可以藉由新增樣式修飾詞來修改釘選的外觀。 這些會在樣式之後新增，但在位置和標籤之前。 樣式修飾詞各有兩個字母的名稱。 這些縮寫名稱可用來協助減少 URL 的長度。

若要變更圖釘的色彩，請使用 『co』 樣式修飾詞，並使用 HTML/CSS RGB 色彩格式指定色彩，這是六位數十六進位數位（不支援三位數表單）。 例如，若要使用深粉紅色色彩，您會在 CSS 中指定為 #FF1493，請使用

pins=default|coFF1493||-122 45

圖釘卷標

若要將標籤新增至釘選，請將標籤放在座標正前的單引號中。 避免在標籤中使用特殊字元，例如 | 或 ||。 例如，若要使用值 '1'、'2' 和 '3' 來標記三個針腳，請使用

pins=default||'1'-122 45|'2'-119.5 43.2|'3'-121.67 47.12

內建圖釘樣式稱為「無」，不會顯示圖釘影像。 如果您想要顯示標籤，而不顯示任何釘選影像，可以使用此功能。 例如，

pins=none||'A'-122 45|'B'-119.5 43.2

若要變更圖釘卷標的色彩，請使用 『lc』 卷標色彩樣式修飾詞。 例如，若要搭配黑色標籤使用粉紅色圖釘，請使用

pins=default|coFF1493|lc000000||-122 45

若要變更標籤的大小，請使用 'ls' 標籤大小樣式修飾詞。 標籤大小代表標籤文字的近似高度，以像素為單位。 例如，若要將標籤大小增加為12，請使用

pins=default|ls12||'A'-122 45|'B'-119 43

卷標會置中於圖釘 「標籤點」。 錨點位置已針對內建圖釘預先定義，且位於自定義圖釘的頂端中心（請參閱下方）。 若要覆寫標籤點，請使用 『la』 樣式修飾詞，並提供錨點的 X 和 Y 圖元座標。 這些座標相對於圖釘影像的左上角。 正 X 值會將錨點向右移動，而正 Y 值會將錨點向下移動。 例如，若要將標籤錨定在圖釘影像左上角上方 10 像素和 4 圖元的位置，請使用

pins=default|la10 -4||'A'-122 45|'B'-119 43

自訂圖釘

若要使用自定義圖釘影像，請使用 『custom』 這個字作為釘選樣式名稱，然後在位置和標籤資訊後面指定 URL。 自定義標籤影像允許的大小上限為65,536圖元。 使用兩個管道字元來指出您已完成指定位置並啟動URL。 例如，

pins=custom||-122 45||http://contoso.com/pushpins/red.png

URL 編碼之後，看起來會像這樣

pins=custom%7C%7C-122+45%7C%7Chttp%3A%2F%2Fcontoso.com%2Fpushpins%2Fred.png

根據預設，自定義圖釘影像會以釘選座標為中心繪製。 這通常不理想，因為它遮蔽了您嘗試反白顯示的位置。 若要覆寫釘選影像的錨點位置，請使用 『an』 樣式修飾詞。 這會使用與 『la』 標籤式修飾詞相同的格式。 例如，如果您的自定義釘選影像在影像左上角有釘選的提示，您可以使用 將錨點設定為該位置

pins=custom|an0 0||-122 45||http://contoso.com/pushpins/red.png

注意：如果您使用自定義圖釘影像的 'co' 色彩修飾詞，指定的色彩將會取代影像中像素的 RGB 色板，但會讓 Alpha （不透明度） 通道保持不變。 這通常只會使用純色自定義影像來完成。

縮放、旋轉和不透明度

您可以使用 'sc' 縮放樣式修飾詞，讓圖釘及其標籤變大或更小。 這是大於零的值。 值為 1 是標準小數位數。 大於 1 的值會讓針腳變大，而小於 1 的值會使其變小。 例如，若要繪製圖釘 50% 大於一般，請使用

pins=default|sc1.5||-122 45

您可以使用 『ro』 旋轉樣式修飾詞來旋轉圖釘及其標籤。 這是順時針旋轉的數度。 使用負數來逆時針旋轉。 例如，若要順時針旋轉圖釘 90 度，並加倍其大小，請使用

pins=default|ro90|sc2||-122 45

您可以指定 『al』 Alpha 樣式修飾詞，讓圖釘及其標籤部分透明。 這是介於 0 到 1 之間的數位，表示圖釘的不透明度。 零會讓它們完全透明（且不可見），1 則讓它們完全不透明（這是預設值）。 例如，若要將圖釘及其標籤設為 67% 不透明，請使用

pins=default|al.67||-122 45

樣式修飾詞摘要

修飾語 說明 類型 範圍
鋁 Alpha （不透明度） float 0 到 1
an 釘選錨點 <int32、 int32> *
co 別針顏色 字串 000000 到FFFFFFFF
la 標籤點 <int32、 int32> *
立法會 標籤色彩 字串 000000 到FFFFFFFF
ls 標籤大小 float 大於 0
ro 輪替 float -360 到 360
sc Scale float 大於 0
  • X 和 Y 座標可以是釘選影像內的任何位置或其周圍的邊界。 邊界大小是針腳寬度和高度的最小值。
tilesetId
 query

Tileset

要傳回的地圖樣式。 可能的值為 microsoft.base.road、microsoft.base.darkgrey 和 microsoft.imagery。 默認值設定為 microsoft.base.road。 如需詳細資訊，請參閱 Render TilesetId。
trafficLayer
 query

TrafficTilesetId

選擇性值，表示影像結果上未覆寫任何流量流量。 可能的值為 microsoft.traffic.relative.main 和 none。 默認值為 none，表示未傳回流量。 如果提供與流量相關的 tilesetId，將會傳回具有對應流量圖層的地圖影像。 如需詳細資訊，請參閱 Render TilesetId。
view
 query

LocalizedMapView

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

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

integer (int32)

minimum: 80
maximum: 2000

產生的影像寬度以像素為單位。 範圍從80到2000。 預設為 512。 它不應該與 bbox 搭配使用。
zoom
 query

integer (int32)

maximum: 20

地圖的所需縮放層級。 針對 tilesetId 為 microsoft.base.road 或 microsoft.base.darkgrey，支援從 0 到 20 的縮放值範圍。 支援 tilesetId 為 microsoft.imagery 的縮放值範圍從 0-19 不等。 預設值為 12。

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

要求標頭

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

string

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

MediaType

接受「標頭欄位可用於指定有關回應介質類型的首選項。 允許的媒體類型包括 image/jpeg 和 image/png。 如果未指定 Accept 標頭，則返回 image/png 格式的圖像。

回覆

名稱 類型 Description
200 OK

file

要求已成功。

Media Types: "image/png", "image/jpeg", "application/json"
Other Status Codes

ErrorResponse

未預期的錯誤回應。

Media Types: "image/png", "image/jpeg", "application/json"

安全性

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 Static Image Request

範例要求

GET https://atlas.microsoft.com/map/static?api-version=2024-04-01&tilesetId=microsoft.base.road&zoom=10&center=-122.177621,47.613079

範例回覆

狀態碼:
200 
Content-Type: image/png
"{file}"

定義

名稱 Description
ErrorAdditionalInfo

資源管理錯誤其他資訊。
ErrorDetail

錯誤詳細數據。
ErrorResponse

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

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

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

回應的媒介類型。
Tileset

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

值表示影像結果上無流量覆蓋。

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

名稱 類型 Description
info

其他資訊。
type

string

其他信息類型。

ErrorDetail

Object

錯誤詳細數據。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤其他資訊。
code

string

錯誤碼。
details

ErrorDetail[]

錯誤詳情
message

string

錯誤訊息。
target

string

錯誤目標。

ErrorResponse

Object

所有 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

整合檢視 (其他)

MediaType

列舉型別

回應的媒介類型。

值 Description
image/png

以 png 格式返回影像。
image/jpeg

以 jpeg 格式返回影像。

Tileset

列舉型別

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

值 Description
microsoft.base.road

microsoft.base.road
microsoft.base.darkgrey

microsoft.base.darkgrey
microsoft.imagery

微軟.imagery

TrafficTilesetId

列舉型別

值表示影像結果上無流量覆蓋。

值 Description
microsoft.traffic.relative.main

支援與流量相關的 tilesetId。
none

默認值，無流量覆蓋。