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

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

Khi đưa ra yêu cầu mã hoá địa lý, bạn có thể sử dụng mặt nạ trường để chỉ định danh sách các trường cần trả về trong phản hồi. Đối với các điểm cuối Mã hoá địa lý cho địa chỉ, Mã hoá địa lý cho vị trí và Mã hoá địa lý cho địa điểm, theo mặc định, tất cả các trường trong đối tượng phản hồi đều được trả về. Đối với điểm cuối Tìm kiếm điểm đến, bạn phải chỉ định một mặt nạ trường trong yêu cầu API.

Sử dụng mặt nạ trường để đảm bảo 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.

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 và không có khoảng trắng, trong đó mỗi đường dẫn chỉ định một trường riêng biệt trong đối tượng phản hồi. Đường dẫn bắt đầu từ trường 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 một trường được chỉ định.

Truyền mặt nạ trường phản hồi đến một yêu cầu 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.

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

Dưới đây là phản hồi hoàn chỉnh từ một yêu cầu chuyển đổi địa chỉ thành toạ độ:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    ...
}

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 phản hồi, theo dạng:

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

Ví dụ: để chỉ trả về trường placeId trong phản hồi, hãy sử dụng mặt nạ trường sau:

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://"geocode.googleapis.com/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Phản hồi hiện tại là:

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE"
    }
  ]
}

Để trả về trường viewport, mặt nạ trường của bạn là:

-H 'X-Goog-FieldMask: results.viewport'

Phản hồi hiện tại là:

{
  "results": [
    {
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

Cách trả lại cả hai:

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

Phản hồi hiện tại là:

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

Mặt nạ trường 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 = "results.placeId,results.viewport"
)

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.
  • Dẫn đến kích thước phản hồi nhỏ hơn, giúp tăng thông lượng mạng.

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