Trang này được dịch bởi Cloud Translation API.

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ừ tin nhắn 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
```

Để biết thêm ví dụ và thông tin chi tiết, hãy xem các phần sau đây.

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.

Ngược lại, bạn phải nhập thông số values như minh hoạ. Ví dụ: đối với routingPreference, bạn phải nhập TRAFFIC_AWARE.

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ề.
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 *.
Thận trọng: Mặc dù bạn có thể sử dụng mặt nạ trường ký tự đại diện này trong quá trình phát triển để xác định những trường bạn cần, nhưng bạn không nên sử dụng tính năng này trong phiên bản chính thức. Việc yêu cầu tất cả các trường trong phiên bản chính thức sẽ dẫn đến chi phí cao hơn và thời gian phản hồi lâu hơn. Chi phí của bạn cũng có thể tăng đột ngột khi thêm nhiều tính năng nâng cao hơn, vì mặt nạ trường này sẽ tự động bao gồm các tính năng đó. Thay vào đó, bạn chỉ yêu cầu các trường bạn cần để giảm thiểu chi phí và yêu cầu thời gian phản hồi.
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][...]
```
Lưu ý: Không sử dụng dấu cách ở bất cứ đâu trong danh sách đường dẫn trường.

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.

Lưu ý: Khi một tin nhắn phản hồi được phân tích cú pháp và một trường trong tin nhắn phản hồi chứa giá trị mặc định, trường này có thể bị bỏ qua khỏi phản hồi ngay cả khi mà bạn đã chỉ định 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 tính toán ma trận tuyến đường, Trường distanceMeters của phản hồi có thể chứa giá trị bằng 0, giá trị mặc định. Vì 0 là giá trị mặc định của distanceMeters, nên bị bỏ qua trong câu trả lời.

Để 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ành DRIVE.
- Thiết lập routingPreference thành TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL.
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.

Chọn thông tin cần trả lại

Xác định mặt nạ trường phản hồi

Tham chiếu trường

Xác định mặt nạ trường cần sử dụng

Ví dụ về đường dẫn mặt nạ trường

Lệnh gọi REST tới computeRoutes

Lệnh gọi REST tới computeRouteMatrix

lệnh gọi gRPC

Những điểm cần lưu ý về đường dẫn trường

Yêu cầu mã thông báo tuyến đường

Ví dụ về mã thông báo tuyến đường

Lệnh gọi REST tới `computeRoutes`

Lệnh gọi REST tới `computeRouteMatrix`