Trang này được dịch bởi Cloud Translation API.

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

Khi gọi phương thức Thông tin về địa điểm (Mới), Tìm kiếm lân cận (Mới) hoặc Tìm kiếm bằng văn bản (Mới), bạn phải chỉ định những trường mà bạn muốn được trả về trong phản hồi. Không có danh sách mặc định 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 sẽ 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 tiêu đề HTTP hay gRPC X-Goog-FieldMask.

Che giấu trường là một phương pháp thiết kế hiệu quả để đảm bảo 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à phí thanh toán không cần thiết.

Xác định mặt nạ cho trường (field mask) của 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 duy nhất trong thông báo phản hồi. Đường dẫn này 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 một đườ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 (field mask) của *.

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

Xác định loại mặt nạ cho trường (field mask) cần sử dụng

Sau đây là cách xác định mặt nạ cho trường (field mask) 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 của "*".
Xem hệ phân cấp của các trường trong phản hồi rồi xác định những trường bạn muốn.
Tạo mặt nạ trường bằ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à 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 qua 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ừ lệnh gọi Tìm kiếm văn bả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 sẽ chỉ định mặt nạ trường (field mask) cho các API này dưới 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 (field mask) 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 thiết lập mặt nạ cho trường (field mask) như sau:

places.formattedAddress,places.displayName.text

Xác định mặt nạ trường phản hồi cho Thông tin chi tiết về đị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 sẽ chỉ định mặt nạ trường (field mask) 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

cuộc 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 đó vào yêu cầu.

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

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

Chỉ thêm những trường mà bạn yêu cầu trong câu trả lời. Chỉ trả về các trường mà bạn cần:

Giảm thời gian xử lý để kết quả trả về với độ trễ thấp hơn.
Đảm bảo hiệu suất độ trễ ổn định nếu API bổ sung thêm trường phản hồi trong tương lai và các trường mới đó sẽ cần thêm thời gian tính toán. Nếu chọn tất cả các trường hoặc chọn tất cả các trường ở cấp cao nhất, thì bạn có thể thấy hiệu suất giảm khi tất cả các trường mới được tự động đư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, từ đó dẫn đến thông lượng mạng cao hơn.
Đảm bảo bạn không yêu cầu dữ liệu không cần thiết, nhằm tránh thời gian xử lý và các khoản phí phát sinh không cần thiết.