เลือกช่องที่จะส่งคืน

เมื่อคุณเรียกข้อมูลรายละเอียดสถานที่ (ใหม่), การค้นหาใกล้เคียง (ใหม่) หรือ การค้นหาข้อความ (ใหม่) วิธีการมีดังนี้ ระบุฟิลด์ที่คุณต้องการให้แสดงผลในคำตอบ ไม่มีรายการเริ่มต้น ของช่องที่แสดงผล หากคุณไม่ใส่รายการนี้ เมธอดจะแสดงข้อผิดพลาด

คุณสามารถระบุรายการช่องได้โดยการสร้างมาสก์ช่องการตอบกลับ จากนั้นคุณข้าม มาสก์ฟิลด์ตอบกลับของเมธอดใดเมธอดหนึ่งโดยใช้พารามิเตอร์ $fields หรือ fields หรือใช้ส่วนหัว HTTP หรือ gRPC X-Goog-FieldMask

การมาสก์ช่องเป็นแนวทางปฏิบัติในการออกแบบที่ดีเพื่อให้แน่ใจว่าคุณไม่ได้ส่งคำขอ ข้อมูลที่ไม่จำเป็น ซึ่งช่วยหลีกเลี่ยงเวลาในการประมวลผลและการเรียกเก็บเงินที่ไม่จำเป็น

กำหนดมาสก์ของช่องการตอบกลับ

มาสก์ฟิลด์การตอบกลับคือรายการเส้นทางที่คั่นด้วยคอมมา โดยแต่ละเส้นทาง ระบุช่องที่ไม่ซ้ำกันในข้อความตอบกลับ เส้นทางเริ่มจาก ข้อความตอบกลับระดับบนสุดและใช้เส้นทางที่คั่นด้วยจุดไปยังช่องที่ระบุ

สร้างเส้นทางช่องดังนี้

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

คุณขอข้อมูลในช่องทั้งหมดได้โดยใช้มาสก์ของช่อง *

ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีสร้างฟิลด์มาสก์ได้ที่ field_mask.proto.

กำหนดฟิลด์มาสก์ที่จะใช้

คุณกำหนดฟิลด์มาสก์ที่ต้องการใช้ได้โดยทำดังนี้

  1. ขอฟิลด์ทั้งหมดโดยใช้มาสก์ฟิลด์ "*"
  2. ให้ดูที่ลำดับชั้นของช่องในคำตอบ แล้วพิจารณาว่าสิ่งใด ช่องที่ต้องการได้อีกด้วย
  3. สร้างมาสก์ของช่องโดยใช้ลำดับชั้นของช่อง

กำหนดมาสก์ของช่องตอบกลับสำหรับการค้นหา Nearby (ใหม่) และการค้นหาข้อความ (ใหม่)

การค้นหาใกล้เคียง (ใหม่) และ การค้นหาข้อความ (ใหม่) จะแสดงอาร์เรย์ของออบเจ็กต์สถานที่ใน ช่อง places ของคำตอบ สำหรับ API เหล่านี้ places คือระดับบนสุด ของคำตอบ

เช่น หากต้องการดูออบเจ็กต์การตอบกลับที่สมบูรณ์จาก การค้นหาข้อความ (ใหม่):

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'

ออบเจ็กต์การตอบกลับที่สมบูรณ์จากการค้นหาข้อความ (ใหม่) จะอยู่ในรูปแบบ:

{
  "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"
      },      ...
    },
  ...
  ]
}

คุณจึงระบุมาสก์ฟิลด์สำหรับ API เหล่านี้ในรูปแบบต่อไปนี้

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

หากต้องการแสดงผลเฉพาะช่อง formattedAddress และ displayName ให้ตั้งค่า มาสก์ของช่องเพื่อ

places.formattedAddress,places.displayName

การระบุ displayName จะรวมทั้งช่อง text และ language ของ displayName หากต้องการเฉพาะช่อง text ให้ตั้งค่ามาสก์ของช่องดังนี้

places.formattedAddress,places.displayName.text

กำหนดมาสก์ฟิลด์ตอบกลับสำหรับรายละเอียดสถานที่ (ใหม่)

รายละเอียดสถานที่แสดงออบเจ็กต์สถานที่เดียวในรูปแบบ

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

คุณจึงระบุมาสก์ฟิลด์สำหรับ API นี้โดยระบุฟิลด์ของ วางออบเจ็กต์ที่คุณต้องการส่งคืน ดังนี้

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

การโทร gRPC

สำหรับ gRPC ให้ตั้งค่าตัวแปรที่มีมาสก์ฟิลด์การตอบสนอง จากนั้นคุณจะสามารถข้าม ตัวแปรนั้นให้กับคำขอ

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

ข้อควรพิจารณาเกี่ยวกับเส้นทางช่อง

ใส่เฉพาะช่องที่จําเป็นในคําตอบ การแสดงผล ที่คุณต้องกรอกข้อมูลต่อไปนี้

  • ลดเวลาในการประมวลผล ดังนั้นระบบจะส่งคืนผลลัพธ์โดยมีเวลาต่ำลง เวลาในการตอบสนอง
  • ดูแลให้เวลาในการตอบสนองมีความเสถียรหาก API เพิ่มช่องตอบกลับเพิ่มเติม ในอนาคต และฟิลด์ใหม่ๆ เหล่านี้ต้องใช้เวลาในการคำนวณเพิ่มเติม หากคุณ เลือกทุกช่อง หรือหากคุณเลือกช่องทั้งหมดที่ระดับบนสุด ประสิทธิภาพจะลดลงเมื่อฟิลด์ใหม่ทั้งหมด รวมอยู่ในคำตอบของคุณโดยอัตโนมัติ
  • ทำให้ขนาดการตอบสนองเล็กลง ซึ่งส่งผลให้เครือข่ายสูงขึ้น อัตราการส่งข้อมูล
  • ตรวจสอบว่าคุณไม่ได้ขอข้อมูลที่ไม่จำเป็น ซึ่งจะช่วยหลีกเลี่ยง เวลาในการประมวลผลที่ไม่จำเป็นและค่าใช้จ่ายที่เรียกเก็บ