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

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

Khi tạo 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. Mặt nạ trường giúp giảm độ trễ phản hồi bằng cách đảm bảo bạn không yêu cầu dữ liệu không cần thiết.

Đối với các phương thức mã hoá địa lý cơ bản (Mã hoá địa lý một địa chỉ, Mã hoá địa lý một vị trí và Mã hoá địa lý địa điểm), tất cả các trường trong đối tượng phản hồi đều được trả về theo mặc định, không giống như Tìm kiếm điểm đến, nơi bạn phải chỉ định mặt nạ trường. Mặc dù mặt nạ trường không bắt buộc đối với các phương thức cơ bản, nhưng bạn nên sử dụng mặt nạ trường để 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 được phân tách bằng dấu phẩy gồm các đường dẫn không có dấu cách, 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 được 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 đầy đủ từ một yêu cầu mã hoá địa lý chuyển tiếp:

{
  "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, ở dạng:

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

Mặt nạ trường đích đến của quảng cáo Tìm kiếm

Khi gọi SearchDestinations, hãy chỉ định chính xác các thuộc tính của điểm đến mà bạn cần, chẳng hạn như Place Details chính, lối vào, điểm đi theo chỉ dẫn, đường viền toà nhà (displayPolygon) và địa danh:

curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations

Mặt nạ trường mã hoá địa lý cốt lõi

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

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/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA

Câu trả lời hiện 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'

Câu trả lời hiện 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'

Câu trả lời hiện 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ều cần lưu ý về đường dẫn trường

Chỉ đưa vào các trường mà bạn cần trong phản hồi để chỉ trả về các trường 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 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ào và sau đó tự động được đưa vào phản hồi của bạn.
  • Giúp giảm kích thước phản hồi, từ đó 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 nạ trường, hãy xem field_mask.proto.