Azure 地圖服務（Preview）

Azure 地圖服務提供用於地圖繪製、路由、地理編碼及反向地理編碼的地理空間 API。

此連接器適用於以下產品和區域：

服務	Class	Regions
Copilot Studio	標準	除以下部分外，所有Power Automate區域： - 由 21Vianet 營運的中國雲
邏輯應用程式	標準	所有 Logic Apps 區域，但下列區域除外： - Azure中國地區 - 美國國防部（DoD）
Power Apps	標準	除以下部分外，所有Power Apps區域 - 由 21Vianet 營運的中國雲
Power Automate（自動化服務）	標準	除以下部分外，所有Power Automate區域： - 由 21Vianet 營運的中國雲

聯絡方式
名稱	Microsoft
URL	https://www.microsoft.com/

連接器中繼資料
發行者	Microsoft
網站	https://azure.microsoft.com/products/azure-maps
隱私策略	https://privacy.microsoft.com/privacystatement
類別	資料;生產力

Azure 地圖服務 Connector

類型： 無碼 | 等級： 標準 | 狀況： 預覽

透過 Azure 地圖服務 REST API 提供地圖、路由、地理編碼及反向地理編碼功能。請求完全由 APIM 政策處理——沒有連接器網頁應用程式。

Authentication

API 金鑰驗證。連線需要 Azure 地圖服務訂閱金鑰。

參數	類型	Required	Description
`subscription_key`	安全字串	是的	Azure 地圖服務訂用帳戶金鑰

金鑰從連線令牌中擷取，並由政策CheckForToken / GetAuthHeaderValue（）作為查詢參數傳遞給 Azure 地圖服務。subscription-key

雲端可用性

雲	Available
公開	是的
費爾法克斯（GCC）	是的
GCC High	是的
DoD	是的

行動

取得路線 — `GetRoute`

計算兩個航點之間的駕駛或步行路線。航點必須是座標對（latitude,longitude）。不支援地址——先用「 按地址取得位置」來地理編碼。

端點（政策之後）：POST https://atlas.microsoft.com/route/directions?api-version=2025-01-01

該政策會將 GET 風格的查詢參數轉換成 GeoJSON FeatureCollection POST 主體，將座標翻轉為longitude,latitude排序，並將避免/優化值映射成 Azure 地圖服務的對應值。

參數	Required	類型	Description
航點1（`wp.0`）	是的	字串	起點為`latitude,longitude`（例如） `47.610,-122.107`
航點2（`wp.1`）	是的	字串	終點為`latitude,longitude`（例如） `47.612,-122.204`
旅行模式（`travelMode`）	No	字串	`driving` （預設）或 `walking`
避開高速公路	No	boolean	對應至 `avoid=limitedAccessHighways`
避免通行費	No	boolean	對應至 `avoid=tollRoads`
避免渡輪	No	boolean	對應至 `avoid=ferries`
避免跨越國界	No	boolean	對應至 `avoid=borderCrossings`
Optimize	No	字串	`fastestWithoutTraffic`、 `fastestWithTraffic`或 `shortest`

回應： 路線摘要，包含行程距離（公尺）、時間（秒）、行程與交通量（秒）及路線段細節。

註：不支援運輸路線。 Azure 地圖服務路線指引僅支援 driving 和 walking。

依地址查詢地點 — `GetLocationByAddress`

將結構化地址編碼至座標與位置細節。

端點：GET https://atlas.microsoft.com/geocode?api-version=2023-06-01

參數	Required	類型	Description
地址行（`addressLine`）	No	字串	街道線（例如） `15595 NE 36th St`
地點（`locality`）	No	字串	城市（例如 `Redmond`）
行政區（`adminDistrict`）	No	字串	州縮寫（例如） `WA`
郵遞區號（`postalCode`）	No	字串	郵遞區號或郵遞區號（例如） `98052`
鄉村地區（`countryRegion`）	No	字串	ISO 兩字母國家代碼（例如 `US`）
最大結果（`top`）	No	整數	1–20，預設5

回應： GeoJSON FeatureCollection。每個功能具備：

geometry.coordinates — [longitude, latitude]
properties.confidence — High， Medium或 Low
properties.address— addressLine， locality，， adminDistrictspostalCode，（ countryRegion 具有 name 和 ISO的物件），formattedAddress

注意：Azure 地圖服務地理編碼不支援中國的地址。

按點查詢位置 — `GetLocationByPoint`

將緯度/經度座標反向編碼到地址。

端點（政策之後）：GET https://atlas.microsoft.com/reverseGeocode?api-version=2023-06-01&coordinates={longitude},{latitude}

該政策會longitude,latitude依序將和 longitudelatitude 參數合併到coordinates查詢參數中。

參數	Required	類型	Description
緯度`latitude`點（）	是的	double	例如，`47.64054`
點經度（`longitude`）	是的	double	例如，`-122.12934`

回應：與「依地址取得位置」的結構相同。GetLocationByAddress_Response

取得靜態地圖—— `GetMap`

取得一張以某點為中心的靜態地圖影像。

端點（政策之後）：GET https://atlas.microsoft.com/map/static?api-version=2024-04-01

該政策將緯度/經度合併到center參數（longitude,latitude），imagerySet映射到 Azure 地圖服務 style 值，並將可選的圖釘作為pins參數傳遞。

參數	Required	類型	Description
中心緯度（`latitude`）	是的	double	例如，`47.64054`
中心經度（`longitude`）	是的	double	例如，`-122.12934`
地圖風格（`imagerySet`）	是的	字串	請參見下方的樣式映射
縮放電平（`zoomLevel`）	是的	字串	0–20，預設 `10`
寬度 (像素)	No	整數	預設512
高度 (像素)	No	整數	預設512
圖像格式	No	字串	`jpeg` 或 `png` （預設 `png`）。 GIF 不支援。
圖釘緯度	No	double	推銷釘位置緯度
圖釘經度	No	double	推針位置經度
圖釘標籤	No	字串	簡短標籤文字

影像集映射：

`imagerySet` 輸入	Azure 地圖服務 `style`
`Road`	`main`
`Aerial`	`satellite`
`AerialWithLabels`	`satellite_road_labels`
`CanvasDark`	`dark`
`CanvasLight`	`road_shaded_relief`
`CanvasGray`	`grayscale_light`

回應： 二元影像（image/jpeg 或 image/png）。在 Power Automate 流程中，回應體是 base64 編碼的。要顯示或儲存圖片：

在儲存到 OneDrive/SharePoint 前，請使用base64ToBinary()表達式轉換。
使用 HTML 表格 或發送帶有 <img src="data:image/png;base64,{body/$content}"> 標籤的電子郵件動作來內嵌渲染。

政策備註

subscription-key 由政策注入;通話不會直接從來電者那裡轉接。
x-ms-apim-tokens進場時，頭origin部會被拆除。
Content-Type: application/json 所有非影像請求都被強制執行;圖片回應會在外發時恢復正確的 image/* 內容類型。
GetRoute 將簡單的查詢參數請求轉換成帶有 GeoJSON 主體的 POST——呼叫者不需要自行建構主體。

檔案儲存體

File	Purpose
apiDefinition.swagger.json	OpenAPI 定義
部署/policies.xml	APIM 政策
部署/PolicySourceCode.cs	政策 C# 邏輯
connector-config-internal.json	認證與環境設定
connector-config-cli.json	能力（`actions`）
connector-config-certification.json	API 名稱（`azuremaps`）與層級（標準）
connector-config-metadata.json	所有權元資料

正在建立連線

連接器支援下列驗證類型：


預設值	建立連線的參數。	所有地區	可共用

預設

適用：所有地區

建立連線的參數。

這是可共享的連接。如果 Power App 與其他使用者共用，也會共用連線。如需詳細資訊，請參閱畫布應用程式的連接器概觀 - Power Apps |Microsoft 文件

名稱	類型	Description	Required
訂閱金鑰	安全字串	Azure 地圖服務訂用帳戶金鑰	True

動作

Get route（預覽）	利用路標計算駕駛或步行路線。航點必須以緯度、經度座標提供。
以地址取得位置（預覽）	用地理編碼地址以取得座標和位置細節。
依點取得位置（預覽）	取得與緯度和經度座標相關的位置資訊。
取得靜態地圖（預覽）	取得一張以某點為中心的靜態地圖影像。 GIF 不支援;請使用JPEG或PNG。

Get route（預覽）

作業識別碼：: GetRoute

利用路標計算駕駛或步行路線。航點必須以緯度、經度座標提供。

參數

名稱	機碼	必要	類型	Description
航點 1	wp.0	True	string	起始航點為緯度、經度（例如 47.610，-122.107）。
航點 2	wp.1	True	string	終點為緯度、經度（例如 47.612，-122.204）。
移動模式	travelMode		string	路線的旅行方式。
避開高速公路	avoid_highways		boolean	避免在路線中使用高速公路。
避免通行費	avoid_tolls		boolean	避免在路線中使用收費公路。
避免渡輪	avoid_ferry		boolean	避免在路線中使用渡輪。
避免跨越國界	avoid_borderCrossing		boolean	避免在路線中越過國家/地區邊界。
Optimize	optimize		string	指定要優化路線的目標。

傳回

身體: GetRoute_Response

以地址取得位置（預覽）

作業識別碼：: GetLocationByAddress

用地理編碼地址以取得座標和位置細節。

參數

名稱	機碼	類型	Description
地址行	addressLine	string	地址的街道線（不包括城市、州等）。
地區（城市）	locality	string	當地，例如美國城市。
行政區（州）	adminDistrict	string	例如美國州的縮寫（例如WA）。
郵遞區號	postalCode	string	郵遞區號或郵遞區號。
國家/地區	countryRegion	string	ISO 兩字母國家代碼（例如 US）。
最大結果	top	integer	最多可返回的結果數（1-20）。默認值：5。

傳回

身體: GetLocationByAddress_Response

依點取得位置（預覽）

作業識別碼：: GetLocationByPoint

取得與緯度和經度座標相關的位置資訊。

參數

名稱	機碼	必要	類型	Description
點緯度	latitude	True	double	緯度座標對應反向地理編碼。範例：47.64054
點經度	longitude	True	double	經度座標為反向地理編碼。範例：-122.12934

傳回

身體: GetLocationByAddress_Response

取得靜態地圖（預覽）

作業識別碼：: GetMap

取得一張以某點為中心的靜態地圖影像。 GIF 不支援;請使用JPEG或PNG。

參數

名稱	機碼	必要	類型	Description
中央緯度	latitude	True	double	地圖中心的緯度。範例：47.64054
中央經度	longitude	True	double	地圖中心的經度。範例：-122.12934
地圖樣式	imagerySet	True	string	顯示地圖風格。
縮放等級	zoomLevel	True	string	縮放等級介於0到20之間。預設值：10
寬度 (像素)	width		integer	輸出影像的寬度（以像素為單位）。預設值：512
高度 (像素)	height		integer	輸出影像的高度（以像素為單位）。預設值：512
圖像格式	format		string	影像格式。預設：png
圖釘緯度	pushpinLatitude		double	圖釘緯度。
圖釘經度	pushpinLongitude		double	圖釘經度。
圖釘標籤	pushpinLabel		string	圖釘標籤（最多3字元）。

傳回

response: GetMap_Response

定義

GetRoute_Response

名稱	路徑	類型	Description
類型	type	string	GeoJSON 類型（始終是 FeatureCollection）。
Features	features	array of object	GeoJSON 功能陣列：Waypoint（起點/終點）、ManeuverPoint（轉彎步驟）及 RoutePath（路線摘要）。
功能類型	features.type	string
Geometry	features.geometry	object
特色類型	features.properties.type	string	特徵類型：Waypoint（起點/終點）、ManeuverPoint（轉彎步驟）或 RoutePath（整體路線摘要）。
距離（公尺）	features.properties.distanceInMeters	float	總路線距離以公尺計算。出現在 RoutePath 功能中。
持續時間 (秒)	features.properties.durationInSeconds	integer	預計出行時間（不含交通狀況）以幾秒計。出現在 RoutePath 功能中。
交通延遲（秒數）	features.properties.trafficDelayInSeconds	integer	因為塞車，幾秒鐘內就多花了時間。出現在 RoutePath 功能中。
交通擁堵	features.properties.trafficCongestion	string	交通擁堵程度（例如：低、中、高）。出現在 RoutePath 功能中。
使用的流量數據	features.properties.trafficDataUsed	string	所使用的交通資料類型（例如：無、流量）。出現在 RoutePath 功能中。
出發地點	features.properties.departureAt	string	預計出發時間（ISO 8601）。出現在 RoutePath 功能中。
抵達	features.properties.arrivalAt	string	預計抵達時間（ISO 8601）。出現在 RoutePath 功能中。
說明書	features.properties.instruction.text	string	人可讀的說明文字（例如「左轉進入東北第八街」）。
機動類型	features.properties.instruction.maneuverType	string	機動類型代碼（例如左轉、右轉、直行、抵達終點）。
航點索引	features.properties.order.inputIndex	integer	對應輸入航點的索引（0 = 起點，1 = 結束）。
腿指數	features.properties.order.legIndex	integer	該地標所屬路線段的索引。

GetLocationByAddress_Response

名稱	路徑	類型	Description
類型	type	string	GeoJSON 類型（始終是 FeatureCollection）。
Features	features	array of object	一系列地理編碼位置特徵。
功能類型	features.type	string
幾何類型	features.geometry.type	string
座標	features.geometry.coordinates	array of double	座標為[經度、緯度]。
特色類型	features.properties.type	string	特徵類型：地址或 PopulatedPlace。
信賴度	features.properties.confidence	string	比賽的信心等級（高、中、低）。
比賽代碼	features.properties.matchCodes	array of string	配對代碼（良好、模糊、上層）。
地址欄	features.properties.address.addressLine	string	街道地址線。
地區（城市）	features.properties.address.locality	string	城市或地區。
行政區	features.properties.address.adminDistricts	array of object	行政區劃陣列（例如州、縣）。
簡短名稱	features.properties.address.adminDistricts.shortName	string
名稱	features.properties.address.adminDistricts.name	string
郵遞區號	features.properties.address.postalCode	string	郵政編碼或郵政編碼。
國家地區	features.properties.address.countryRegion	string	國家或地區名稱。
格式化地址	features.properties.address.formattedAddress	string	完整的格式化地址字串。

GetMap_Response

地圖圖片: binary

Azure 地圖服務 （Preview）