Tài liệu này mô tả các bước bạn cần thực hiện để bắt đầu sử dụng Route Optimization API.
Điều kiện tiên quyết
Quy trình này hướng dẫn bạn cách thiết lập Tài khoản Google Cloud và dự án trên đám mây của Google Cloud đã bật tính năng thanh toán. Bạn cũng nên nắm rõ cách tính phí khi sử dụng Route Optimization API.
- Xem lại thông tin thanh toán và chi phí sử dụng tại Mức sử dụng và thông tin thanh toán của Route Optimization API.
Xác minh rằng bạn có Tài khoản Google Cloud.
Đăng nhập vào Google Cloud ConsoleXác minh rằng bạn có một dự án trên đám mây của Google Cloud đã bật tính năng thanh toán.
Chuyển đến trang Thanh toán- Chọn dự án của bạn để mở trang Thanh toán.
Trên trang Thanh toán:
- Nếu bạn đã bật tính năng thanh toán cho dự án đã chọn và chỉ có một tài khoản thanh toán, thì trang Thanh toán sẽ mở ra.
- Nếu bạn có nhiều tài khoản thanh toán, hãy chọn Chuyển đến tài khoản thanh toán được liên kết để xem thông tin chi tiết về tài khoản thanh toán liên kết với dự án.
- Nếu tài khoản thanh toán tồn tại nhưng không được liên kết với dự án, thì bạn sẽ được nhắc liên kết tài khoản thanh toán với dự án.
- Nếu không có tài khoản thanh toán nào hoặc bạn muốn tạo một tài khoản thanh toán mới, hãy chọn Quản lý tài khoản thanh toán để tạo một tài khoản thanh toán mới. Để biết thêm thông tin, hãy xem bài viết Tạo tài khoản thanh toán mới trên Cloud theo hình thức tự phục vụ.
Bật API
Trước khi có thể sử dụng Route Optimization API, bạn phải dùng Google Cloud Console hoặc lệnh gcloud để bật API này trong dự án trên đám mây của bạn trên Google Cloud.
Cách bật API:
Giao diện dòng lệnh
Mở trang sản phẩm trong Google Cloud Console:
Bật Route Optimization APINhấp vào nút Bật.
gcloud
gcloud services enable \ --project "PROJECT" \ "routeoptimization.googleapis.com"
Đọc thêm về Google Cloud SDK, cách cài đặt Cloud SDK và các lệnh sau:
Các sản phẩm của Google Maps Platform yêu cầu lệnh gọi API phải có mã thông báo OAuth để ngăn chặn việc sử dụng trái phép.
Tạo mã thông báo OAuth
Route Optimization API hỗ trợ OAuth 2.0 để xác thực. Google hỗ trợ các trường hợp OAuth 2.0 phổ biến, chẳng hạn như các trường hợp cho máy chủ web.
Tài liệu này mô tả cách truyền mã thông báo OAuth đến một lệnh gọi Route Optimization API trong môi trường phát triển của bạn. Để biết thêm thông tin về cách sử dụng OAuth trong môi trường thực tế, hãy xem bài viết Các phương pháp xác thực tại Google.
Bạn có thể gọi trực tiếp các API Google Maps bằng cách gửi yêu cầu API đến máy chủ hoặc có thể sử dụng thư viện ứng dụng để đơn giản hoá mã. Google Maps cung cấp thư viện ứng dụng cho Go, Java, Node.js và Python. Để biết thêm thông tin, hãy xem phần Thư viện ứng dụng Route Optimization API.
Tổng quan về OAuth
Bạn có thể tạo và quản lý mã truy cập bằng OAuth theo một số cách, tuỳ thuộc vào môi trường triển khai của bạn.
Bạn có thể sử dụng OAuth 2.0 cho các hoạt động tương tác giữa máy chủ với máy chủ giữa ứng dụng của bạn và một dịch vụ của Google. Trong trường hợp này, bạn sử dụng một tài khoản dịch vụ được liên kết với ứng dụng của bạn thay vì một người dùng cá nhân. Bạn có thể đưa ra yêu cầu API bằng tài khoản dịch vụ mà không cần người dùng trực tiếp tham gia. Để biết thêm thông tin về các phương thức xác thực, hãy xem bài viết Các phương thức xác thực tại Google.
Ngoài ra, bạn có thể tích hợp Route Optimization API vào một ứng dụng di động Android hoặc iOS. Để biết thêm thông tin về cách sử dụng OAuth và quản lý mã truy cập cho các môi trường triển khai, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập vào các API của Google.
Phạm vi OAuth
Để sử dụng OAuth với Route Optimization API, bạn phải chỉ định phạm vi sau cho mã thông báo OAuth:
https://www.googleapis.com/auth/cloud-platform
Định cấu hình vai trò
Tài liệu này cung cấp thông tin về các vai trò và quyền trong hệ thống Quản lý danh tính và quyền truy cập (IAM) cho tính năng Tối ưu hoá tuyến đường. IAM cho phép bạn cấp quyền truy cập chi tiết vào các tài nguyên cụ thể của tính năng Tối ưu hoá tuyến đường và giúp ngăn chặn quyền truy cập vào các tài nguyên khác. IAM cho phép bạn áp dụng nguyên tắc bảo mật về đặc quyền tối thiểu, trong đó quy định rằng không ai được có nhiều quyền hơn mức họ thực sự cần.
Khi một chủ thể (người dùng, nhóm hoặc tài khoản dịch vụ) gọi một Cloud APIs, chủ thể đó phải có các quyền IAM thích hợp để sử dụng tài nguyên. Để cấp cho một đối tượng chính các quyền cần thiết, bạn cần cấp một vai trò IAM cho đối tượng chính đó.
Để làm quen với việc quản lý quyền truy cập trong Google Cloud nói chung, hãy xem phần Tổng quan về IAM.
Các vai trò IAM được xác định trước để cho phép các đối tượng chính truy cập vào tính năng Tối ưu hoá tuyến đường là:
-
Route Optimization Editor (roles/routeoptimization.editor): cấp cho người dùng hoặc tài khoản dịch vụ quyền đọc và ghi đối với các tài nguyên Tối ưu hoá tuyến đường trong dự án. Điều này bao gồm khả năng gọiOptimizeToursvàBatchOptimizeTours, cũng như truy xuất các thao tác chạy trong thời gian dài bằngGetOperation. -
Route Optimization Viewer (roles/routeoptimization.viewer): cấp quyền chỉ có thể đọc đối với tài nguyên Tối ưu hoá tuyến đường trong dự án. Vai trò này cho phép gọiOptimizeToursvà truy cập vào Hoạt động chạy trong thời gian dài bằngGetOperation.
gcloud projects add-iam-policy-binding PROJECT \ --member user:someone@example.com \ --role roles/routeoptimization.editor
Để biết thêm thông tin, hãy xem bài viết Cấp vai trò IAM bằng Google Cloud Console.
Ví dụ: Thử các lệnh gọi API REST trong môi trường phát triển cục bộ
Nếu bạn không có môi trường tạo mã thông báo và muốn thử dùng Route Optimization API bằng mã thông báo OAuth, hãy làm theo quy trình trong phần này.
Ví dụ này mô tả cách sử dụng mã thông báo OAuth do Thông tin xác thực mặc định của ứng dụng (ADC) cung cấp để thực hiện lệnh gọi. Để biết thêm thông tin về cách sử dụng ADC để gọi API của Google bằng thư viện ứng dụng, hãy xem bài viết Xác thực bằng thư viện ứng dụng.
Chỉ sử dụng quy trình REST sau đây cho mục đích phát triển hoặc thử nghiệm, không dùng cho môi trường thực tế.
Điều kiện tiên quyết
Trước khi bạn gửi yêu cầu REST bằng ADC, hãy sử dụng CLI gcloud để cung cấp thông tin xác thực cho ADC:
Cài đặt và khởi chạy CLI
gcloud. Để biết thêm thông tin, hãy xem bài viết Cài đặt gcloud CLI.Xác thực bằng CLI
gcloud:gcloud auth application-default login
Hoàn tất quy trình đăng nhập để lưu thông tin đăng nhập vào tệp thông tin đăng nhập cục bộ mà ADC sử dụng.
Để biết thêm thông tin, hãy xem bài viết Thiết lập ADC cho môi trường phát triển cục bộ.
Tạo yêu cầu REST
Trong ví dụ này, bạn truyền hai tiêu đề của yêu cầu:
Truyền mã thông báo OAuth trong tiêu đề
Authorizationbằng cách sử dụng lệnh sau để tạo mã thông báo:gcloud auth application-default print-access-tokenMã thông báo được trả về có phạm vi là
https://www.googleapis.com/auth/cloud-platform.Truyền mã nhận dạng hoặc tên của dự án trên đám mây Google Cloud đã bật tính năng thanh toán trong tiêu đề
X-Goog-User-Project.
Để gọi Route Optimization API bằng mã thông báo OAuth, hãy hoàn tất các bước sau:
Trong mã mẫu sau, hãy thay thế PROJECT_NUMBER_OR_ID bằng số hoặc mã dự án trên đám mây của bạn trên Google Cloud:
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-binary @- << EOM { "model": { "shipments": [ { "pickups": [ { "arrivalLocation": { "latitude": 37.73881799999999, "longitude": -122.4161 } } ], "deliveries": [ { "arrivalLocation": { "latitude": 37.79581, "longitude": -122.4218856 } } ] } ], "vehicles": [ { "startLocation": { "latitude": 37.73881799999999, "longitude": -122.4161 }, "endLocation": { "latitude": 37.73881799999999, "longitude": -122.4161 } } ], "globalStartTime": "2023-01-13T16:00:00-08:00", "globalEndTime": "2023-01-14T16:00:00-08:00" } } EOMĐể sao chép lệnh
curl, hãy nhấp vào Sao chép trong mã mẫu.Dán lệnh vào cửa sổ dòng lệnh rồi chạy lệnh đó.
Phản hồi là một đối tượng JSON:
{
"routes": [
{
"vehicleStartTime": "2023-01-14T00:00:00Z",
"vehicleEndTime": "2023-01-14T00:39:22Z",
"visits": [
{
"isPickup": true,
"startTime": "2023-01-14T00:00:00Z",
"detour": "0s"
},
{
"startTime": "2023-01-14T00:19:53Z",
"detour": "0s"
}
],
"transitions": [
{
"travelDuration": "0s",
"waitDuration": "0s",
"totalDuration": "0s",
"startTime": "2023-01-14T00:00:00Z"
},
{
"travelDuration": "1193s",
"travelDistanceMeters": 9007,
"waitDuration": "0s",
"totalDuration": "1193s",
"startTime": "2023-01-14T00:00:00Z"
},
{
"travelDuration": "1169s",
"travelDistanceMeters": 9546,
"waitDuration": "0s",
"totalDuration": "1169s",
"startTime": "2023-01-14T00:19:53Z"
}
],
"metrics": {
"performedShipmentCount": 1,
"travelDuration": "2362s",
"waitDuration": "0s",
"delayDuration": "0s",
"breakDuration": "0s",
"visitDuration": "0s",
"totalDuration": "2362s",
"travelDistanceMeters": 18553
}
}
],
"metrics": {
"aggregatedRouteMetrics": {
"performedShipmentCount": 1,
"travelDuration": "2362s",
"waitDuration": "0s",
"delayDuration": "0s",
"breakDuration": "0s",
"visitDuration": "0s",
"totalDuration": "2362s",
"travelDistanceMeters": 18553
},
"usedVehicleCount": 1,
"earliestVehicleStartTime": "2023-01-14T00:00:00Z",
"latestVehicleEndTime": "2023-01-14T00:39:22Z"
}
}
Khắc phục sự cố
Nếu yêu cầu của bạn trả về một thông báo lỗi cho biết API này không hỗ trợ thông tin xác thực của người dùng cuối, hãy xem phần Khắc phục sự cố khi thiết lập ADC.