google-maps

概述

Google Maps 是一个用于调用 Google Maps Platform API 的技能，通过 Google Maps OAuth 连接器进行访问。当用户提到 "Google Maps"、"geocode" 等相关需求时可以使用该技能。

主要能力

该技能覆盖以下 OAuth API 主机与端点：

地理编码 v4：https://geocode.googleapis.com
- GET https://geocode.googleapis.com/v4/geocode/address/{address_query}
- GET https://geocode.googleapis.com/v4/geocode/location/{location_query}
Places API (New)：https://places.googleapis.com
- POST https://places.googleapis.com/v1/places:searchText
- GET https://places.googleapis.com/v1/places/{place_id}
Routes API：https://routes.googleapis.com
- POST https://routes.googleapis.com/directions/v2:computeRoutes
- POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

使用方式

前置条件

在 vm0.ai 的 Settings -> Connectors（OAuth）中连接 Google Maps。
所连接的 Google 账号必须能访问已启用相关 Maps Platform API 的 Google Cloud 项目。
沙箱环境提供 $GOOGLE_MAPS_TOKEN，作为已连接 OAuth 访问令牌的占位符。
仅通过 Authorization: Bearer $GOOGLE_MAPS_TOKEN 发送该令牌；vm0 会在网络边界处替换该请求头。
不要将 $GOOGLE_MAPS_TOKEN 作为 key= 查询参数传递，它不是 Maps API key。

示例请求

1. 正向地理编码地址

curl -s "https://geocode.googleapis.com/v4/geocode/address/Beijing%20Zhongguancun" \
  --header "Authorization: Bearer $GOOGLE_MAPS_TOKEN" \
  --header "X-Goog-FieldMask: results.formattedAddress,results.location" \
  | jq '.results[] | {formattedAddress, location}'

2. 反向地理编码坐标

curl -s "https://geocode.googleapis.com/v4/geocode/location/39.9799664,116.3160877" \
  --header "Authorization: Bearer $GOOGLE_MAPS_TOKEN" \
  --header "X-Goog-FieldMask: results.formattedAddress,results.location" \
  | jq '.results[] | {formattedAddress, location}'

3. 按文本搜索地点

curl -s -X POST "https://places.googleapis.com/v1/places:searchText" \
  --header "Authorization: Bearer $GOOGLE_MAPS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "X-Goog-FieldMask: places.id,places.displayName,places.formattedAddress,places.location,places.googleMapsUri" \
  -d '{"textQuery":"coffee in Palo Alto","maxResultCount":5}' \
  | jq '.places[] | {id, name: .displayName.text, formattedAddress, location, googleMapsUri}'

4. 获取地点详情

curl -s "https://places.googleapis.com/v1/places/ChIJl_iF0xO7j4AR-hSIJRPYIvA" \
  --header "Authorization: Bearer $GOOGLE_MAPS_TOKEN" \
  --header "X-Goog-FieldMask: id,displayName,formattedAddress,location,googleMapsUri" \
  | jq '{id, name: .displayName.text, formattedAddress, location, googleMapsUri}'

5. 计算驾车路线

curl -s -X POST "https://routes.googleapis.com/directions/v2:computeRoutes" \
  --header "Authorization: Bearer $GOOGLE_MAPS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline" \
  -d '{"origin":{"address":"Beijing Zhongguancun"},"destination":{"address":"Tiananmen Square Beijing"},"travelMode":"DRIVE"}' \
  | jq '.routes[] | {duration, distanceMeters, encodedPolyline: .polyline.encodedPolyline}'

6. 计算路线矩阵

curl -s -X POST "https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix" \
  --header "Authorization: Bearer $GOOGLE_MAPS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "X-Goog-FieldMask: originIndex,destinationIndex,duration,distanceMeters,status" \
  -d '{"origins":[{"waypoint":{"address":"Beijing Zhongguancun"}}],"destinations":[{"waypoint":{"address":"Tiananmen Square Beijing"}}],"travelMode":"DRIVE"}' \
  | jq '.[] | {originIndex, destinationIndex, duration, distanceMeters, status}'

故障排查

如果请求失败，可运行：

zero doctor check-connector --env-name GOOGLE_MAPS_TOKEN
zero doctor check-connector --url https://geocode.googleapis.com/v4/geocode/address/Beijing --method GET
zero doctor check-connector --url https://places.googleapis.com/v1/places:searchText --method POST
zero doctor check-connector --url https://routes.googleapis.com/directions/v2:computeRoutes --method POST

注意：check-connector --url 命令用于验证连接器与防火墙匹配情况，它并不能证明 Google API 请求体、字段掩码、计费或项目配置是有效的。

适用场景

需要将地址转换为坐标（正向地理编码）或将坐标转换为地址（反向地理编码）。
需要按文本搜索地点或获取某地点详情。
需要计算驾车等出行方式的路线、距离与时长。
需要计算多点之间的路线矩阵（起点数与终点数相乘即路线元素数量）。

限制与注意事项

Google Maps Platform 请求由 Google 计费，请将请求范围限定在用户实际需要范围内。
对于 Geocoding v4、Places API (New) 与 Routes API 的响应，始终发送明确的 X-Goog-FieldMask。
除非用户明确需要全部字段，否则不要使用 * 等通配符字段掩码。
路线矩阵的成本与延迟随路线元素数量（origins.length * destinations.length）增长。
优先使用上述较新的、兼容 OAuth 的 API；旧版 maps.googleapis.com/maps/api/... 端点不在本连接器覆盖范围内。
使用 Geocoding v4 路径绑定时，应对地址与坐标路径段进行 URL 编码。
保持请求体精简，仅请求用户需要的字段。
应检查 JSON 响应中的 API 级错误；连接器与权限错误通常会在 Google API 响应之前以 HTTP 4xx 或 5xx 状态出现。
该技能的官方收费与价格信息暂未提供。