Render - Get Map Static Image

服務:: Maps

API 版本:: 2024-04-01

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

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

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

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

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

|：----------|：----------------|：----------------|：----------------|：-------------| |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

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

路徑參數自 S1 起在 Azure 地圖服務帳號 SKU 中被支援。 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
發	填滿 Alpha （不透明度）	float	0 到 1
lw	線條寬度	int32	(0, 50]
ra	圓半徑（公尺）	float	大於 0

pins

query

string[]

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

Azure 地圖服務帳號 S0 SKU 只支援單一的 pins 參數實例，且每個 pin 位置數量限制為 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
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"

名稱

類型

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 地圖服務資源帳號或子資源的存取權限。任何使用者、群組或服務主體皆可透過內建角色或由一個或多個 REST API 權限組成的自訂角色獲得存取權限，Azure 地圖服務\n\n實作情境時，建議檢視 authentication concepts。總結來說，此安全定義提供了透過能對特定 API 與範圍進行存取控制的物件來建模應用程式的解決方案。\n\n#### 註解\n* 此安全定義要求使用 x-ms-client-id標頭來指示應用程式請求存取的Azure 地圖服務資源。此功能可從 Maps 管理 API 取得。\n* \nAuthorization URL 是針對Azure公有雲實例的專用。主權雲擁有獨特的授權網址和 Microsoft Entra ID 設定。 \n* \nAzure 基於角色的存取控制由 Azure 管理層透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API 配置。\n* \nAzure 地圖服務Web SDK 允許基於配置的應用程式設定，適用於多種使用情境。\n* 欲了解更多Microsoft 身分識別平台資訊，請參見 Microsoft 身分識別平台 overview。

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

範圍

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

subscription-key

這是一個共享金鑰，當你在Azure入口網站建立Azure 地圖服務帳號，或使用 PowerShell、CLI、Azure SDK 或 REST API 時，會被配置。\n\n 有了這個金鑰，任何應用程式都能存取所有 REST API。換句話說，這個金鑰可以作為發行帳戶的主金鑰使用。\n\n 對於公開的應用程式，我們建議使用機密客戶端應用程式方法來存取Azure 地圖服務 REST API，以便您的金鑰能安全儲存。

類型: apiKey
位於: header

SAS Token

這是一個共享存取簽章憑證，透過 List SAS 操作在 Azure 地圖服務資源，經由 Azure 管理層面，透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API 建立。\n\n 使用此憑證，任何應用程式都被授權使用 Azure 存取基於角色的存取控制，以及對特定代幣的到期日、速率及使用區域的細緻控制。換句話說，SAS 令牌可以用來讓應用程式以比共享金鑰更安全的方式控制存取。\n\n 對於公開暴露的應用程式，我們建議在 Map 帳號資源上設定特定的允許來源清單，以減少渲染濫用，並定期更新 SAS 令牌。

類型: apiKey
位於: header

範例

Successful Static Image Request

範例要求

HTTP

GET {endpoint}/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

列舉型別

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

值	Description
AE	阿拉伯聯合大公國 (阿拉伯文檢視)
AR	阿根廷 (阿根廷文檢視)
BH	巴林 (阿拉伯文檢視)
IN	印度 (印度文檢視)
IQ	伊拉克 (阿拉伯文檢視)
JO	約旦 (阿拉伯文檢視)
KW	科威特 (阿拉伯文檢視)
LB	黎巴嫩 (阿拉伯文檢視)
MA	摩洛哥 (摩洛哥文檢視)
OM	阿曼 (阿拉伯文檢視)
PK	巴基斯坦 (巴基斯坦文檢視)
PS	巴勒斯坦民族權力機構 (阿拉伯文檢視)
QA	卡達 (阿拉伯文檢視)
SA	沙烏地阿拉伯 (阿拉伯文檢視)
SY	敘利亞 (阿拉伯文檢視)
US	美國 of America
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	默認值，無流量覆蓋。