เลือกช่องที่จะแสดงผล

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

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

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับพารามิเตอร์ของ URL ได้ที่พารามิเตอร์ของระบบ

กำหนดมาสก์ฟิลด์คำตอบ

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

สร้างและระบุเส้นทางฟิลด์ดังนี้

1. ค้นหาช่องที่มีข้อมูลที่คุณต้องการจาก Routes API โปรดดูรายละเอียดที่หัวข้อการอ้างอิงช่อง
2. กำหนดเส้นทางสำหรับช่องที่ต้องการและสร้างฟิลด์มาสก์สำหรับช่องเหล่านั้น: ดูรายละเอียดได้ที่กำหนดฟิลด์มาสก์ที่ต้องการใช้

3. รวมมาสก์ฟิลด์สำหรับฟิลด์ทั้งหมดที่ต้องการ โดยคั่นมาสก์ฟิลด์ด้วยคอมมา เช่น หากต้องการขอ distanceMeters สำหรับเส้นทาง รวมถึงระยะเวลาของขั้นตอนแต่ละขั้นของเส้นทาง ให้ป้อนทั้ง 2 รายการโดยคั่นด้วยคอมมา โดยไม่ต้องเว้นวรรค

   routes.legs.distanceMeters,routes.legs.steps.duration

4. ส่งมาสก์ฟิลด์พร้อมกับคำขอ API ตัวอย่างเช่น ในคําขอ cURL คุณจะต้องระบุฟิลด์มาสก์ด้วย -H และ X-Goog-FieldMask

   -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration

ดูตัวอย่างและรายละเอียดเพิ่มเติมได้ที่ส่วนต่อไปนี้

การอ้างอิงฟิลด์

หากต้องการดูช่องที่คุณขอในการตอบกลับผ่านมาสก์ฟิลด์ โปรดดูข้อมูลอ้างอิง Routes API ที่ลิงก์ไว้ในรายการต่อไปนี้ ระบุฟิลด์ในรูปแบบ Camel Case ตามที่แสดงในข้อมูลอ้างอิง เช่น routePreference

ในทางตรงกันข้าม คุณต้องป้อนค่าพารามิเตอร์ตามที่แสดง เช่น สำหรับ routingPreference คุณต้องป้อน TRAFFIC_AWARE

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

• มาสก์ช่องเส้นทางของ Compute
  • REST: ระบุฟิลด์ของออบเจ็กต์ Route ในคำตอบที่จะแสดงผล โดยใส่คำนำหน้าเป็น routes. เช่น routes.distanceMeters
  • gRPC: ระบุช่องของออบเจ็กต์ Route ในการตอบกลับที่จะแสดง
• คํานวณมาสก์ช่องเมตริกเส้นทาง
  • REST: ระบุช่องของเนื้อหาคำตอบที่จะแสดง
  • gRPC: ระบุช่องของออบเจ็กต์ RouteMatrixElement ในคำตอบที่จะแสดง

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

วิธีระบุช่องที่ต้องการใช้และสร้างมาสก์ช่องมีดังนี้

1. ขอข้อมูลทุกช่องโดยใช้มาสก์ฟิลด์ *
   ข้อควรระวัง: แม้ว่าคุณจะใช้มาสก์ช่องไวลด์การ์ดนี้ในระหว่างการพัฒนาเพื่อระบุช่องที่ต้องการได้ แต่อย่าใช้ในเวอร์ชันที่ใช้งานจริง การขอฟิลด์ทั้งหมดในเวอร์ชันที่ใช้งานจริงจะทำให้ต้นทุนสูงขึ้นและเวลาในการตอบกลับนานขึ้น นอกจากนี้ ค่าใช้จ่ายอาจเพิ่มขึ้นโดยไม่คาดคิดเมื่อมีการเพิ่มฟีเจอร์ขั้นสูงมากขึ้น เนื่องจากมาสก์ช่องนี้จะรวมฟีเจอร์เหล่านั้นโดยอัตโนมัติ แต่ให้ขอเฉพาะช่องที่คุณต้องการเพื่อลดค่าใช้จ่ายและเวลาในการตอบกลับคำขอ
2. ดูลําดับชั้นของช่องในการตอบกลับสําหรับช่องที่ต้องการ

3. สร้างมาสก์ช่องโดยใช้ลําดับชั้นของช่องที่แสดงในขั้นตอนก่อนหน้า โดยใช้รูปแบบนี้

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

   หมายเหตุ: อย่าเว้นวรรคในรายการเส้นทางของช่อง

ตัวอย่างเช่น สำหรับคำตอบบางส่วนจากเส้นทางนี้

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

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

routes.legs.distanceMeters

หากต้องการแสดงผลฟิลด์ distanceMeters สำหรับแต่ละขั้นตอนของเส้นทางแทน ซึ่งก็คือ distanceMeters ในส่วน steps ในตัวอย่างก่อนหน้านี้ มาสก์ฟิลด์จะเป็นดังนี้

routes.legs.steps.distanceMeters

หากต้องการแสดงผลทั้ง 2 รายการพร้อมผลลัพธ์ด้านบน มาสก์ฟิลด์จะเป็นดังนี้

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

ตัวอย่างเส้นทางฟิลด์มาสก์

ส่วนนี้มีตัวอย่างเพิ่มเติมเกี่ยวกับวิธีระบุเส้นทางฟิลด์เป็นส่วนหนึ่งของมาสก์ฟิลด์คำตอบในการเรียก REST และ gRPC

การเรียกใช้ REST ไปยัง computeRoutes

ในตัวอย่างแรก คุณใช้การเรียก REST กับเมธอด computeRoutes เพื่อคํานวณเส้นทาง ในตัวอย่างนี้ คุณระบุมาสก์ช่องในส่วนหัวเพื่อแสดงผลช่องเส้นทาง distanceMeters และ duration ในการตอบกลับ อย่าลืมใส่ routes นําหน้าชื่อช่อง

X-Goog-FieldMask: routes.distanceMeters,routes.duration

การเรียกใช้ REST ไปยัง computeRouteMatrix

สําหรับเมธอด REST computeRouteMatrix ที่ใช้ในการคํานวณเมทริกซ์เส้นทาง ให้ระบุในส่วนหัวเพื่อแสดงผล originIndex, destinationIndex และ duration สําหรับชุดค่าผสมต้นทางและปลายทางแต่ละชุด

X-Goog-FieldMask: originIndex,destinationIndex,duration

การเรียกใช้ gRPC

สําหรับ gRPC ให้ตั้งค่าตัวแปรที่มีมาสก์ช่องการตอบกลับ จากนั้นคุณสามารถส่งตัวแปรนั้นไปยังคําขอได้

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

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

ใส่เฉพาะช่องที่ต้องการในการตอบกลับเพื่อแสดงเฉพาะช่องที่ต้องการ

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

หมายเหตุ: เมื่อมีการแยกวิเคราะห์ข้อความตอบกลับ และช่องในข้อความตอบกลับมีค่าเริ่มต้น ระบบอาจละเว้นช่องนั้นในการตอบกลับ แม้ว่าคุณจะระบุไว้ในมาสก์ช่องคำตอบก็ตาม ดูข้อมูลเพิ่มเติมได้ที่คู่มือภาษา (proto3) เช่น เมื่อคุณคํานวณเมทริกซ์เส้นทาง ช่อง distanceMeters ของคําตอบอาจมีค่าเป็น 0 ซึ่งเป็นค่าเริ่มต้น เนื่องจาก 0 คือค่าเริ่มต้นของ distanceMeters ระบบจึงละเว้นค่านี้ในการตอบกลับ

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