Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Chọn các trường cần trả về

Khi yêu cầu một tuyến đường hoặc ma trận tuyến đường, bạn phải sử dụng mặt nạ cho trường để chỉ định thông tin mà phản hồi cần trả về. Không có danh sách mặc định về các trường được trả về. Nếu bạn không chỉ định mặt nạ cho trường, các phương thức sẽ trả về lỗi.

Việc sử dụng mặt nạ cho trường cũng đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết. Điều này giúp giảm độ trễ phản hồi và tránh trả về thông tin mà hệ thống của bạn không cần.

Bạn chỉ định danh sách các trường cần thiết trong mặt nạ cho trường phản hồi. Sau đó, bạn sẽ truyền mặt nạ cho 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.

Để biết thêm thông tin về các tham số URL, hãy xem Tham số hệ thống.

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

Mặt nạ cho trường phản hồi là một danh sách được phân tách bằng dấu phẩy các đường dẫn, 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 và chỉ định đường dẫn cho trường như sau:

Tìm các trường chứa thông tin bạn cần. Để biết thông tin chi tiết, hãy xem bài viết Tài liệu tham khảo về trường.
Xác định đường dẫn cho các trường bạn cần và xây dựng mặt nạ cho 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ạ cho trường mà bạn muốn sử dụng.
Kết hợp mặt nạ cho trường cho tất cả các trường bạn cần, phân tách mặt nạ cho trường bằng dấu phẩy. Ví dụ: để yêu cầu distanceMeters cho chặng tuyến đường, cộng với thời lượng cho từng bước của chặng tuyến đường, hãy nhập cả hai giá trị này, 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ạ cho trường cùng với yêu cầu API. Ví dụ: trong yêu cầu curl, bạn sẽ chỉ định mặt nạ cho trường bằng -H và X-Goog-FieldMask:
```
-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
```

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

Tài liệu tham khảo về 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ạ cho trường, hãy tham khảo tài liệu tham khảo về API Tuyến đường Tính toán tuyến đường hoặc Tính toán ma trận tuyến đường được liên kết trong danh sách sau. Chỉ định các trường theo 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ị tham số như minh hoạ. Ví dụ: đối với routingPreference, bạn phải nhập TRAFFIC_AWARE.

Các tài liệu tham khảo này bao gồm các trường có sẵn. Tuy nhiên, bạn cần tham khảo hệ thống phân cấp của các trường để xác định đường dẫn đầy đủ của mặt nạ cho trường. Để biết thông tin chi tiết về cách lấy hệ thống phân cấp của các trường, hãy xem bài viết Xác định mặt nạ cho trường mà bạn muốn sử dụng.

Tính toán mặt nạ cho trường tuyến đường
- REST: Chỉ định các trường của đối tượng Tuyến đường trong phản hồi cần trả về, được đặt trước bằng routes., ví dụ: routes.distanceMeters.
- gRPC: Chỉ định các trường của Tuyến đường đối tượng trong phản hồi cần trả về.
Tính toán mặt nạ cho trường Ma trận tuyến đường
- 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 RouteMatrixElement đối tượng trong phản hồi cần trả về.

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

Sau đây là cách xác định các trường bạn muốn sử dụng và xây dựng mặt nạ cho 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ạ cho trường *.
Thận trọng: Mặc dù bạn có thể sử dụng mặt nạ cho trường ký tự đại diện này trong quá trình phát triển để xác định các trường bạn cần, nhưng đừng sử dụng mặt nạ này trong quá trình phát hành công khai. Việc yêu cầu tất cả các trường trong quá trình phát hành công khai sẽ làm tăng chi phí và kéo dài thời gian phản hồi. Chi phí của bạn cũng có thể tăng lên một cách bất ngờ khi các tính năng nâng cao khác được thêm vào, vì mặt nạ cho 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 các trường bạn cần để giảm thiểu chi phí và thời gian phản hồi yêu cầu.
Xem hệ thống phân cấp của các trường trong phản hồi cho các trường bạn muốn.
Xây dựng mặt nạ cho trường bằng cách sử dụng hệ thống phân cấp của các trường được hiển thị trong 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ỳ đâ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 đường:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

Nếu bạn chỉ muốn trả về trường distanceMeters cho chặng tuyến đường, tức là distanceMeters cuối cùng trong mẫu trước đó, thì mặt nạ cho 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 tuyến đường, tức là distanceMeters trong steps trong mẫu trước đó, thì mặt nạ cho trường của bạn sẽ như sau:

routes.legs.steps.distanceMeters

Nếu bạn muốn trả về cả hai trường, với kết quả ở trên, thì mặt nạ cho trường của bạn sẽ như sau:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

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

Phần này chứa thêm các ví dụ về cách chỉ định đường dẫn cho trường như một phần của mặt nạ cho 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ạ cho trường để trả về các trường distanceMeters và duration của tuyến đường trong phản hồi. Hãy nhớ đặt tiền tố tên trường bằng routes.

X-Goog-FieldMask: routes.distanceMeters,routes.duration

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

Đối với phương thức REST computeRouteMatrix 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 mỗi tổ hợp điểm gốc 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ạ cho 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 cho trường

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

Giảm thời gian xử lý, nhờ đó, kết quả sẽ đượ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 bạn chọn tất cả các trường ở cấp cao nhất, bạn có thể gặp phải tình trạng 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 phản hồi.
Giúp giảm kích thích thước phản hồi, từ đó 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ý không cần thiết và các khoản phí được tính.

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, trường đó có thể bị bỏ qua trong phản hồi ngay cả khi bạn đã chỉ định trường đó trong mặt nạ cho 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 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). 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 xây dựng mặt nạ cho trường, hãy xem field_mask.proto.

Chọn các trường cần trả về

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

Tài liệu tham khảo về trường

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

Ví dụ về đường dẫn cho mặt nạ cho 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 cho trường

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

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