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

Chọn thông tin cần trả về

Khi 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 bạn muốn bằng cách liệt kê các trường sẽ 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 truyền mặt nạ trường phản hồi đến 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.

Việc sử dụng mặt nạ trường là một phương pháp thiết kế hay để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, từ đó giúp tránh thời gian xử lý và các khoản phí không cần thiết.

Để biết thêm thông tin về các tham số URL, hãy xem phần 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 phân tách bằng dấu chấm đến trường đã chỉ định.

Tạo và chỉ định đườ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 phần Xác định mặt nạ trường 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 đường, cộng với thời lượng cho mỗi bước chặng đường, hãy nhập cả hai, phân tách bằng dấu phẩy, 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 về API Tuyến được liên kết trong danh sách sau. Chỉ định các trường theo kiểu camel case như trong tài liệu tham khảo. Ví dụ: routePreference.

Ngược lại, bạn phải nhập giá trị của tham số như minh hoạ. Ví dụ: đối với routingPreference, bạn phải nhập TRAFFIC_AWARE.

Các tệp 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ủa 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ủa 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ố 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 cần trả về.
Tính toán mặt nạ trường ma trận 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 *.
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 đừng sử dụng mặt nạ 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 môi trường phát hành công khai sẽ làm tăng chi phí và thời gian phản hồi. Chi phí của bạn cũng có thể tăng lên ngoài dự kiến khi thêm các 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 đó, hãy chỉ yêu cầu những trường mà bạn cần để giảm thiểu chi phí và thời gian phản hồi yêu cầu.
Xem hệ phân cấp của các trường trong phản hồi cho các trường bạn muốn.
Tạo mặt nạ trường bằng cách sử dụng hệ phân cấp của các trường hiển thị ở bước trước, theo định dạng 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.

Ví dụ: đối với một phần phản hồi 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 đường; tức là distanceMeters cuối cùng trong mẫu trước, thì mặt nạ trường của bạn sẽ như sau:

routes.legs.distanceMeters

Nếu bạn muốn trả về trường distanceMeters cho từng bước của chặng đường; tức là distanceMeters trong steps trong mẫu trước, thì mặt nạ trường của bạn sẽ 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 sẽ 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 đế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 một tuyến đường. Trong ví dụ này, trong tiêu đề, bạn chỉ định mặt nạ trường để trả về các trường tuyến distanceMeters và duration 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 đến `computeRouteMatrix`

Đối với phương thức computeRouteMatrix của 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 mỗi tổ hợp điểm xuất phát và điểm đế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ều cần cân nhắc về đường dẫn trường

Chỉ đưa vào phản hồi những trường mà bạn yêu cầu để chỉ trả về những trường mà bạn cần:

Giảm thời gian xử lý, nhờ đó 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 nếu chọn tất cả các trường ở cấp cao nhất, bạn có thể thấy hiệu suất giảm khi các trường mới được thêm vào và sau đó tự động được đưa vào phản hồi của bạn.
Kết quả là kích thước phản hồi nhỏ hơn, giúp tăng thông lượng mạng.
Đả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ý và các khoản phí 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ị bỏ qua trong 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

Để 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 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.
- Đặt routingPreference thành TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL.
Kiểm tra để đảm bảo rằng không có điểm trung gian nào trên tuyến đường là điểm trung gian via.
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 bài viết Lên kế hoạch cho một tuyến đường (Android) hoặc Lên kế hoạch cho một 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 có một điểm xuất phát và 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à đường đa tuyến của tuyến đườ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ả về

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 đến computeRoutes

Lệnh gọi REST đến computeRouteMatrix

Lệnh gọi gRPC

Những điều cần cân nhắc về đường dẫn trường

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

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

Lệnh gọi REST đến `computeRoutes`

Lệnh gọi REST đến `computeRouteMatrix`