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 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 thông tin sau:

  • Đối tượng dynamicRoute có thông tin sau:
    • The origin của tuyến đường đã chọn.
    • The destination của tuyến đường đã chọn.
    • Bất kỳ intermediates nào (còn gọi là điểm tham chiếu) của tuyến đường.
  • 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ự 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 duy nhất cho tuyến đường đã chọn.
.

Mã mẫu sau đây cho thấy cấu trúc của 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ể sử 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 phản hồi điểm cuối thành công 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, hãy sử dụng batchCreate điểm cuối. Đ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ảng requests. Mỗi đối tượng trong mảng này là một CreateSelectedRouteRequest mà xác định một tài nguyên SelectedRoute riêng lẻ.

Mã mẫu sau đây cho thấy cấu trúc của 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ảng 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 khởi hành và điểm đến, hãy đưa 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 tham chiếu được xác định bằng latitude và longitude. Một tuyến đường có thể có tối đa 25 điểm tham chiếu.

Mã mẫu sau đây cho biết cách tạo 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"

Sử dụng các thuộc tính tuỳ chỉnh của tuyến đường

Để nâng cao 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 bao gồm 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 để 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.

Dưới đâ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 làm 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 trên các gói 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à các giá trị tương ứng.
  • Tinh chỉnh phân tích BigQuery: Trong các bảng BigQuery, bạn có thể sử dụng các 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 hơn.

Mã mẫu tiếp theo cho biết cách tạo SelectedRoute có tuỳ chỉnh routeAttributes.

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"