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

Khi bạn gọi Thông tin chi tiết về địa điểm (Mới), Tìm kiếm lân cận (Mới) hoặc Tìm kiếm văn bản (Mới), bạn phải chỉ định trường bạn muốn được trả về trong phản hồi. Không có danh sách mặc định trong số các trường được trả về. Nếu bạn bỏ qua danh sách này, các phương thức sẽ trả về lỗi.

Bạn chỉ định danh sách trường bằng cách tạo mặt nạ trường phản hồi. Sau đó, bạn vượt qua 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ố $fields hoặc fields hoặc bằng cách sử dụng tiêu đề HTTP hoặc gRPC X-Goog-FieldMask.

Tạo mặt nạ cho trường là một phương pháp thiết kế hiệu quả để đảm bảo rằng bạn sẽ 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à thanh toán không cần thiết các khoản phí.

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á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 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 đã chỉ định.

Xây dựng đường dẫn trường như sau:

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

Bạn có thể yêu cầu tất cả các trường bằng cách sử dụng mặt nạ trường của *.

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

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

Dưới đây là cách bạn có thể xác định loại mặt nạ trường mà bạn muốn sử dụ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ác trường trong phản hồi và xác định điều gì mà bạn muốn.
  3. Tạo mặt nạ trường bằng cách sử dụng hệ phân cấp trường.

Xác định mặt nạ trường phản hồi cho tính năng Tìm kiếm lân cận (Mới) và Tìm kiếm văn bản (Mới)

Tìm kiếm lân cận (Mới) và Tìm kiếm văn bản (Mới) trả về một mảng các đối tượng Địa điểm trong đó trường places của phản hồi. Đối với các API này, places là cấp cao nhất của trường phản hồi.

Ví dụ: để xem đối tượng phản hồi đầy đủ từ một Tìm kiếm văn bản (Mới):

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: *' \
'https://places.googleapis.com/v1/places:searchText'

Đối tượng phản hồi hoàn chỉnh từ tính năng Tìm kiếm văn bản (Mới) cuộc gọi có dạng:

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Spiced @ Barangaroo",
        "languageCode": "en"
      },      ...
    },
  ...
  ]
}

Do đó, bạn chỉ định mặt nạ trường cho các API này ở dạng:

places[.secondLevelField][.thirdLevelField][...]

Nếu bạn chỉ muốn trả về các trường formattedAddressdisplayName, hãy đặt mặt nạ trường của bạn để:

places.formattedAddress,places.displayName

Việc chỉ định displayName sẽ bao gồm cả trường textlanguage của displayName. Nếu bạn chỉ muốn trường text, hãy đặt mặt nạ trường là:

places.formattedAddress,places.displayName.text

Xác định mặt nạ trường phản hồi cho Chi tiết địa điểm (Mới)

Thông tin chi tiết về địa điểm trả về một đối tượng Địa điểm duy nhất trong biểu mẫu:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "types": [
    "locality",
    "political"
  ],
  "formattedAddress": "Trinidad, CA 95570, USA",
  "displayName": {
    "text": "Trinidad",
    "languageCode": "en"
  }
  ...
}

Do đó, bạn chỉ định mặt nạ trường cho API này bằng cách chỉ định các trường của đối tượng Địa điểm mà bạn muốn trả về:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: formattedAddress,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

lệnh 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ể chuyển biến đó vào yêu cầu.

const (
  fieldMask = "places.formattedAddress,places.displayName"
)

Những điểm cần lưu ý về đường dẫn trường

Chỉ đưa vào các trường mà bạn yêu cầu trong câu trả lời. Chỉ trả lại mà bạn cần:

  • Giảm thời gian xử lý, để kết quả của bạn được trả về với thời gian độ trễ.
  • Đảm bảo hiệu suất độ trễ ổn định nếu API thêm nhiều trường phản hồi hơn trong tương lai và những trường mới đó sẽ cần thêm thời gian tính toán. Nếu bạn 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ể sẽ bị giảm hiệu suất khi tất cả các trường mới tự động được đưa vào câu trả lời của bạn.
  • Kích thước phản hồi nhỏ hơn, đồng nghĩa với việc mạng sẽ tăng lên thông lượ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í đã lập hoá đơn.