Trang này được dịch bởi Cloud Translation API.

Tạo yêu cầu Tối ưu hóa tuyến đường đầu tiên của bạn

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

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 đến Route Optimization API bằng một tình huống sử dụng thực tế.

Để đơn giản, ví dụ này sử dụng HTTP và JSON để minh hoạ REST API. Tuy nhiên, đối với môi trường sản xuất, bạn nên sử dụng gRPC vì những lợi ích về hiệu suất mà giao thức này mang lại. Tuy nhiên, gRPC yêu cầu bạn phải cài đặt một số thành phần. Để biết thêm thông tin, hãy xem Thư viện ứng dụng Route Optimization API.

Trường hợp

Bản đồ San Francisco có các ghim cho Tháp Coit, Công viên Mission Dolores và Công viên Sân chơi South Sunset

Bạn cung cấp dịch vụ trông giữ thú cưng từ 7:00 đến 19:00 ở San Francisco. Sáng nay, bạn cần đón 2 chú cún ở những địa điểm khác nhau trong thành phố. Cả hai chủ sở hữu chú cún đều cho bạn khoảng thời gian đón từ 7:30 đến 9:30.

Bạn có một chiếc xe tải cho công việc này và bạn trả cho người lái xe 27 đô la mỗi giờ. Lái xe và xe van bắt đầu ngày làm việc tại trung tâm chăm sóc ban ngày của bạn lúc 7:00 và cần quay lại sau khi đón trẻ vào buổi sáng muộn nhất là 12:00 để nghỉ trưa.

Hôm nay là ngày 13 tháng 2 năm 2024 và người lái xe có những việc cần làm sau đây:

Đón chú chó núi Bern gần tháp Coit.
Đón chú chó Chihuahua tại Công viên sân chơi South Sunset.
Đưa cả hai chú chó đến trung tâm chăm sóc ban ngày cho 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, đồ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 tình huống ví dụ này, trước tiên, bạn phải hoàn tất hướng dẫn trong phần Thiết lập Route Optimization API.

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 này là một yêu cầu nhỏ và đơn giản, hãy sử dụng một 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 Route Optimization API, hãy xem phần Đ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 đến phương thức optimizeTours:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

Bạn cũng cần đặt chế độ cài đặt thời gian chờ và thời hạn ở mức ngắn để giảm mọi thời gian chờ không cần thiết. Đối với trường hợp 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ố timeout thành 2 giây.
Để nguyên chế độ cài đặt thời hạn ở mức mặc định là 60 giây cho các yêu cầu REST.

2. Tạo nội dung yêu cầu

Sau khi chọn phương thức chặn optimizeTours và xác định chế độ cài đặt thời gian chờ và thời hạn, bước tiếp theo là tạo nội dung của thông báo yêu cầu.

Đối với trường hợp này, yêu cầu là một thông báo OptimizeToursRequest được mã hoá dưới dạng JSON trong REST API.

Để tạo thông báo yêu cầu, hãy làm theo các bước tiếp theo:

Bắt đầu bằng 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, 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 lô hàng. Trong trường shipments, hãy thêm một thông báo Shipment cho 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 mà chủ sở hữu chó muốn, cũng như địa điểm và thời gian mà trung tâm chăm sóc ban ngày muốn đón chó.
1. Đối với mỗi chú cún, hãy tạo một VisitRequest để đón và một VisitRequest khác để giao. Trong trường hợp này, VisitRequest giao được gọi là điểm trả khách tại cơ sở chăm sóc ban ngày.
  - Trong phần đón, hãy đặt arrivalWaypoint thành vị trí đón chú chó (Tháp Coit cho chú chó Bernese hoặc Công viên sân chơi South Sunset cho chú chó Chihuahua) và timeWindows thành thời gian đón mà chủ nhân yêu cầu (từ 7:30 đến 9:30).
  - Trong phần giao hàng, hãy đặt arrivalWaypoint thành trung tâm chăm sóc ban ngày và timeWindows thành thời gian giao hàng 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.
2. 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ư "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 các loại xe. Trong trường vehicles, hãy thêm thông báo Vehicle cho một xe của bạn với trung tâm chăm sóc ban ngày làm điểm bắt đầu và điểm kết thúc, chi phí tiền lương của người lái xe và giờ hoạt động của xe.
1. Đặt startWaypoint và endWaypoint cho xe tải lần lượt là vị trí bắt đầu và vị trí kết thúc trong ngày, tức là trung tâm chăm sóc ban ngày gần Công viên Mission Dolores.
2. Để giảm thiểu chi phí vận hành, bạn phải xác định các hạn chế về chi phí của doanh nghiệp. Đặt tham số chi phí costPerHour thành 27, đây là số tiền bạn trả cho người lái xe để lái chiếc xe van của trường mầm non cho chó. Để biết thêm thông tin về các tham số chi phí, hãy xem Mô hình chi phí.
  
  Lưu ý quan trọng: Chi phí là yếu tố cần thiết để trình tối ưu hoá tìm được tuyến đường phù hợp nhất. Nếu không có các giải pháp này, trình tối ưu hoá sẽ coi tất cả các giải pháp là như nhau.
3. Để đảm bảo trình tối ưu hoá tạo ra một tuyến đường trong giờ hoạt động của xe, hãy xác định startTimeWindows trong phạm vi chấp nhận được để người lái xe bắt đầu vận hành xe và endTimeWindows trong phạm vi chấp nhận được để người lái xe phải quay lại trung tâm chăm sóc ban ngày. Để biết thêm thông tin về khoảng thời gian, hãy xem phần Khoảng thời gian.
Đặt một khung thời gian toàn cầu. Khung thời gian chung là khung thời gian mà xe có thể đến đón và trả trẻ tại cơ sở chăm sóc trẻ em của bạn trong suốt cả ngày. Trong trường hợp này, hãy đặt globalStartTime thành 7:00 và globalEndTime thành 19:00 cho ngày 13 tháng 2 năm 2024. Đây là giờ hoạt động của dịch vụ trông giữ thú cưng.

3. Gửi yêu cầu

Sau đây là một yêu cầu curl đơn giản dựa trên tình huống trông giữ chó và sử dụng phương thức optimizeTours chặn.

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
                }
              }
            },
            "timeWindow": [
              {
                "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
                }
              }
            },
            "timeWindow": [
              {
                "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 phần nội dung yêu cầu của tình huống ví dụ. Bạn có thể lọc nội dung theo thư mục mẹ hoặc theo nội dung tìm kiếm bằng văn bản.

Cha mẹ	Tham số	Loại thuộc tính	Mô tả
`OptimizeToursRequest`	`model`	đối tượng (`ShipmentModel`)	Đây là phần cốt lõi trong yêu cầu của bạn. Đây là một đối tượng duy nhất mà bạn xác định toàn bộ vấn đề, bao gồm tất cả những chú cún bạn cần đón và trả (`shipments`) cũng như xe tải 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 đề mà bạn cần tối ưu hoá.
`OptimizeToursRequest`	`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. 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 trẻ 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 các đố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 các đối tượng, trong đó mỗi đối tượng xác định một chiếc 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 thực hiện việc đón và trả khách. Bạn phải xác định ít nhất một chiếc 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 đối với mọi sự kiện 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à định tuyến. Đối với trường hợp này, hãy đặt thời gian này thành thời gian sớm nhất mà người lái xe có thể lái xe trong ngày, tức 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 đối với mọi sự kiện trong toàn bộ mô hình của bạn. Đối với trường hợp này, hãy đặt thời gian này thành thời điểm dự kiến xe sẽ kết thúc hoạt động, tức 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 lấy hàng có thể có cho lô hàng. Trình tối ưu hoá sẽ chọn cách phù hợp nhất để giải quyết vấn đề của bạn. Đối với trường hợp này, hãy liệt kê các địa điểm đón và khung giờ mà mỗi chủ sở hữu cung cấp cho từng chú cún.
	`deliveries[]`	mảng đối tượng (`VisitRequest`)	Đây là danh sách tất cả các lựa chọn có thể để gửi hàng. Trình tối ưu hoá sẽ chọn cách phù hợp nhất để giải quyết vấn đề của bạn. Đối với trường hợp này, hãy liệt kê vị trí của cơ sở trông giữ chó và khung thời gian mà người lái xe cần quay lại ăn trưa cho mỗi chú chó.
	`label`	chuỗi	Đây là giá trị nhận dạng của 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 này, hãy dùng một chuỗi mô tả như "Chihuahua", "Bernese mountain dog" hoặc tên của chú chó để khớp giải pháp với thông tin đầ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 thông tin 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 này, hãy đặt giá trị này thành vị trí do chủ sở hữu cung cấp cho `pickups` và thành địa chỉ của trung tâm chăm sóc ban ngày cho `deliveries`.
`VisitRequest`	`timeWindows[]`	mảng đối tượng (`TimeWindow`)	Đây là một mảng các đối tượng xác định các ràng buộc về thời gian để lấy hàng hoặc giao hàng. Đối với trường hợp này, hãy dùng thông tin này để xác định khung giờ lấy hàng cho từng chú chó và khung giờ chấp nhận được để đưa chú chó đến trung tâm chăm sóc ban ngày.
`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 lấy hàng hoặc giao hàng làm vị trí bắt đầu. Đối với trường hợp này, vì người lái xe bắt đầu ngày làm việc tại cơ sở trông giữ thú cưng, 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 mà xe sẽ đi, đượ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 lấy hàng hoặc giao hàng làm điểm cuối của tuyến đường. Đối với trường hợp này, vì người lái xe phải kết thúc ngày làm việc tại cơ sở trông giữ thú cưng, 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ữ thú cưng này, hãy dùng điều này để mô hình hoá mức lương theo giờ của người lái xe.
	`startTimeWindows[]`	mảng đối tượng (`TimeWindow`)	Đây là khoảng thời gian chấp nhận được để người lái xe bắt đầu lái xe tải nhỏ đi đó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 để người lái xe hoàn tất việc lái xe và đỗ xe trở lại trung tâm chăm sóc ban ngày cho thú cưng.

Diễn giải câu trả lời