Render - Get Map Static Image

參考

服務:: Maps

API 版本:: 2024-04-01

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

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

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

如需詳細資訊和詳細範例，請參閱在點陣地圖上呈現自定義數據。

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

縮放比例	最小 Lon 範圍	最大 Lon 範圍	Min Lat Range	最大 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

注意： center 或 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[]

周框方塊是由兩個緯度和兩個經度所定義，代表地球矩形區域的四邊。格式：double) 中的 'minLon、minLat、maxLon、maxLat' (。

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

Lat 和 Lon 允許的範圍上限和最小值會針對此頁面頂端數據表中的每個縮放層級定義。

center

query

number[]

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

注意：置中或 bbox 都是必要參數。它們互斥。

height

query

integer

int32

產生的影像高度，以像素為單位。範圍從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
fc	填滿色彩	字串	000000 到FFFFFFFF
la	行Alpha (不透明度)	float	0 到 1
fa	填滿Alpha (不透明度)	float	0 到 1
lw	線條寬度	int32	(0， 50]
ra	圓形半徑 (公尺)	float	大於 0

pins

query

string[]

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

Azure 地圖服務帳戶 S0 SKU 僅支援釘選參數的單一實例。其他 SKU 允許多個針腳參數實例指定多個針腳樣式。

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

pins=default||-122 45

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

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

此處的所有範例都會顯示沒有 URL 編碼的 pin 參數，以便清楚起見。

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

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

樣式修飾詞摘要

修飾詞	描述	類型	範圍
al	Alpha (不透明度)	float	0 到 1
an	釘選錨點	<int32、int32>	*
co	釘選色彩	字串	000000 到FFFFFFFF
la	標籤點	<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。如需詳細資訊，請參閱轉譯 TilesetId。

trafficLayer

query

TrafficTilesetId

選擇性值，表示影像結果上沒有重疊的流量流量。可能的值為 microsoft.traffic.relative.main 和 none。默認值為 none，表示未傳回流量。如果提供與流量相關的 tilesetId，將會傳回對應交通圖層的地圖影像。如需詳細資訊，請參閱轉譯 TilesetId。

view

query

LocalizedMapView

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

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

width

query

integer

int32

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

zoom

query

integer

int32

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

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

要求標頭

名稱	必要	類型	Description
x-ms-client-id		string	指定哪一個帳戶用於搭配 Microsoft Entra ID 安全性模型使用。它代表 Azure 地圖服務帳戶的唯一標識碼，而且可以從 Azure 地圖服務管理平面帳戶 API 擷取。若要在 Azure 地圖服務中使用 Microsoft 專案標識碼安全性，請參閱下列文章以取得指引。
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 Flow 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。如需詳細資訊，請參閱轉譯 TilesetId。
TrafficTilesetId	選擇性值，表示影像結果上沒有重疊的流量。可能的值為 microsoft.traffic.relative.main 和 none。默認值為 none，表示未傳回任何流量。如果提供與流量相關的 tilesetId，將會傳回對應流量圖層的地圖影像。如需詳細資訊，請參閱轉譯 TilesetId。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

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

ErrorDetail

錯誤詳細數據。

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

ErrorResponse

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

LocalizedMapView

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

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

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

MediaType

[接受] 標頭欄位可用來指定回應媒體類型的喜好設定。允許的媒體類型包括 image/jpeg 和 image/png。如果未指定 Accept 標頭，則傳回 image/png 中的影像。

名稱	類型	Description
image/jpeg	string	以 jpeg 格式傳回影像。
image/png	string	以 png 格式傳回影像。

TilesetId

要傳回的對應樣式。可能的值為 microsoft.base.road、microsoft.base.darkgrey 和 microsoft.imagery。默認值設定為 microsoft.base.road。如需詳細資訊，請參閱轉譯 TilesetId。

名稱	類型	Description
microsoft.base.darkgrey	string	TilesetId 包含具有深灰色樣式的所有圖層。
microsoft.base.road	string	TilesetId 包含轉譯主要樣式的所有圖層。
microsoft.imagery	string	TilesetId 包含衛星和空照影像的組合。

TrafficTilesetId

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

名稱	類型	Description
microsoft.traffic.relative.main	string	支援的流量相關 tilesetId。
none	string	默認值，沒有流量重疊。

共用方式為

Render - Get Map Static Image

URI 參數

樣式修飾詞

樣式修飾詞摘要

樣式修飾詞

圖釘卷標

自訂圖釘

縮放、旋轉和不透明度

樣式修飾詞摘要

要求標頭

回應

安全性

AADToken

備註

範圍

subscription-key

SAS Token

範例

Successful Static Image Request

範例要求

範例回覆

定義

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

LocalizedMapView

MediaType

TilesetId

TrafficTilesetId

其他資源