Map Management API 指南和範例

您可以使用 Map Management API，透過程式輔助方式管理 v2alpha (實驗功能) 和 v2beta (預先發布版) 端點的雲端式地圖樣式設定資源。

作業摘要

如要使用 Map Management API 呈現自訂地圖，請按照下列主要步驟操作：

  1. 建立 StyleConfig：使用 JSON 表示法定義地圖的視覺外觀，包括顏色、顯示設定和密度設定。
  2. 建立 MapConfig：建立專屬地圖 ID，做為地圖 ID 和高階功能的容器。
  3. 與 MapContextConfig 建立關聯：將 StyleConfig (和選用資料集) 連結至 MapConfig 中的特定地圖變化版本 (例如 ROADMAP 或 SATELLITE)。

預設行為

使用第 2 版端點時，請注意下列預設行為：

  • 地圖類型：預設地圖算繪類型為 RASTER。如要使用向量地圖，您必須在 MapConfig 中明確將 map_type 設為 VECTOR。
  • 地圖變化版本：如果在建立 MapContextConfig 時未指定 map_variants，則根據預設，設定只會套用至 ROADMAP 變化版本。
  • 基本樣式：如果 json_style_sheet 為空白或未在 StyleConfig 中提供，系統會使用預設未套用樣式的 Google 基本地圖。

使用 StyleConfigs

StyleConfig 包含 JSON 樣式定義。

建立 StyleConfig

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://mapmanagement.googleapis.com/v2beta/projects/YOUR_PROJECT_ID/styleConfigs \
-d '{
  "display_name": "My Custom Style",
  "json_style_sheet": "[{\"featureType\":\"all\",\"stylers\":[{\"saturation\":-100}]}]"
}'

列出 StyleConfig

curl -X GET \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
https://mapmanagement.googleapis.com/v2beta/projects/YOUR_PROJECT_ID/styleConfigs

使用 MapConfig

MapConfig 會定義地圖的身分和核心算繪類型。

建立 MapConfig

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://mapmanagement.googleapis.com/v2beta/projects/YOUR_PROJECT_ID/mapConfigs \
-d '{
  "display_name": "My New Map",
  "map_type": "VECTOR"
}'

使用 MapContextConfigs

MapContextConfig 會將樣式設定連結至 MapConfig。

建立 MapContextConfig

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://mapmanagement.googleapis.com/v2beta/projects/YOUR_PROJECT_ID/mapConfigs/YOUR_MAP_ID/mapContextConfigs \
-d '{
  "style_config": "projects/YOUR_PROJECT_ID/styleConfigs/YOUR_STYLE_ID",
  "map_variants": ["ROADMAP", "NAVIGATION"]
}'

錯誤

  • PERMISSION_DENIED：要求缺少足夠的 IAM 權限，或專案未啟用 API。
  • NOT_FOUND：指定的資源 (專案、MapConfig 或 StyleConfig) 不存在。
  • INVALID_ARGUMENT：要求主體格式錯誤，或包含無效的欄位值。