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, thì 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á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 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.

Xây dựng và chỉ định đường dẫn cho 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à 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 phần Xác định mặt nạ cho trường mà bạn muốn sử dụng.

  3. 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, 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ạ 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.

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ệ 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ệ phân cấp của các trường, hãy xem phần 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ó tiền tố là 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

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

Sau đây là cách bạn có thể 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 đó:

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

  3. Xây dựng mặt nạ cho trường bằng cách sử dụng hệ phân cấp của các trường được trình bày ở 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 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, 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 trong 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 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ớ thêm tiền tố routes vào 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 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 đến computeRoutes

Đối với phương thức gRPC computeRoutes dùng để tính toán tuyến đường, hãy đặt một biến chứa mặt nạ cho trường phản hồi để trả về các trường distanceMeters, duration và đường nhiều đoạn được mã hoá của tuyến đường trong 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"
)

Lệnh gọi gRPC đến computeRouteMatrix

Đối với phương thức gRPC computeRouteMatrix dùng để tính toán ma trận tuyến đường, hãy đặt một biến chứa mặt nạ cho trường phản hồi để chỉ định trả về originIndex, destinationIndex và duration cho mỗi tổ hợp điểm gốc và điểm đến. Sau đó, bạn có thể truyền biến đó đến yêu cầu:

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

Lưu ý về đường dẫn cho trường

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

  • Giảm thời gian xử lý, vì vậy, 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, thì 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 của bạn.
  • Tạo ra phản hồi có kích thước 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.

Để 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.