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

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

Khi gọi một phương thức để tính toán ma trận tuyến hoặc 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 cần trả về 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 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.

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ờ đó tránh được 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ề 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.

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.

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.

Những 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 chiếu đến 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 đị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
- 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 để 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 các trường 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ân tuyến đường; 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ân tuyến đường; tức là distanceMeters trong steps trong mẫu trước, thì 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 đế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 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 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:

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ề các trường 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 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 bạn thêm các trường mới và sau đó tự động được đưa vào phản hồ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 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ị loại 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ị là 0. Đây là giá trị mặc định. Vì 0 là giá trị mặc định của distanceMeters, nên giá trị này sẽ bị loại khỏi phản hồi.

Để biết thêm thông tin 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 tuyến đường:
- Đặ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 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.routeToken,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.

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`