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