Tài liệu này hướng dẫn bạn cách thực hiện yêu cầu đầu tiên đối với API Tối ưu hoá tuyến đường bằng trường hợp sử dụng thực tế.
Để đơn giản, ví dụ này sử dụng HTTP và JSON để minh hoạ API REST. Tuy nhiên, đối với môi trường sản xuất, bạn nên sử dụng gRPC để hưởng lợi từ hiệu suất của giao thức này. Tuy nhiên, bạn cần cài đặt gRPC. Để biết thêm thông tin, hãy xem bài viết Thư viện ứng dụng API Tối ưu hoá tuyến đường.
Trường hợp
Bạn cung cấp dịch vụ trông giữ chó từ 7:00 đến 19:00 tại San Francisco. Sáng nay, bạn cần đón 2 chú chó ở các địa điểm khác nhau trong thành phố. Cả 2 chủ chó đều cho bạn khoảng thời gian đón chó từ 7:30 đến 9:30.
Bạn có một chiếc xe tải nhỏ để thực hiện công việc này và trả cho tài xế 27 đô la mỗi giờ. Tài xế và xe tải nhỏ bắt đầu ngày làm việc tại trung tâm trông giữ chó của bạn lúc 7:00 và cần quay lại sau khi đón chó vào buổi sáng trước 12:00 để nghỉ ăn trưa.
Hôm nay là ngày 13 tháng 2 năm 2024 và tài xế có các nhiệm vụ sau:
- Đón chú chó núi Bern gần Tháp Coit.
- Đón chú chó Chihuahua tại Công viên South Sunset Playground.
- Đưa cả 2 chú chó đến trung tâm trông giữ chó tại Công viên Mission Dolores.
Bạn cần một tuyến đường giúp giảm thiểu thời gian chó ở trong xe tải nhỏ, đồng thời đáp ứng các yêu cầu về việc đón và trả chó.
Trước khi bắt đầu
Để chạy mã trong trường hợp ví dụ này, trước tiên, bạn phải hoàn tất hướng dẫn trong bài viết Thiết lập API Tối ưu hoá tuyến đường.
1. Chọn phương pháp tối ưu hoá tuyến đường
Route Optimization API có nhiều phương thức để bạn lựa chọn tuỳ thuộc vào độ phức tạp của vấn đề tối ưu hoá.
Vì trường hợp trông giữ chó này là một yêu cầu nhỏ và đơn giản, hãy sử dụng
phương thức chặn, chẳng hạn như optimizeTours, phương thức này sẽ nhanh chóng cung cấp kết quả
cho các yêu cầu nhỏ. Để biết thêm thông tin về các phương thức của Route Optimization API, hãy xem bài viết Điểm cuối đồng bộ và không đồng bộ.
Sử dụng URL sau để thực hiện yêu cầu HTTP POST đối với optimizeTours
phương thức:
https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours
Bạn cũng cần đặt thời gian chờ và thời hạn ngắn để giảm thời gian chờ không cần thiết. Đối với trường hợp trông giữ chó này, trình tối ưu hoá không cần nhiều thời gian để phản hồi yêu cầu của bạn, vì vậy, hãy sử dụng các chế độ cài đặt sau:
- Đặt tham số
timeoutthành 2 giây. - Để nguyên chế độ cài đặt thời hạn ở giá trị mặc định là 60 giây cho các yêu cầu REST.
2. Xây dựng nội dung thông báo yêu cầu
Sau khi chọn phương thức chặn optimizeTours và xác định thời gian chờ
cũng như thời hạn, bước tiếp theo là xây dựng nội dung thông báo yêu cầu.
Đối với trường hợp này, yêu cầu là thông báo OptimizeToursRequest được mã hoá dưới dạng JSON trong API REST.
Để xây dựng thông báo yêu cầu, hãy làm theo các bước tiếp theo:
Bắt đầu với cấu trúc yêu cầu cơ bản như sau:
{ "timeout": ..., "model": { "shipments": [...], "vehicles": [...], "globalStartTime": "...", "globalEndTime": "..." } }Để biết thêm thông tin về cấu trúc này, hãy xem hướng dẫn về khái niệm chính cho Cấu trúc cơ bản (ShipmentModel, Shipment và Vehicle).
Xác định các lô hàng. Trong trường
shipments, hãy thêm thông báoShipmentcho mỗi chú chó cần được đón và trả vào buổi sáng. Đây là nơi bạn xác định từng địa điểm và thời gian đón chó mà chủ chó ưu tiên, cũng như địa điểm và thời gian trả chó tại trung tâm trông giữ chó.Đối với mỗi chú chó, hãy tạo một
VisitRequestcho việc đón và một VisitRequest khác cho việc trả chó. Trong trường hợp này, việc trả chó được gọi là trả chó tại trung tâm trông giữ chó .Trong phần đón chó, hãy đặt
arrivalWaypointthành địa điểm đón chó (Tháp Coit cho chú chó núi Bern hoặc Công viên South Sunset Playground cho chú chó Chihuahua) vàtimeWindowsthành thời gian đón chó mà chủ chó yêu cầu (7:30 đến 9:30).Trong phần trả chó, hãy đặt
arrivalWaypointthành trung tâm trông giữ chó vàtimeWindowsthành thời gian trả chó bắt buộc (9:30 đến 11:30).
Để biết thêm thông tin về khoảng thời gian, hãy xem bài viết Khoảng thời gian.
Bạn có thể sử dụng trường
labelđể thêm giá trị nhận dạng cho từng lô hàng, chẳng hạn như "Bernese mountain dog" (Chó núi Bern) và "Chihuahua". Điều này có thể giúp bạn xác định các lô hàng trong phản hồi.
Để biết thêm thông tin về cách xác định lô hàng, hãy xem bài viết Lô hàng.
Xác định xe. Trong trường
vehicles, hãy thêm thông báoVehicle`Vehicle` cho một chiếc xe tải nhỏ của bạn với trung tâm trông giữ chó là điểm bắt đầu và điểm kết thúc, chi phí tiền lương của tài xế và giờ hoạt động của xe tải nhỏ.Đặt
startWaypointvàendWaypointcho xe tải nhỏ thành địa điểm bắt đầu và kết thúc trong ngày, đó là trung tâm trông giữ chó gần Công viên Mission Dolores.Để giảm thiểu chi phí hoạt động, bạn phải xác định các ràng buộc về chi phí của doanh nghiệp. Đặt tham số chi phí
costPerHourthành 27, đây là số tiền bạn trả cho tài xế để lái xe tải nhỏ trông giữ chó. Để biết thêm thông tin về các tham số chi phí, hãy xem bài viết Mô hình chi phí.Để đảm bảo trình tối ưu hoá tạo một tuyến đường trong giờ hoạt động của xe tải nhỏ, hãy xác định
startTimeWindowsthành phạm vi chấp nhận được để tài xế bắt đầu lái xe tải nhỏ vàendTimeWindowsthành phạm vi chấp nhận được để tài xế phải quay lại trung tâm trông giữ chó. Để biết thêm thông tin về khoảng thời gian, hãy xem bài viết Khoảng thời gian.
Để biết thêm thông tin về cách xác định xe, hãy xem bài viết Xe.
Đặt khoảng thời gian chung. Khoảng thời gian chung thể hiện khung thời gian mà xe tải nhỏ có thể đón và trả chó cho trung tâm trông giữ chó của bạn trong suốt cả ngày. Đối với trường hợp này, hãy đặt
globalStartTimethành 7:00 vàglobalEndTimethành 19:00 cho ngày 13 tháng 2 năm 2024. Đây là giờ hoạt động của trung tâm trông giữ chó.
3. Gửi yêu cầu
Sau đây là yêu cầu curl đơn giản dựa trên trường hợp trông giữ chó và sử dụng phương thức chặn optimizeTours.
Trước khi gửi yêu cầu, hãy thay thế PROJECT_NUMBER_OR_ID trong mã mẫu bằng mã dự án Google Cloud của bạn.
curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
"timeout": "2s",
"model": {
"shipments": [
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.802395,
"longitude": -122.405822
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T07:30:00Z",
"endTime": "2024-02-13T09:30:00Z"
}
]
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00Z",
"endTime": "2024-02-13T11:30:00Z"
}
]
}
],
"label": "Bernese mountain dog"
},
{
"pickups": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.738067,
"longitude": -122.498593
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T07:30:00Z",
"endTime": "2024-02-13T09:30:00Z"
}
]
}
],
"deliveries": [
{
"arrivalWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"timeWindows": [
{
"startTime": "2024-02-13T09:30:00Z",
"endTime": "2024-02-13T11:30:00Z"
}
]
}
],
"label": "Chihuahua"
}
],
"vehicles": [
{
"startWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"endWaypoint": {
"location": {
"latLng": {
"latitude": 37.760202,
"longitude": -122.426796
}
}
},
"costPerHour": 27,
"startTimeWindows": [
{
"startTime": "2024-02-13T07:00:00Z",
"endTime": "2024-02-13T07:15:00Z"
}
],
"endTimeWindows": [
{
"startTime": "2024-02-13T11:45:00Z",
"endTime": "2024-02-13T12:00:00Z"
}
]
}
],
"globalStartTime": "2024-02-13T07:00:00Z",
"globalEndTime": "2024-02-13T19:00:00Z"
}
}
EOM
Các tham số yêu cầu được dùng trong yêu cầu
Bảng sau đây mô tả các tham số yêu cầu được dùng trong nội dung yêu cầu của trường hợp ví dụ. Bạn có thể lọc nội dung theo cấp mẹ hoặc theo tìm kiếm văn bản.
| Cha mẹ | Tham số | Loại thuộc tính | Mô tả |
|---|---|---|---|
OptimizeToursRequest |
model |
đối tượng (ShipmentModel) |
Đây là cốt lõi của yêu cầu. Đây là một đối tượng duy nhất nơi bạn
xác định toàn bộ vấn đề, bao gồm tất cả các chú chó bạn cần đón và
trả (shipments)
và xe tải nhỏ trong đội xe của bạn
(vehicles).
Hãy coi đây là bản thiết kế hoàn chỉnh cho vấn đề bạn cần tối ưu hoá. |
timeout |
Thời lượng | Tham số này chỉ định thời gian tối đa mà máy chủ xử lý một yêu cầu trước khi trả về phản hồi. Hãy sử dụng tham số này để rút ngắn thời gian chờ. Đối với các yêu cầu nhỏ và nhanh, chẳng hạn như trường hợp trông giữ chó này, hãy đặt giá trị này thành 2 giây. | |
ShipmentModel |
shipments[] |
mảng đối tượng (Shipment) |
Đây là một mảng đối tượng, trong đó mỗi đối tượng đại diện cho một chú chó cần được đón hoặc trả. |
vehicles[] |
mảng đối tượng (Vehicle) |
Đây là một mảng đối tượng, trong đó mỗi đối tượng xác định một xe trong đội xe của bạn. Đây là nơi bạn mô tả các tài nguyên của mình, chẳng hạn như xe tải nhỏ thực hiện việc đón và trả chó. Bạn phải xác định ít nhất một xe để nhận được tuyến đường tối ưu. | |
globalStartTime |
Dấu thời gian | Đây là thời gian sớm nhất có thể xảy ra cho bất kỳ sự kiện nào trong toàn bộ mô hình của bạn. Tham số này thu hẹp vấn đề tối ưu hoá theo thời gian, điều này rất quan trọng để tính toán chính xác lưu lượng truy cập và tuyến đường Đối với trường hợp trông giữ chó này, hãy đặt tham số này thành thời gian sớm nhất mà tài xế có thể lái xe tải nhỏ trong ngày, đó là 7:00 ngày 13 tháng 2 năm 2024. | |
globalEndTime |
Dấu thời gian | Đây là thời gian muộn nhất có thể xảy ra cho bất kỳ sự kiện nào trong toàn bộ mô hình của bạn. Đối với trường hợp trông giữ chó này, hãy đặt tham số này thành thời điểm xe tải nhỏ dự kiến kết thúc hoạt động, đó là 19:00 ngày 13 tháng 2 năm 2024. | |
Shipment |
pickups[] |
mảng đối tượng (VisitRequest) |
Đây là danh sách tất cả các lựa chọn đến lấy hàng có thể có cho lô hàng. Trình tối ưu hoá sẽ chọn lựa chọn tốt nhất để giải quyết vấn đề của bạn. Đối với trường hợp trông giữ chó này, hãy liệt kê các địa điểm đón chó và khoảng thời gian mà mỗi chủ chó cung cấp cho từng chú chó. |
deliveries[] |
mảng đối tượng (VisitRequest) |
Đây là danh sách tất cả các lựa chọn trả chó có thể có cho lô hàng. Trình tối ưu hoá sẽ chọn lựa chọn tốt nhất để giải quyết vấn đề của bạn. Đối với trường hợp trông giữ chó này, hãy liệt kê địa điểm của cơ sở trông giữ chó và khoảng thời gian mà tài xế cần quay lại để ăn trưa cho từng chú chó. | |
label |
chuỗi | Đây là giá trị nhận dạng cho một lô hàng cụ thể trong yêu cầu của bạn. Bạn có thể chỉ định nhãn trong yêu cầu để dễ đọc phản hồi hơn. Đối với trường hợp trông giữ chó này, hãy sử dụng một chuỗi mô tả như "Chihuahua", "Bernese mountain dog" (Chó núi Bern) hoặc tên của chú chó để so khớp giải pháp với dữ liệu đầu vào khi bạn nhận được phản hồi API. | |
VisitRequest |
arrivalWaypoint[] |
đối tượng (Waypoint) |
Đây là vị trí của một lượt ghé thăm cụ thể trên tuyến đường. Bạn có thể xác định vị trí này
bằng cách sử dụng toạ độ vĩ độ và kinh độ, mã địa điểm hoặc hướng. Trong
trường hợp trông giữ chó này, hãy đặt tham số này thành địa điểm do chủ chó cung cấp cho
pickups
và thành địa chỉ của trung tâm trông giữ chó cho
deliveries. |
timeWindows[] |
mảng đối tượng (TimeWindow) |
Đây là một mảng đối tượng xác định các ràng buộc về thời gian cho việc đón hoặc trả chó. Đối với trường hợp này, hãy sử dụng tham số này để xác định khoảng thời gian đón chó cho từng chú chó và khoảng thời gian chấp nhận được để trả chó tại trung tâm trông giữ chó. | |
Vehicle |
startWaypoint[] |
đối tượng (Waypoint) |
Đây là vị trí bắt đầu của tuyến đường của xe, được xác định bằng toạ độ vĩ độ và kinh độ hoặc mã địa điểm. Tham số này cho trình tối ưu hoá biết nơi xe phải bắt đầu tuyến đường. Nếu bạn không xác định điểm tham chiếu này, trình tối ưu hoá sẽ chọn một trong các điểm đón hoặc trả chó làm vị trí bắt đầu. Đối với trường hợp trông giữ chó này, vì tài xế bắt đầu ngày làm việc tại cơ sở trông giữ chó, hãy sử dụng toạ độ của Công viên Mission Dolores. |
endWaypoint[] |
đối tượng (Waypoint) |
Đây là điểm đến cuối cùng của tuyến đường của xe, được xác định bằng toạ độ vĩ độ và kinh độ hoặc mã địa điểm. Tham số này cho trình tối ưu hoá biết nơi xe phải kết thúc tuyến đường. Nếu bạn không xác định điểm tham chiếu này trình tối ưu hoá sẽ chọn một trong các điểm đón hoặc trả chó làm điểm kết thúc của tuyến đường. Đối với trường hợp trông giữ chó này, vì tài xế phải kết thúc ngày làm việc tại cơ sở trông giữ chó, hãy sử dụng toạ độ của Công viên Mission Dolores. | |
costPerHour |
số | Đây là chi phí phát sinh cho mỗi giờ sử dụng xe, bất kể xe đang di chuyển hay dừng. Đối với trường hợp trông giữ chó này, hãy sử dụng tham số này để mô hình hoá tiền lương theo giờ của tài xế. | |
startTimeWindows[] |
mảng đối tượng (TimeWindow) |
Đây là khoảng thời gian chấp nhận được để tài xế bắt đầu lái xe tải nhỏ để đón chó vào buổi sáng. | |
endTimeWindows[] |
mảng đối tượng (TimeWindow) |
Đây là khoảng thời gian chấp nhận được để tài xế lái xe tải nhỏ xong và đỗ xe trở lại trung tâm trông giữ chó. |