本頁面由 Cloud Translation API 翻譯而成。

建立所選路線

本頁面將在下列章節中，說明如何使用 Roads Selection API 建立路徑及新增自訂屬性：

建立路徑：使用 create 端點定義單一路徑。
批次建立路線：使用 batchCreate 端點，在單一要求中定義多條路線。
建立包含中繼路線控點的路徑：定義最多 25 個中繼路線控點的路徑。
使用自訂路徑屬性：為路徑新增最多 10 個自訂鍵/值組合，方便整理。

建立路由

如要建立路線，請向 create 端點傳送 POST 要求。

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

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

dynamicRoute 物件，其中包含下列資訊：
- 所選路線的 origin。
- 所選路線的 destination。
- 路線的任何intermediates (又稱途經點)。
專屬 selectedRouteId。這個值的長度必須介於 4 至 63 個字元之間，且只能使用英數字元。如未提供 ID，系統會為所選路線產生專屬 ID。

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

curl -X POST -d '
    {"dynamic_route": { \
      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"
}

批次建立路徑

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

將 POST 要求傳送至 batchCreate 端點：

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

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

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

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

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "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"
    },
    {
      "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
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

建立包含中途路線控點的路徑

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

以下程式碼範例說明如何使用中途停靠點建立 SelectedRoute：

curl -X POST -d '
    {"dynamic_route": { \
        "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 物件會包含 route_attributes 欄位。

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

這些屬性有助於識別特定路線，或根據符合您需求的條件將路線分組。

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

"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 '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"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"