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

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

Giới thiệu

Khi gọi phương thức Place Details (New) (Thông tin chi tiết về địa điểm (Mới)), Nearby Search (New) (Tìm kiếm lân cận (Mới)), hoặc Text Search (New) (Tìm kiếm văn bản (Mới)), bạn phải chỉ định những trường mà bạn muốn trả về trong phản hồi. Không có danh sách mặc định gồm 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 có thể tìm thấy danh sách đầy đủ các trường dữ liệu được hỗ trợ và SKU tương ứng trong Trường dữ liệu về địa điểm (Mới). Để biết thông tin về các trường dành riêng cho từng API, hãy xem những bài viết sau:

Tham số FieldMask của Place Details (New) (Thông tin chi tiết về địa điểm (Mới))
Tham số FieldMask của Nearby Search (New) (Tìm kiếm lân cận (Mới))
Tham số FieldMask của Tìm kiếm văn bản (Mớ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 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ố $fields hoặc fields, hoặc bằng cách sử dụng tiêu đề HTTP hoặc gRPC X-Goog-FieldMask.

Việc che giấu trường là một phương pháp thiết kế hay để đả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 tránh thời gian xử lý và phí thanh toán không cần thiết.

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, trong đó mỗi đường dẫn chỉ định một trường duy nhất trong nội dung 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 đườ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 *.

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

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

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

Yêu cầu tất cả các trường bằng cách sử dụng mặt nạ trường *.
Xem hệ thống phân cấp của các trường trong phản hồi và xác định những trường bạn muốn.
Xây dựng mặt nạ trường bằng hệ thống phân cấp trường.

Xác định mặt nạ trường phản hồi cho Nearby Search (New) (Tìm kiếm lân cận (Mới)) và Tìm kiếm văn bản (New) (Tìm kiếm bằng văn bản (Mới))

Nearby Search (New) (Tìm kiếm lân cận (Mới)) và Tìm kiếm văn bản (New) (Tìm kiếm bằng văn bản (Mới)) trả về một mảng đố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à trường cấp cao nhất của phản hồi.

Ví dụ: để xem đối tượng phản hồi hoàn chỉnh từ một Tìm kiếm văn bả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ừ lệnh gọi Tìm kiếm văn bản (Mớ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 formattedAddress và displayName, hãy đặt mặt nạ trường thành:

places.formattedAddress,places.displayName

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

places.formattedAddress,places.displayName.text

Xác định mặt nạ trường phản hồi cho Place Details (New) (Thông tin chi tiết về địa điểm (Mới))

Place Details (New) (Thông tin chi tiết về địa điểm (Mới)) trả về một đối tượng Địa điểm duy nhất ở dạng:

{
  "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ể truyền biến đó đến yêu cầu.

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

Những điều cần cân nhắc về đường dẫn trường

Chỉ đưa những trường mà bạn yêu cầu 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 API thêm nhiều trường phản hồi hơn trong tương lai và các trường mới đó yêu cầu 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 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 tất cả các trường mới được tự động đưa vào phản hồi.
Tạo ra kích thước phản hồi nhỏ hơn, điều này 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, điều này giúp tránh thời gian xử lý và phí thanh toán không cần thiết.