建立所選路線

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

建立路由

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

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

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

  • dynamicRoute 物件，其中包含下列資訊：
  • 專屬 selectedRouteId。這個值必須介於 4 至 63 個字元之間，且只能使用英數字元。如未提供 ID，系統會為所選路線產生專屬 ID。

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

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"
}

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

如要建立途經起點和目的地之間特定點的路徑，請在要求主體的 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"

使用自訂路徑屬性

為提升「道路管理分析」的路線管理和資料分析成效，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 端點。這個端點可讓您在一次呼叫中定義最多 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": [
        {
          "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"
    },
    {
      "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"
    }
  ]
}