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

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

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, từ đó 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ề 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 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ừ 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 một đường dẫn trường như sau:

Tìm các trường chứa thông tin bạn cần trong Routes API. Để 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 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. 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 ví dụ và thông tin chi tiết hơn, 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 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 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ệ thống 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 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 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 Phần 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ề.

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 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ẽ 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 độ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 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 ý: Đừ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 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 đườ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 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. 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ớ đặt 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 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ể truyền biến đó đến 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ỉ 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ý, 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 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ế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 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 bạn tính toán một ma trận tuyến đường, trường distanceMeters của phản hồi có thể chứa giá trị 0, giá trị mặc định của trường này. 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 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 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ố bắt buộc sau để trả về mã thông báo tuyến:
- Đặt travelMode thành DRIVE.
- Đặt 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ã thông báo tuyến:
```
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 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ả 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 tới computeRoutes

Lệnh gọi REST tới 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 đườ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`