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 https://atlas.microsoft.com/map/static?api-version=2024-04-01

含選擇性參數:

GET https://atlas.microsoft.com/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

api-version

query

True

string

Azure 地圖服務 API 的版本號碼。當前版本為2024-04-01。

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 編碼值，因為它會包含管道和標點符號等保留字元。

從 S1 開始，Azure 地圖服務帳戶 SKU 支援 Path 參數。 path 參數的多個實例允許使用其樣式指定多個幾何。每個要求的參數數目限制為 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
足球俱樂部	填滿色彩	字串	000000 到FFFFFFFF
洛杉磯	線條 Alpha （不透明度）	float	0 到 1
發	填滿 Alpha （不透明度）	float	0 到 1
lw	線條寬度	int32	(0, 50]
ra	圓半徑（公尺）	float	大於 0

pins

query

string[]

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

Azure 地圖服務帳戶 S0 SKU 僅支援針腳參數的單一實例，而且每個針腳的位置數目限制為 5 個。其他 SKU 最多允許 25 個針腳參數實例指定多個針腳樣式，而且每個針腳的位置數目限制為 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

S0 Azure 地圖服務帳戶 SKU 只允許五個圖釘。其他帳戶 SKU 沒有這項限制。

樣式修飾詞

您可以藉由新增樣式修飾詞來修改釘選的外觀。這些會在樣式之後新增，但在位置和標籤之前。樣式修飾詞各有兩個字母的名稱。這些縮寫名稱可用來協助減少 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
一	釘選錨點	<int32、 int32>	*
co	釘選色彩	字串	000000 到FFFFFFFF
洛杉磯	標籤點	<int32、 int32>	*
立法會	標籤色彩	字串	000000 到FFFFFFFF
ls	標籤大小	float	大於 0
ro	輪替	float	-360 到 360
sc	規模	float	大於 0

X 和 Y 座標可以是釘選影像內的任何位置或其周圍的邊界。邊界大小是針腳寬度和高度的最小值。

tilesetId

query

TilesetId

要傳回的地圖樣式。可能的值為 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 地圖服務中的 View 參數必須符合相關法律，包括地圖、地圖、影像和其他數據，以及您有權透過 Azure 地圖服務存取的第三方內容的國家/地區。範例：view=IN。

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

width

query

integer (int32)

minimum: 80
maximum: 2000

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

zoom

query

integer (int32)

minimum: 0
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 地圖服務管理平面帳戶 API 取得 Azure 地圖服務帳戶的唯一識別碼。如需在 Azure 地圖服務中使用 Microsoft Entra ID 安全性的詳細資訊，請參閱在 Azure 地圖服務中管理驗證。
Accept		MediaType	接受「標頭欄位可用於指定有關回應介質類型的首選項。允許的媒體類型包括 image/jpeg 和 image/png。如果未指定 Accept 標頭，則返回 image/png 格式的圖像。

回應

名稱	類型	Description
200 OK	object	此圖像是從成功的獲取映射靜態圖像調用返回的。 Media Types: "image/jpeg", "image/png" 標題 Content-Type: string
Other Status Codes	ErrorResponse	發生未預期的錯誤。 Media Types: "image/jpeg", "image/png"

名稱

類型

Description

200 OK

object

此圖像是從成功的獲取映射靜態圖像調用返回的。

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

標題

Content-Type: string

Other Status Codes

ErrorResponse

發生未預期的錯誤。

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

安全性

AADToken

這些是 Entra OAuth 2.0 流程 Microsoft。與 Azure 角色型存取配對時，控制它可用來控制 Azure 地圖服務 REST API 的存取。 Azure 角色型訪問控制可用來指定一或多個 Azure 地圖服務資源帳戶或子資源的存取權。任何使用者、群組或服務主體都可以透過內建角色或由一或多個 Azure 地圖服務 REST API 許可權所組成的自定義角色來授與存取權。

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

註釋

此安全性定義需要使用 x-ms-client-id 標頭來指出應用程式要求存取的 Azure 地圖服務資源。這可以從地圖管理 API取得。

Authorization URL 專屬於 Azure 公用雲端實例。主權雲端具有唯一的授權 URL，Microsoft Entra ID 設定。 * 透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 Azure 管理平面設定 Azure 角色型存取控制。 * Azure 地圖服務 Web SDK 的使用方式允許針對多個使用案例設定應用程式。

如需Microsoft身分識別平臺的詳細資訊，請參閱 Microsoft 身分識別平臺概觀。

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

範圍

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

subscription-key

這是透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，透過 Azure 管理平面建立 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

範例要求

HTTP

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	錯誤回應
LocalizedMapView	View 參數（也稱為「用戶區域」參數）可讓您針對地緣政治爭議區域顯示特定國家/地區的正確地圖。不同的國家/地區對這類區域有不同的檢視，而 View 參數可讓應用程式符合您的應用程式將提供服務的國家/地區所需的檢視。根據預設，即使您尚未在要求中定義 View 參數，仍會設定為 “Unified”。您必須負責判斷使用者的位置，然後正確設定該位置的 View 參數。或者，您可以選擇設定 'View=Auto'，這會根據要求的IP位址傳回地圖數據。 Azure 地圖服務中的 View 參數必須符合相關法律，包括地圖、地圖、影像和其他數據，以及您有權透過 Azure 地圖服務存取的第三方內容的國家/地區。範例：view=IN。如需詳細資訊，請參閱支援的檢視，並查看可用的檢視。
MediaType	接受「標頭欄位可用於指定有關回應介質類型的首選項。允許的媒體類型包括 image/jpeg 和 image/png。如果未指定 Accept 標頭，則返回 image/png 格式的圖像。
TilesetId	要傳回的地圖樣式。可能的值為 microsoft.base.road、microsoft.base.darkgrey 和 microsoft.imagery。默認值設定為 microsoft.base.road。如需詳細資訊，請參閱 Render TilesetId。
TrafficTilesetId	選擇性值，表示影像結果上未覆寫任何流量流量。可能的值為 microsoft.traffic.relative.main 和 none。默認值為 none，表示未傳回流量。如果提供與流量相關的 tilesetId，將會傳回具有對應流量圖層的地圖影像。如需詳細資訊，請參閱 Render TilesetId。

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

名稱	類型	Description
info	object	其他資訊。
type	string	其他信息類型。

ErrorDetail

Object

錯誤詳細數據。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳細數據。
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

Object

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

LocalizedMapView

列舉型別

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

值	Description
AE	阿拉伯聯合大公國 (阿拉伯文檢視)
AR	阿根廷 (阿根廷文檢視)
BH	巴林 (阿拉伯文檢視)
IN	印度 (印度文檢視)
IQ	伊拉克 (阿拉伯文檢視)
JO	約旦 (阿拉伯文檢視)
KW	科威特 (阿拉伯文檢視)
LB	黎巴嫩 (阿拉伯文檢視)
MA	摩洛哥 (摩洛哥文檢視)
OM	阿曼 (阿拉伯文檢視)
PK	巴基斯坦 (巴基斯坦文檢視)
PS	巴勒斯坦民族權力機構 (阿拉伯文檢視)
QA	卡達 (阿拉伯文檢視)
SA	沙烏地阿拉伯 (阿拉伯文檢視)
SY	敘利亞 (阿拉伯文檢視)
US	美利堅合眾國
YE	葉門 (阿拉伯文檢視)
Auto	根據要求的IP位址傳回地圖數據。
Unified	整合檢視 (其他)

MediaType

列舉型別

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

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

TilesetId

列舉型別

值	Description
microsoft.base.road	TilesetId 包含具有渲染主樣式的所有圖層。
microsoft.base.darkgrey	TilesetId 包含所有具有深灰色樣式的圖層。
microsoft.imagery	TilesetId 包含衛星和航空圖像的組合。

TrafficTilesetId

列舉型別

值	Description
microsoft.traffic.relative.main	支援與流量相關的 tilesetId。
none	默認值，無流量覆蓋。

共用方式為

Render - Get Map Static Image

URI 參數

樣式修飾詞

樣式修飾詞摘要

樣式修飾詞

圖釘卷標

自訂圖釘

縮放、旋轉和不透明度

樣式修飾詞摘要

要求標頭

回應

安全性

AADToken

註釋

範圍

subscription-key

SAS Token

範例

Successful Static Image Request

範例要求

範例回覆

定義

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

LocalizedMapView

MediaType

TilesetId

TrafficTilesetId