เมื่อเรียกใช้เมธอดรายละเอียดสถานที่ (ใหม่), การค้นหาใกล้เคียง (ใหม่) หรือ ค้นหาข้อความ (ใหม่) คุณต้องระบุช่องที่ต้องการให้แสดงผลในคำตอบ ไม่มีรายการเริ่มต้นของ ช่องที่ส่งคืน หากคุณไม่ใช้รายการนี้ เมธอดจะแสดงข้อผิดพลาด
คุณระบุรายการช่องโดยการสร้างมาสก์ฟิลด์การตอบกลับ จากนั้นคุณจะส่งมาสก์ของช่องคำตอบไปยังเมธอดใดเมธอดหนึ่งได้โดยใช้พารามิเตอร์ $fields
หรือ fields
หรือใช้ส่วนหัว HTTP หรือ gRPC X-Goog-FieldMask
การมาสก์ฟิลด์เป็นการออกแบบที่ดีเพื่อไม่ให้ขอข้อมูลที่ไม่จำเป็น ซึ่งจะช่วยหลีกเลี่ยงเวลาในการประมวลผลและการเรียกเก็บเงินที่ไม่จําเป็น
กำหนดมาสก์ของช่องการตอบกลับ
ฟิลด์มาสก์การตอบกลับคือรายการเส้นทางที่คั่นด้วยคอมมา โดยแต่ละเส้นทางจะระบุช่องที่ไม่ซ้ำกันในข้อความตอบกลับ โดยเส้นทางนี้จะเริ่มจากข้อความตอบกลับระดับบนสุดและใช้เส้นทางที่คั่นด้วยจุดไปยังช่องที่ระบุ
สร้างเส้นทางช่องดังนี้
topLevelField[.secondLevelField][.thirdLevelField][...]
คุณส่งคำขอข้อมูลทุกช่องได้โดยใช้มาสก์ของช่อง *
ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีสร้างฟิลด์มาสก์ได้ที่ field_mask.proto
กำหนดว่าจะใช้มาสก์ฟิลด์ใด
วิธีกำหนดฟิลด์มาสก์ที่ต้องการใช้มีดังนี้
- ขอทุกช่องโดยใช้ฟิลด์มาสก์ "*"
- ดูลำดับชั้นของช่องในคำตอบแล้วกำหนดช่องที่ต้องการ
- สร้างฟิลด์มาสก์โดยใช้ลำดับชั้นฟิลด์
กำหนดมาสก์ของช่องคำตอบสำหรับการค้นหาใกล้เคียง (ใหม่) และการค้นหาข้อความ (ใหม่)
การค้นหาใกล้เคียง (ใหม่) และการค้นหาข้อความ (ใหม่) จะแสดงผลอาร์เรย์ของออบเจ็กต์สถานที่ในช่อง places
ของคำตอบ สำหรับ API เหล่านี้ places
จะเป็นช่องระดับบนสุดของการตอบกลับ
ตัวอย่างเช่น หากต้องการดูออบเจ็กต์การตอบกลับที่สมบูรณ์จาก Text Search (ใหม่) ให้ทำดังนี้
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 นี้ได้โดยการระบุฟิลด์ของออบเจ็กต์ Place ที่คุณต้องการส่งคืน
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 เพิ่มช่องการตอบกลับเพิ่มเติมในอนาคต และช่องใหม่เหล่านั้นต้องใช้เวลาในการคำนวณเพิ่มเติม หากเลือกช่องทั้งหมดหรือเลือกช่องทั้งหมดที่ระดับบนสุด ประสิทธิภาพอาจลดลงเมื่อช่องใหม่ทั้งหมดรวมอยู่ในคำตอบโดยอัตโนมัติ
- ทำให้การตอบสนองมีขนาดเล็กลง ซึ่งส่งผลให้อัตราการส่งข้อมูลของเครือข่ายสูงขึ้น
- ดูแลไม่ให้คุณขอข้อมูลที่ไม่จำเป็น ซึ่งจะช่วยหลีกเลี่ยงเวลาที่ไม่จำเป็นในการประมวลผลและค่าใช้จ่ายที่เรียกเก็บ