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][...]

Lưu ý: Đừng sử dụng dấu cách ở bất kỳ vị trí nào trong danh sách đường dẫn trường.

• Mặt nạ cho trường (field mask) của tuyến đường tính toán
  • REST: Chỉ định các trường của đối tượng Route trong phản hồi cần trả về, có tiền tố là routes., ví dụ: routes.distanceMeters.
  • gRPC: Chỉ định các trường của đối tượng Route trong phản hồi cần trả về.
• 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:

1. 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 *.
   Thận trọng: Mặc dù bạn có thể sử dụng mặt nạ trường (field mask) ký tự đại diện này trong quá trình phát triển, nhưng đừng dùng mặt nạ trường phản hồi ký tự đại diện (*) khi phát hành chính thức. Chi phí có thể cao hơn dự kiến vì có nhiều tính năng nâng cao hơn được yêu cầu qua mặt nạ trường (field mask) này và làm tăng độ trễ phản hồi. Hãy đảm bảo bạn chỉ yêu cầu các trường cần thiết để giảm thiểu chi phí và yêu cầu thời gian phản hồi.
2. 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.
3. 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.

Thận trọng: Mặt nạ trường (trường hợp) đặc biệt là một ký tự đại diện "*", chọn tất cả các trường. Tuy nhiên, mặc dù bạn có thể sử dụng mặt nạ cho trường (field mask) của ký tự đại diện này trong quá trình phát triển, nhưng đừng dùng trong phiên bản chính thức. Chi phí có thể cao hơn dự kiến vì các tính năng nâng cao được yêu cầu thông qua mặt nạ trường (field mask) này và làm tăng độ trễ phản hồi. Hãy đảm bảo bạn chỉ yêu cầu các trường cần thiết để giảm thiểu chi phí và yêu cầu thời gian 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.

Lưu ý: Khi một thông báo phản hồi được phân tích cú pháp và một trường trong thông báo phản hồi chứa giá trị mặc định, thì trường đó có thể bị bỏ qua khỏi phản hồi ngay cả khi bạn đã chỉ định trường đó trong mặt nạ trường phản hồi. Để biết thêm thông tin, hãy xem Hướng dẫn về ngôn ngữ (proto3). Ví dụ: khi bạn tính toán một ma trận tuyến, trường distanceMeters của phản hồi có thể chứa giá trị mặc định là 0. Vì 0 là giá trị mặc định của distanceMeters nên sẽ bị loại khỏi phản hồi.

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:

1. Đặt travel_mode thành DRIVING.
2. Thiết lập routing_preference thành TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL.
3. 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.
4. 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

Lưu ý: Do điều kiện đường sá biến động, nên các tuyến đường được tạo bằng một mã thông báo nhất định có thể khác với tuyến đường dự kiến. Để giảm thiểu sự khác biệt, hãy sử dụng mã thông báo trong vòng vài phút kể từ khi tạo mã thông báo.

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.