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