เลือกข้อมูลที่จะแสดง

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

คุณสามารถระบุรายการช่องได้โดยการสร้างมาสก์ช่องการตอบกลับ จากนั้น คุณต้องส่งมาสก์ฟิลด์ตอบกลับไปยังเมธอดใดเมธอดหนึ่งโดยใช้พารามิเตอร์ของ 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 ที่ลิงก์ในรายการต่อไปนี้ ระบุฟิลด์ด้วยตัวพิมพ์ใหญ่แบบอูฐตามที่แสดงในการอ้างอิง เช่น routePreference

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

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

• มาสก์ช่องเส้นทางการประมวลผล
  • 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"
)

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

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

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

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

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

ขอโทเค็นเส้นทาง

หากต้องการขอให้ Routes API แสดงโทเค็นเส้นทางสำหรับเส้นทางที่สร้างขึ้น ให้ทำตามขั้นตอนต่อไปนี้

1. ตั้งค่าพารามิเตอร์ต่อไปนี้ซึ่งจําเป็นต่อการส่งคืนโทเค็นเส้นทาง
   • ตั้งค่า travelMode เป็น DRIVE
   • โปรดตั้งค่า routingPreference เป็น TRAFFIC_AWARE หรือ TRAFFIC_AWARE_OPTIMAL
2. ตรวจสอบว่าไม่มีจุดอ้างอิงของเส้นทางที่เป็นจุดอ้างอิง via จุด
3. ระบุมาสก์ของช่อง routes.routeToken เพื่อแสดงผลโทเค็นเส้นทาง ดังนี้

   X-Goog-FieldMask: routes.routeToken

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

คุณสามารถใช้โทเค็นเส้นทางสำหรับเส้นทางที่วางแผนใน SDK การนำทาง โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อ วางแผนเส้นทาง (Android) หรือวางแผนเส้นทาง (iOS)

ตัวอย่างโทเค็นเส้นทาง

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

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

ดูรายละเอียดเพิ่มเติมได้ที่เอกสารอ้างอิง Compute Routes API