Tạo các tuyến đã chọn

Trang này mô tả cách tạo tuyến đường và thêm các thuộc tính tuỳ chỉnh bằng Roads Selection API trong các phần sau:

Tạo tuyến đường

Để tạo một tuyến đường, hãy gửi yêu cầu POST đến điểm cuối create.

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

Nội dung yêu cầu phải là một đối tượng JSON xác định tài nguyên SelectedRoute. Đối tượng này chỉ định những thông tin sau:

  • Đối tượng dynamicRoute có thông tin sau:
    • origin của tuyến đường đã chọn.
    • destination của tuyến đường đã chọn.
    • Mọi intermediates (còn gọi là điểm tham chiếu) của tuyến đường.
  • Một selectedRouteId duy nhất. Giá trị này phải có độ dài từ 4 đến 63 ký tự và chỉ sử dụng các ký tự bao gồm chữ và số. Nếu bạn không cung cấp mã nhận dạng, hệ thống sẽ tạo một mã nhận dạng riêng biệt cho tuyến đường đã chọn.

Mẫu mã sau đây cho thấy cấu trúc của một yêu cầu POST đến điểm cuối create.

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"

Khi thành công, API sẽ trả về tài nguyên SelectedRoute. Phản hồi bao gồm selectedRouteId trong trường name. Bạn có thể dùng selectedRouteId này để truy xuất hoặc xoá tài nguyên SelectedRoute.

Mã mẫu sau đây cho thấy cấu trúc của một phản hồi thành công của điểm cuối 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"
}

Tạo hàng loạt tuyến đường

Để tạo nhiều tuyến đường trong một yêu cầu duy nhất, hãy sử dụng điểm cuối batchCreate. Điểm cuối này cho phép bạn xác định tối đa 1.000 tuyến đường trong một lệnh gọi.

Gửi yêu cầu POST đến điểm cuối batchCreate:

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

URL sử dụng cú pháp Chuyển mã gRPC.

Nội dung yêu cầu phải là một đối tượng JSON chứa một mảng requests. Mỗi đối tượng trong mảng này là một CreateSelectedRouteRequest xác định một tài nguyên SelectedRoute riêng lẻ.

Mẫu mã sau đây cho thấy cấu trúc của một yêu cầu POST đến điểm cuối batchCreate:

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"

Khi thành công, API sẽ trả về một phản hồi chứa một mảng gồm các tài nguyên SelectedRoute đã được tạo.

Mã mẫu sau đây cho thấy cấu trúc của phản hồi điểm cuối 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"
    }
  ]
}

Tạo tuyến đường có các điểm tham chiếu trung gian

Để tạo một tuyến đường đi qua các điểm cụ thể giữa điểm xuất phát và điểm đến, hãy thêm một mảng intermediates vào đối tượng dynamicRoute trong nội dung yêu cầu. Mỗi phần tử trong mảng intermediates là một điểm đánh dấu được xác định bằng latitude và longitude. Một tuyến đường có thể có tối đa 25 điểm đánh dấu.

Đoạn mã mẫu sau đây cho biết cách tạo một SelectedRoute có các điểm tham chiếu trung gian:

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"

Khai thác các thuộc tính tuỳ chỉnh của tuyến đường

Để tăng cường khả năng quản lý tuyến đường và phân tích dữ liệu trong Roads Management Insights, đối tượng SelectedRoute có một trường route_attributes.

Sử dụng trường routeAttributes để xác định các thuộc tính tuỳ chỉnh của riêng bạn cho từng tuyến đường, trong đó mỗi thuộc tính là một cặp khoá-giá trị. Bạn có thể cung cấp tối đa 10 cặp khoá-giá trị tuỳ chỉnh cho mỗi tuyến đường.

Các thuộc tính này rất hữu ích khi xác định các tuyến đường cụ thể hoặc nhóm các tuyến đường dựa trên tiêu chí phù hợp với nhu cầu của bạn.

Sau đây là một số ví dụ về các thuộc tính tuyến đường mà bạn có thể sử dụng:

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

Hãy tuân theo các nguyên tắc tiếp theo khi xác định trường routeAttributes:

  • Khoá không được bắt đầu bằng tiền tố goog.
  • Độ dài của mỗi khoá và mỗi giá trị không được vượt quá 100 ký tự.

Sau đó, bạn có thể sử dụng các routeAttributes tuỳ chỉnh này trong Roads Management Insights theo những cách sau:

  • Lọc thông báo Pub/Sub: Bạn có thể đặt bộ lọc cho các thuê bao Pub/Sub để chỉ nhận thông tin cập nhật cho những tuyến đường khớp hoặc không khớp với các khoá thuộc tính cụ thể và giá trị tương ứng của chúng.
  • Tinh chỉnh thông tin phân tích BigQuery: Trong các bảng BigQuery, bạn có thể dùng những thuộc tính này để lọc các tuyến đường cụ thể dựa trên giá trị của một thuộc tính. Bạn cũng có thể nhóm các tuyến đường theo một khoá thuộc tính cụ thể để phân tích dữ liệu có mục tiêu rõ ràng hơn.

Đoạn mã mẫu tiếp theo cho thấy cách tạo SelectedRoute bằng routeAttributes tuỳ chỉnh.

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"