建立所選路線

本頁說明如何使用 Roads Selection API 建立路線及新增自訂屬性，各節內容如下：

建立路由

如要建立路徑，請傳送 POST 要求至 create 端點。

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID

要求主體必須是定義 SelectedRoute 資源的 JSON 物件。這個物件會指定下列資訊：

  • dynamicRoute 物件，包含下列資訊：
  • 不重複的 selectedRouteId。這個值的長度應為 4 至 63 個字元，有效字元為 a-z、A-Z、0-9、- 或 _。如未提供 ID，系統會為所選路徑產生專屬 ID。

建立固定路徑 (預設)

根據預設，系統會建立固定路線，並與建立時計算的靜態路線幾何圖形 (匯出至 routes_status BigQuery 資料表) 保持一致，不考量即時路況。這可確保交通資訊監控作業維持一致，不受路況變化影響。

您可以在要求主體中設定 dynamicRouting 布林值欄位，指定路徑為固定 (false，預設值) 或動態 (true)。

下列程式碼範例顯示 POST 要求create固定路線的結構。

curl -X POST -d '
    {
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE,
          "longitude": ORIGIN_LONGITUDE
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE,
          "longitude": DESTINATION_LONGITUDE
        }
      }
    }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

如果成功，API 會傳回 SelectedRoute 資源。回應會在 name 欄位中包含 selectedRouteId。您可以使用這個 selectedRouteId 擷取或刪除 SelectedRoute 資源。

下列程式碼範例顯示成功的 create 端點回應結構。

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING",
  "dynamicRouting": false
}

建立動態路徑

您也可以將 dynamicRouting 欄位設為 true，建立動態路徑。由於 Google 的路線規劃平台每次都會找出最佳路線，因此路線幾何圖形可能會因路況而異。

下列程式碼範例顯示向動態路徑create POST 要求的結構：

curl -X POST -d '
    {
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE,
          "longitude": ORIGIN_LONGITUDE
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE,
          "longitude": DESTINATION_LONGITUDE
        }
      },
      "dynamicRouting": true
    }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

下列程式碼範例顯示 create 端點成功回應的結構。

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING",
  "dynamicRouting": true
}

建立含有中途路線控點的路線

如要建立經過起點和目的地之間特定點的路徑，請在要求主體的 dynamicRoute 物件中加入 intermediates 陣列。intermediates 陣列中的每個元素都是由 latitude 和 longitude 定義的路線控點。一條路線最多可有 25 個路線控點。

以下程式碼範例說明如何建立含有中途路線控點的 SelectedRoute：

curl -X POST -d '
    {
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE,
          "longitude": ORIGIN_LONGITUDE
        },
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {
          "latitude": DESTINATION_LATITUDE,
          "longitude": DESTINATION_LONGITUDE
        }
      }
    }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

使用自訂路徑屬性

為強化 Roads Management Insights 的路線管理和資料分析功能，SelectedRoute 物件包含 routeAttributes 欄位。

使用 routeAttributes 欄位，為個別路徑定義自訂屬性，其中每個屬性都是鍵/值組合。每條路徑最多可提供 25 個自訂鍵/值組合。

這些屬性可用於識別特定路徑，或根據與需求相關的條件將路徑分組。

以下列舉幾個可用的路線屬性：

  • "road_classification": "highway"
  • "maintenance_zone": "north_district"
  • "event_id": "marathon_2024"
  • "pavement_type": "asphalt"

定義 routeAttributes 欄位時，請遵循下列規範：

  • 鍵的開頭不得為前置字串 goog。
  • 每個鍵和值的長度不得超過 100 個半形字元。

接著，您可以在道路管理分析中，透過下列方式使用這些自訂 routeAttributes：

  • 篩選 Pub/Sub 通知：您可以在 Pub/Sub 訂閱項目設定篩選器，只接收符合或不符合特定屬性鍵及其對應值的路徑更新。
  • 精細調整 BigQuery 分析：在 BigQuery 資料表中，您可以根據屬性值，使用這些屬性篩選特定路徑。您也可以依特定屬性鍵將路徑分組，進行更精確的資料分析。

下一個程式碼範例說明如何使用自訂 routeAttributes 建立 SelectedRoute。

curl -X POST -d '
    {
    "dynamicRoute": {
      "origin": {
        "latitude": ORIGIN_LATITUDE,
        "longitude": ORIGIN_LONGITUDE
      },
      "destination": {
        "latitude": DESTINATION_LATITUDE,
        "longitude": DESTINATION_LONGITUDE
      }
    },
    "routeAttributes": {
      "ATTRIBUTE_KEY": "ATTRIBUTE_VALUE"
    }
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

批次建立路徑

如要在單一要求中建立多條路線，請使用 batchCreate 端點。這個端點可讓您在一次呼叫中定義最多 1000 條路線。

向 batchCreate 端點傳送 POST 要求：

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate

這個網址使用 gRPC 轉碼語法。

要求主體必須是包含 requests 陣列的 JSON 物件。這個陣列中的每個物件都是 CreateSelectedRouteRequest，用於定義個別 SelectedRoute 資源。

下列程式碼範例顯示傳送至 batchCreate 端點的 POST 要求結構：

curl -X POST -d '
    {
      "requests": [
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_1,
                "longitude": ORIGIN_LONGITUDE_1
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_1,
                "longitude": DESTINATION_LONGITUDE_1
              }
            }
          },
          "selectedRouteId": "route-one"
        },
        {
          "selectedRoute": {
            "dynamicRoute": {
              "origin": {
                "latitude": ORIGIN_LATITUDE_2,
                "longitude": ORIGIN_LONGITUDE_2
              },
              "destination": {
                "latitude": DESTINATION_LATITUDE_2,
                "longitude": DESTINATION_LONGITUDE_2
              }
            }
          },
          "selectedRouteId": "route-two"
        }
      ]
    }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/"\
"PROJECT_NUMBER/selectedRoutes:batchCreate"

如果成功，API 會傳回回應，其中包含已建立的 SelectedRoute 資源陣列。

下列程式碼範例顯示 batchCreate 端點回應的結構：

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING",
      "dynamicRouting": false
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING",
      "dynamicRouting": false
    }
  ]
}