Chọn thông tin cần trả lại
Khi bạn gọi một phương thức để tính toán tuyến đường hoặc ma trận tuyến đường, bạn phải chỉ định thông tin mình muốn bằng cách liệt kê các trường trở lại trong phản hồi. Không có danh sách mặc định các trường được trả về. Nếu bạn bỏ qua danh sách này, các phương thức sẽ trả về lỗi.
Bạn chỉ định danh sách trường bằng cách tạo mặt nạ trường phản hồi. Sau đó, bạn vượt qua
mặt nạ trường phản hồi cho một trong hai phương thức bằng cách sử dụng tham số URL $fields
hoặc
fields
hoặc bằng cách sử dụng tiêu đề HTTP hoặc gRPC X-Goog-FieldMask
.
Sử dụng mặt nạ trường là một phương pháp thiết kế hiệu quả để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, nhờ đó giúp tránh thời gian xử lý không cần thiết và các khoản phí phải trả.
Để biết thêm thông tin về các tham số URL, hãy xem System Parameters (Tham số hệ thống).
Xác định mặt nạ trường phản hồi
Mặt nạ trường phản hồi là một danh sách các đường dẫn được phân tách bằng dấu phẩy, trong đó mỗi đường dẫn path chỉ định một trường duy nhất trong thông báo phản hồi. Đường dẫn bắt đầu từ thông báo phản hồi cấp cao nhất và sử dụng đường dẫn được phân tách bằng dấu chấm đến trường được chỉ định.
Tạo và chỉ định một đường dẫn trường như sau:
- Tìm các trường chứa thông tin bạn cần từ Routes API (API Tuyến đường). Để biết thông tin chi tiết, hãy xem phần Tham chiếu trường.
- Xác định đường dẫn cho các trường bạn cần và tạo mặt nạ trường cho các trường đó: Để biết thông tin chi tiết, hãy xem bài viết Xác định mặt nạ trường mà bạn muốn sử dụng.
Kết hợp các mặt nạ trường cho tất cả các trường bạn cần, phân tách các mặt nạ trường bằng dấu phẩy. Ví dụ: để yêu cầu
distanceMeters
cho chặng của tuyến đường, cùng với thời gian của mỗi chặng của tuyến đường, hãy nhập cả hai (phân tách bằng dấu phẩy) và không có dấu cách:routes.legs.distanceMeters,routes.legs.steps.duration
Gửi mặt nạ trường cùng với yêu cầu API của bạn. Ví dụ: trong một yêu cầu cURL, bạn sẽ chỉ định mặt nạ trường bằng
-H
vàX-Goog-FieldMask
:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Tham chiếu trường
Để xem các trường mà bạn có thể yêu cầu trong phản hồi thông qua mặt nạ trường, hãy tham khảo tài liệu tham khảo API tuyến đường được liên kết trong danh sách sau. Chỉ định các trường theo quy ước viết hoa kiểu lạc đà như trong tài liệu tham khảo. Ví dụ: routePreference
.
Các thông tin tham chiếu này bao gồm các trường có sẵn; tuy nhiên, bạn cần tham khảo hệ phân cấp các trường để xác định đường dẫn mặt nạ trường đầy đủ. Để biết thông tin chi tiết về cách lấy hệ phân cấp các trường, hãy xem phần Xác định mặt nạ trường mà bạn muốn sử dụng.
- Tính toán mặt nạ trường tuyến đường
- REST: Chỉ định các trường của
Đối tượng Định tuyến trong
phản hồi để trả về, có tiền tố là
routes.
, ví dụ:routes.distanceMeters
. - gRPC: Chỉ định các trường của Đối tượng Định tuyến trong để trả về.
- REST: Chỉ định các trường của
Đối tượng Định tuyến trong
phản hồi để trả về, có tiền tố là
- Tính toán mặt nạ trường ma trận định tuyến
- REST: Chỉ định các trường của Nội dung phản hồi quay lại.
- gRPC: Chỉ định các trường của RouteMatrixElement trong phản hồi để trả về.
Xác định mặt nạ trường cần sử dụng
Dưới đây là cách bạn có thể xác định các trường mà bạn muốn sử dụng và tạo mặt nạ trường cho các trường đó:
- Yêu cầu tất cả các trường bằng cách sử dụng mặt nạ trường của
*
. - Xem hệ phân cấp của các trường trong phản hồi cho thuộc tính mà bạn muốn.
Tạo mặt nạ trường bằng cách sử dụng hệ thống phân cấp các trường hiển thị ở bước trước theo định dạng sau:
topLevelField[.secondLevelField][.thirdLevelField][...]
Ví dụ: đối với phản hồi một phần này từ một tuyến:
"routes": [ { "legs": [ { "steps": [ {"distanceMeters": 119}, {"distanceMeters": 41} ] } ], "distanceMeters": 160 } ]
Nếu bạn chỉ muốn trả về trường distanceMeters
cho chặng đi; tức là distanceMeters
cuối cùng trong mẫu trước đó, mặt nạ trường của bạn như sau:
routes.legs.distanceMeters
Thay vào đó, nếu bạn muốn trả về trường distanceMeters
cho mỗi bước của chặng đi; tức là distanceMeters
trong steps
trong mẫu trước, mặt nạ trường của bạn như sau:
routes.legs.steps.distanceMeters
Nếu bạn muốn trả về cả hai, với kết quả ở trên, mặt nạ trường của bạn như sau:
routes.legs.distanceMeters,routes.legs.steps.distanceMeters
Ví dụ về đường dẫn mặt nạ trường
Phần này có thêm ví dụ về cách chỉ định một đường dẫn trường trong mặt nạ trường phản hồi trong các lệnh gọi REST và gRPC.
Lệnh gọi REST tới computeRoutes
Trong ví dụ đầu tiên, bạn sử dụng lệnh gọi REST cho
Phương thức computeRoutes
để tính toán
một tuyến đường. Ở ví dụ này, trong tiêu đề, bạn chỉ định mặt nạ trường để trả về các trường distanceMeters
và duration
về tuyến trong phản hồi. Hãy nhớ thêm tiền tố routes
cho tên trường.
X-Goog-FieldMask: routes.distanceMeters,routes.duration
Lệnh gọi REST tới computeRouteMatrix
Đối với Kiến trúc chuyển trạng thái đại diện (REST) computeRouteMatrix
phương thức dùng để tính toán ma trận tuyến đường, trong tiêu đề, hãy chỉ định để trả về
originIndex
, destinationIndex
và duration
cho từng tổ hợp nguồn gốc
và đích đến:
X-Goog-FieldMask: originIndex,destinationIndex,duration
lệnh gọi gRPC
Đối với gRPC, hãy đặt một biến chứa mặt nạ trường phản hồi. Sau đó, bạn có thể chuyển biến đó vào yêu cầu.
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
Những điểm cần lưu ý về đường dẫn trường
Chỉ bao gồm các trường mà bạn yêu cầu trong phản hồi để chỉ trả về mà bạn cần:
- Giảm thời gian xử lý để kết quả được trả về với độ trễ thấp hơn.
- Đảm bảo hiệu suất độ trễ ổn định. Nếu bạn chọn tất cả các trường, hoặc nếu chọn tất cả các trường ở cấp cao nhất, bạn có thể suy giảm hiệu suất khi các trường mới được thêm vào và sau đó tự động được đưa vào câu trả lời của bạn.
- Kích thước phản hồi nhỏ hơn, đồng nghĩa với việc thông lượng mạng sẽ cao hơn.
- Đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, nhờ đó tránh được thời gian xử lý và các khoản phí được lập hoá đơn không cần thiết.
Để biết thêm chi tiết về cách tạo mặt nạ trường, hãy xem field_mask.proto.
Yêu cầu mã thông báo tuyến đường
Để yêu cầu Routes API trả về mã thông báo tuyến đường cho các tuyến đường đã tạo, hãy làm theo các bước sau:
- Thiết lập các tham số sau đây để trả về mã thông báo định tuyến:
- Đặt
travelMode
thànhDRIVE
. - Thiết lập
routingPreference
thànhTRAFFIC_AWARE
hoặcTRAFFIC_AWARE_OPTIMAL
.
- Đặt
- Kiểm tra để đảm bảo không có điểm tham chiếu tuyến đường nào của bạn là
via
điểm tham chiếu. - Chỉ định mặt nạ trường
routes.routeToken
để trả về một mã thông báo tuyến đường:X-Goog-FieldMask: routes.routeToken
Bạn có thể sử dụng mã thông báo tuyến đường cho tuyến đường đã lên kế hoạch trong SDK điều hướng. Để biết thêm thông tin, hãy xem Lên kế hoạch tuyến đường (Android) hoặc Lên kế hoạch tuyến đường (iOS).
Ví dụ về mã thông báo tuyến đường
Dưới đây là ví dụ về nội dung của yêu cầu cURL cho một điểm đến duy nhất tuyến đường, sử dụng mặt nạ trường để yêu cầu mã thông báo tuyến đường cùng với tuyến đường thời lượng, khoảng cách và tuyến đường hình nhiều đường:
curl -X POST -d {"origin":{ "location": { "latLng":{ "latitude": -37.8167, "longitude": 144.9619 } } }, "destination":{ "location": { "latLng":{ "latitude":-37.8155, "longitude": 144.9663 } } }, "routingPreference":"TRAFFIC_AWARE", "travelMode":"DRIVE" } -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
Để biết thêm chi tiết, hãy xem Tài liệu tham khảo về API tuyến đường tính toán.