Chọn thông tin cần trả lại
Khi gọi một phương thức để tính toán tuyến hoặc tính toán ma trận tuyến, bạn phải chỉ định thông tin mình muốn bằng cách chỉ định trường bạn muốn trả về trong phản hồi. Không có danh sách mặc định chứa 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 sẽ truyền 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 hay gRPC X-Goog-FieldMask
.
Che giấu trường là một phương pháp thiết kế hiệu quả để đảm bảo bạn không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý không cần thiết và các khoản phí phát sinh.
Để biết thêm thông tin về tham số URL, hãy xem phần Tham số hệ thống.
Xác định mặt nạ cho trường (field mask) của phản hồi
Mặt nạ cho trường (field mask) của 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 chỉ định một trường duy nhất trong thông báo phản hồi. Đường dẫn này 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.
Xây dựng một đường dẫn trường như sau:
topLevelField[.secondLevelField][.thirdLevelField][...]
- Mặt nạ cho trường (field mask) của tuyến đường tính toán
- Tính toán mặt nạ trường ma trận tuyến đường
- REST: Chỉ định các trường của Nội dung phản hồi cần trả về.
- gRPC: Chỉ định các trường của đối tượng RouteMatrixElement trong phản hồi cần trả về.
Để biết thêm thông tin về cách tạo mặt nạ cho trường (field mask), hãy xem field_mask.proto.
Xác định loại mặt nạ cho trường (field mask) cần sử dụng
Sau đây là cách xác định mặt nạ cho trường (field mask) mà bạn muốn sử dụng:
- Yêu cầu tất cả các trường bằng cách sử dụng mặt nạ trường (field mask) của
*
. - Xem hệ phân cấp của các trường trong phản hồi rồi xác định những trường bạn muốn.
- Tạo mặt nạ trường bằng hệ phân cấp trường.
Ví dụ: đối với nội dung phản hồi một phần từ một tuyến đường chuyển tuyến:
"routes": [ { "legs": [ { "distanceMeters": 12886, } ... ]}]
Nếu bạn chỉ muốn trả về trường distanceMeters
, mặt nạ cho trường (field mask) của bạn sẽ là:
routes.legs.distanceMeters
Một ví dụ khác: Để trả về mọi nội dung trong legs
trong phản hồi, mặt nạ trường của bạn là:
routes.legs
Chỉ định một đường dẫn trường
Phần này đưa ra các ví dụ về cách chỉ định một đường dẫn trường trong mặt nạ trường phản hồi.
Lệnh gọi REST đến computeRoutes
Trong ví dụ đầu tiên, bạn sử dụng lệnh gọi REST đến phương thức computeRoutes
để tính toán tuyến đường. Ở ví dụ này, trong tiêu đề, bạn chỉ định mặt nạ trường (field mask) để trả về các trường Route.distanceMeters
và Route.duration
trong phản hồi. Hãy nhớ thêm tiền tố routes
vào tên trường.
-H X-Goog-FieldMask: routes.distanceMeters,routes.duration
Lệnh gọi REST đến computeRouteMatrix
Đối với phương thức REST computeRouteMatrix
dùng để tính toán ma trận tuyến, 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:
-H X-Goog-FieldMask: originIndex,destinationIndex,duration
cuộc 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ể truyền biến đó vào yêu cầu.
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
Những điểm cần cân nhắc về đường dẫn trường
Chỉ thêm những trường mà bạn yêu cầu trong câu trả lời. Chỉ trả về các trường mà bạn cần:
- Giảm thời gian xử lý để kết quả trả về với độ trễ thấp hơn.
- Đảm bảo hiệu suất độ trễ ổn định nếu API bổ sung thêm trường phản hồi trong tương lai và các trường mới đó sẽ cần thêm thời gian tính toán. Nếu chọn tất cả các trường hoặc chọn tất cả các trường ở cấp cao nhất, thì bạn có thể thấy hiệu suất giảm khi tất cả các trường mới được tự động đưa vào phản hồi của bạn.
- Dẫn đến kích thước phản hồi nhỏ hơn, từ đó dẫn đến thông lượng mạng cao hơn.
- Đảm bảo bạn không yêu cầu dữ liệu không cần thiết, nhằm tránh thời gian xử lý và các khoản phí phát sinh không cần thiết.
Yêu cầu mã thông báo tuyến đường
Để yêu cầu API Tuyến đường trả về mã thông báo tuyến cho các tuyến đã tạo, hãy làm theo các yêu cầu về việc trả về mã thông báo tuyến đường, sau đó sử dụng mặt nạ trường routes.route_token
để yêu cầu mã thông báo:
- Đặt
travel_mode
thànhDRIVING
. - Thiết lập
routing_preference
thànhTRAFFIC_AWARE
hoặcTRAFFIC_AWARE_OPTIMAL
. - Kiểm tra để đảm bảo không có điểm tham chiếu nào trong tuyến đường của bạn là điểm tham chiếu
via
. - Chỉ định mặt nạ cho trường của mã thông báo tuyến đường:
-H X-Goog-FieldMask: routes.route_token
Bạn có thể sử dụng tuyến đường theo kế hoạch trong SDK điều hướng. Để biết thêm thông tin chi tiết, hãy xem phần 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 định tuyến
Dưới đây là ví dụ về nội dung yêu cầu cURL cho một tuyến một điểm đến, một điểm đến, sử dụng mặt nạ trường để yêu cầu mã thông báo tuyến đường, cùng với thời lượng tuyến đường, khoảng cách và hình nhiều tuyến:
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.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
Để biết thêm thông tin chi tiết, hãy xem Tài liệu tham khảo về API Tính toán tuyến đường.