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 đường hoặc tính toán ma trận tuyến đường, bạn phải chỉ định thông tin mình muốn bằng cách chỉ định những trường mà bạn muốn được trả về trong phản hồi. Không có danh sách mặc định nào gồm các trường được trả về. Nếu bạn bỏ qua danh sách này, thì 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ẽ chuyển mặt nạ trường phản hồi sang một trong hai phương thức bằng cách sử dụng tham số URL $fields hoặc fields, hoặc dùng tiêu đề X-Goog-FieldMask HTTP hoặc gRPC.

Che giấu 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, giúp tránh thời gian xử lý không cần thiết và phát sinh các khoản phí phát sinh.

Để biết thêm thông tin về tham số URL, hãy xem bài viết 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 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.

Xây dựng đường dẫn trường như sau:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Tính toán mặt nạ trường định tuyến
    • REST: Chỉ định các trường của đối tượng Route (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 Route (Tuyến) trong phản hồi để trả về.
  • Tính toán mặt nạ trường ma trận định tuyến

Để biết thêm thông tin về cách tạo mặt nạ trường, hãy xem field_mask.proto.

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 loại mặt nạ trường 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 của *.
  2. Xem hệ phân cấp các trường trong phản hồi rồi xác định những trường mà bạn muốn.
  3. Tạo mặt nạ trường bằng cách sử dụng hệ phân cấp trường.

Ví dụ: đối với 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ạ trường của bạn sẽ:

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 sẽ là:

routes.legs

Chỉ định đường dẫn trường

Phần này có 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 tới 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 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 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 tới computeRouteMatrix

Đối với phương thức computeRouteMatrix REST 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 điểm gốc và đích đến:

-H 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ỉ thêm các trường mà bạn yêu cầu vào 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ả của bạn được trả về với độ trễ thấp hơn.
  • Đảm bảo hiệu suất độ trễ ổn định nếu API thêm nhiều trường phản hồi hơn trong tương lai và những 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ì hiệu suất có thể giảm khi tất cả các trường mới đều 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, từ đó dẫn đến thông lượng mạng 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, giúp tránh mất thời gian xử lý không cần thiết và các khoản phí phải trả.

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 cho các tuyến đã tạo, hãy làm theo các yêu cầu đối với việc trả về một mã thông báo tuyến, 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 tuyến đường nào của bạn là via điểm tham chiếu.
  4. Chỉ định mặt nạ trường 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 đã lên 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 tuyến đường

Dưới đây là ví dụ về nội dung yêu cầu cURL cho một tuyến đường đi một điểm gốc, một đích đế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, khoảng cách và 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.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

Để biết thêm thông tin, hãy xem Tài liệu tham khảo về API tuyến đường tính toán.