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

Trang này mô tả cách tạo tuyến đường và thêm thuộc tính tùy 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.
  • selectedRouteId duy nhất. Giá trị này phải có từ 4 đến 63 ký tự và các ký tự hợp lệ là a-z, A-Z, 0-9, - hoặc _. 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 một yêu cầu POST đến điểm cuối 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"

Nếu 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 một phản hồi thành công từ đ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 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 phần 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 '
    {
      "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"

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

Để cải thiện khả năng quản lý tuyến đường và phân tích dữ liệu trong Thông tin chi tiết về quản lý đường, đối tượng SelectedRoute có một trường routeAttributes.

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 25 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.

Sau đây là một số ví dụ về 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 sau 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 gói thuê bao Pub/Sub để chỉ nhận thông tin cập nhật về 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 các khoá đó.
  • Tinh chỉnh thông tin phân tích trong BigQuery: Trong bảng BigQuery, bạn có thể sử dụng các thuộc tính này để lọc ra những tuyến 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 theo một khoá thuộc tính cụ thể để phân tích dữ liệu theo mục tiêu cụ thể hơ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 '
    {
    "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"

Tạo tuyến đường theo lô

Để tạo nhiều tuyến đường trong một yêu cầu, 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ả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ã mẫu 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": [
        {
          "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"

Nếu thành công, API sẽ trả về một phản hồi chứa một 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"
    }
  ]
}