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ạ trường để chỉ định thông tin mà phản hồi sẽ 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ạ trường, các phương thức sẽ trả về lỗi.

Việc sử dụng mặt nạ 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, từ đó 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 mặt nạ trường phản hồi. Sau đó, bạn sẽ truyền 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.

Để 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 đườ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 riêng biệ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:

  1. 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 phần Tài liệu tham khảo về trường.
  2. 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 mà bạn muốn sử dụng.

  3. 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 đoạn đường, cộng với thời lượng cho từng bước của đoạn đườ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

  4. 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 một phản hồi thông qua mặt nạ trường, hãy tham khảo phần tham chiếu Compute Routes (Tính toán tuyến đường) hoặc Compute Route Matrix (Tính toán ma trận tuyến đường) của Routes API được liên kết trong danh sách sau. Chỉ định các trường theo quy tắc lạc đà như trong tài liệu tham khảo. Ví dụ: routePreference.

Các thông tin tham khảo này bao gồm những 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ạ 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 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ạ cho trường tuyến đường
    • REST: Chỉ định các trường của đối tượng Route trong phản hồi cần 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 trong phản hồi cần trả về.
  • Tính toán mặt nạ trường Ma trận tuyến đường

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

Sau đây là cách xác định những trường bạn muốn sử dụng và tạo mặt nạ trường cho các trường đó:

  1. Yêu cầu tất cả các trường bằng cách sử dụng mặt nạ trường *.
  2. 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.

  3. 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 xuất hiện ở bước trước, theo định dạng sau:

    topLevelField[.secondLevelField][.thirdLevelField][...]

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 đườ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 đoạn đường; tức là distanceMeters trong steps ở 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, thì 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ạ cho trường

Phần này chứa thêm các ví dụ về cách chỉ định đường dẫn trường trong thành phần mặt nạ trường phản hồi trong các lệnh gọi REST và gRPC.

Cuộc 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 các mặt nạ trường để trả về các trường distanceMeters và duration của tuyến đường trong phản hồi. Nhớ thêm tiền tố routes vào tên trường.

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

Cuộc 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 xuất phát và điểm đến:

X-Goog-FieldMask: originIndex,destinationIndex,duration

Cuộc 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 đó 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ỉ thêm những trường bạn cần vào phản hồi để chỉ trả về những trường 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ể 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à sau đó tự động được đưa vào phản hồi của bạn.
  • Giảm kích thước phản hồi, nhờ đó 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.

Để biết thêm thông tin chi tiết về cách tạo một mặt nạ trường, hãy xem field_mask.proto.