Method: computeRouteMatrix

รับรายการต้นทางและปลายทาง แล้วแสดงผลสตรีมที่มีข้อมูลเส้นทางสำหรับชุดค่าผสมต้นทางและปลายทางแต่ละชุด

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

ตัวอย่างเช่น ในวิธีนี้

  • ฟิลด์มาสก์ของช่องที่ใช้ได้ทั้งหมด (สำหรับการตรวจสอบด้วยตนเอง): X-Goog-FieldMask: *
  • ฟิลด์มาสก์ของระยะเวลา เส้นทาง ระยะทาง สถานะขององค์ประกอบ สภาพ และดัชนีองค์ประกอบ (ตัวอย่างการตั้งค่าเวอร์ชันที่ใช้งานจริง): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

คุณต้องใส่ status ในมาสก์ฟิลด์ ไม่เช่นนั้นข้อความทั้งหมดจะดูเหมือนว่าไม่มีปัญหา Google ไม่แนะนำให้ใช้มาสก์ฟิลด์การตอบกลับแบบไวลด์การ์ด (*) เนื่องจากเหตุผลต่อไปนี้

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

คำขอ HTTP

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

URL ใช้ไวยากรณ์การแปลงรหัส gRPC

เนื้อความของคำขอ

เนื้อหาของคำขอมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
ฟิลด์
origins[]

object (RouteMatrixOrigin)

ต้องระบุ อาร์เรย์ของต้นทาง ซึ่งกำหนดแถวของเมทริกซ์การตอบกลับ ข้อจำกัดด้านขนาดหลายประการมีผลกับ Cardinality ของต้นทางและปลายทาง ดังนี้

  • ผลรวมของจำนวนต้นทาง + จำนวนปลายทางที่ระบุเป็น placeId หรือ address ต้องไม่เกิน 50
  • ผลคูณของจำนวนต้นทาง × จำนวนปลายทางต้องไม่เกิน 625 ในทุกกรณี
  • ผลคูณของจำนวนต้นทาง × จำนวนปลายทางต้องไม่เกิน 100 หากตั้งค่า routingPreference เป็น TRAFFIC_AWARE_OPTIMAL
  • ผลคูณของจำนวนต้นทาง × จำนวนปลายทางต้องไม่เกิน 100 หากตั้งค่า travelMode เป็น TRANSIT
destinations[]

object (RouteMatrixDestination)

ต้องระบุ อาร์เรย์ของปลายทาง ซึ่งกำหนดคอลัมน์ของเมทริกซ์การตอบกลับ
travelMode

enum (RouteTravelMode)

ไม่บังคับ ระบุรูปแบบการเดินทาง
routingPreference

enum (RoutingPreference)

ไม่บังคับ ระบุวิธีกำหนดเส้นทาง เซิร์ฟเวอร์จะพยายามใช้ค่ากำหนดการกำหนดเส้นทางที่เลือกเพื่อคำนวณเส้นทาง หากค่ากำหนดการกำหนดเส้นทางส่งผลให้เกิดข้อผิดพลาดหรือเวลาในการตอบสนองนานเกินไป ระบบจะแสดงผลข้อผิดพลาด คุณจะระบุตัวเลือกนี้ได้เฉพาะเมื่อ travelMode เป็น DRIVE หรือ TWO_WHEELER เท่านั้น ไม่เช่นนั้นคำขอจะล้มเหลว
departureTime

string (Timestamp format)

ไม่บังคับ เวลาออกเดินทาง หากไม่ได้ตั้งค่านี้ ค่าเริ่มต้นจะเป็นเวลาที่คุณส่งคำขอ หมายเหตุ: คุณระบุ departureTime ในอดีตได้เมื่อตั้งค่า RouteTravelMode เป็น TRANSIT เท่านั้น

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย เช่น "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"
arrivalTime

string (Timestamp format)

ไม่บังคับ เวลาถึง หมายเหตุ: ตั้งค่าได้เมื่อตั้งค่า RouteTravelMode เป็น TRANSIT เท่านั้น คุณระบุ departureTime หรือ arrivalTime ได้อย่างใดอย่างหนึ่ง แต่จะระบุทั้ง 2 อย่างไม่ได้

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย เช่น "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"
languageCode

string

ไม่บังคับ รหัสภาษา BCP-47 เช่น "en-US" หรือ "sr-Latn" ดูข้อมูลเพิ่มเติมได้ที่ตัวระบุภาษาของ Unicode ดูรายการภาษาที่รองรับได้ที่การรองรับภาษา เมื่อคุณไม่ได้ระบุค่านี้ ระบบจะอนุมานภาษาที่แสดงจากตำแหน่งของต้นทางแรก
regionCode

string

ไม่บังคับ รหัสภูมิภาคที่ระบุเป็นค่า ccTLD ("โดเมนระดับบนสุด") 2 อักขระ ดูข้อมูลเพิ่มเติมได้ที่โดเมนระดับบนสุดแบบรหัสประเทศ
units

enum (Units)

ไม่บังคับ ระบุหน่วยวัดสำหรับฟิลด์ที่แสดง
extraComputations[]

enum (ExtraComputation)

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

enum (TrafficModel)

ไม่บังคับ ระบุสมมติฐานที่จะใช้เมื่อคำนวณเวลาในการเข้าชม การตั้งค่านี้จะส่งผลต่อค่าที่แสดงในช่องระยะเวลาใน RouteMatrixElement ซึ่งมีเวลาที่คาดการณ์ในการเข้าชมตามค่าเฉลี่ยในอดีต TrafficModel ใช้ได้กับคำขอที่ตั้งค่า RoutingPreference เป็น TRAFFIC_AWARE_OPTIMAL และ RouteTravelMode เป็น DRIVE เท่านั้น ค่าเริ่มต้นจะเป็น BEST_GUESS หากมีการขอการเข้าชมและไม่ได้ระบุ TrafficModel
transitPreferences

object (TransitPreferences)

ไม่บังคับ ระบุค่ากำหนดที่มีผลต่อเส้นทางที่แสดงสำหรับTRANSITเส้นทาง หมายเหตุ: คุณระบุ transitPreferences ได้ก็ต่อเมื่อตั้งค่า RouteTravelMode เป็น TRANSIT

เนื้อหาการตอบกลับ

มีข้อมูลเส้นทางที่คำนวณสำหรับคู่ต้นทาง/ปลายทางใน API v2.computeRouteMatrix ซึ่งสามารถสตรีมไปยังไคลเอ็นต์ได้

หากทำสำเร็จ เนื้อหาการตอบกลับจะมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

การแสดง JSON 
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
ช่อง
status

object (Status)

รหัสสถานะข้อผิดพลาดขององค์ประกอบนี้
condition

enum (RouteMatrixElementCondition)

ระบุว่าพบเส้นทางหรือไม่ ไม่ขึ้นอยู่กับสถานะ
distanceMeters

integer

ระยะทางการเดินทางของเส้นทางเป็นเมตร
duration

string (Duration format)

ระยะเวลาที่ใช้ในการนำทางตามเส้นทาง หากตั้งค่า routingPreference เป็น TRAFFIC_UNAWARE ค่านี้จะเหมือนกับ staticDuration หากคุณตั้งค่า routingPreference เป็น TRAFFIC_AWARE หรือ TRAFFIC_AWARE_OPTIMAL ระบบจะคำนวณค่านี้โดยพิจารณาจากสภาพการจราจร

ระยะเวลาเป็นวินาทีที่มีเศษทศนิยมได้สูงสุด 9 หลัก โดยลงท้ายด้วย 's' เช่น "3.5s"
staticDuration

string (Duration format)

ระยะเวลาในการเดินทางผ่านเส้นทางโดยไม่คำนึงถึงสภาพการจราจร

ระยะเวลาเป็นวินาทีที่มีเศษทศนิยมได้สูงสุด 9 หลัก โดยลงท้ายด้วย 's' เช่น "3.5s"
travelAdvisory

object (RouteTravelAdvisory)

ข้อมูลเพิ่มเติมเกี่ยวกับเส้นทาง เช่น ข้อมูลเกี่ยวกับข้อจำกัดและข้อมูลค่าผ่านทาง
fallbackInfo

object (FallbackInfo)

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

object (LocalizedValues)

การแสดงข้อความของพร็อพเพอร์ตี้ของ RouteMatrixElement
originIndex

integer

ดัชนีที่อิงตาม 0 ของต้นทางในคำขอ
destinationIndex

integer

ดัชนีที่อิงตาม 0 ของปลายทางในคำขอ

RouteMatrixOrigin

ต้นทางเดียวสำหรับ ComputeRouteMatrixRequest

การแสดง JSON 
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
ฟิลด์
waypoint

object (Waypoint)

ต้องระบุ จุดอ้างอิงต้นทาง
routeModifiers

object (RouteModifiers)

ไม่บังคับ ตัวแก้ไขสำหรับทุกเส้นทางที่ใช้จุดนี้เป็นต้นทาง

RouteMatrixDestination

ปลายทางเดียวสำหรับ ComputeRouteMatrixRequest

การแสดง JSON 
{
  "waypoint": {
    object (Waypoint)
  }
}
ฟิลด์
waypoint

object (Waypoint)

ต้องระบุ จุดอ้างอิงปลายทาง

ExtraComputation

การคำนวณเพิ่มเติมที่จะดำเนินการขณะประมวลผลคำขอ

Enum
EXTRA_COMPUTATION_UNSPECIFIED ไม่ได้ใช้ คำขอที่มีค่านี้จะล้มเหลว
TOLLS ข้อมูลค่าผ่านทางสำหรับองค์ประกอบเมทริกซ์

RouteMatrixElementCondition

สภาพของเส้นทางที่แสดง

Enum
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED ใช้เฉพาะเมื่อ status ขององค์ประกอบไม่ถูกต้อง
ROUTE_EXISTS พบเส้นทางและระบบได้กรอกข้อมูลที่เกี่ยวข้องสำหรับองค์ประกอบแล้ว
ROUTE_NOT_FOUND ไม่พบเส้นทาง ระบบจะไม่กรอกข้อมูลในช่องที่มีข้อมูลเส้นทาง เช่น distanceMeters หรือ duration ในองค์ประกอบ

LocalizedValues

การแสดงข้อความของพร็อพเพอร์ตี้บางอย่าง

การแสดง JSON 
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
ช่อง
distance

object (LocalizedText)

ระยะทางในการเดินทางที่แสดงในรูปแบบข้อความ
duration

object (LocalizedText)

ระยะเวลาที่แสดงในรูปแบบข้อความโดยพิจารณาสภาพการจราจร หมายเหตุ: หากไม่ได้ขอข้อมูลการเข้าชม ค่านี้จะเป็นค่าเดียวกับ staticDuration
staticDuration

object (LocalizedText)

ระยะเวลาที่แสดงในรูปแบบข้อความโดยไม่พิจารณาสภาพการจราจร
transitFare

object (LocalizedText)

ค่าโดยสารขนส่งที่แสดงในรูปแบบข้อความ