API Tuyến đường hiện đang ở chế độ Xem trước (trước GA). Các sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể không được hỗ trợ hạn chế. Đồng thời, các thay đổi đối với sản phẩm và tính năng trước giai đoạn phát hành rộng rãi có thể không tương thích với các phiên bản trước giai đoạn phát hành rộng rãi khác. Các Sản phẩm trước giai đoạn phát hành rộng rãi chịu sự điều chỉnh của Điều khoản dành riêng cho dịch vụ nền tảng Google Maps. Để biết thêm thông tin, hãy xem nội dung mô tả giai đoạn ra mắt.

Hướng dẫn di chuyển API tuyến đường

Hiện tại, Nền tảng Google Maps hỗ trợ API Chỉ đườngAPI Ma trận khoảng cách. Bản phát hành API tuyến đường mới này chứa phiên bản thế hệ tiếp theo, được tối ưu hóa hiệu suất của API chỉ đường và API ma trận khoảng cách hiện có:

  • Tuyến tính: Tính toán hướng giữa các vị trí với dữ liệu định tuyến toàn diện và toàn cầu cùng lưu lượng truy cập theo thời gian thực.
  • Ma trận tuyến tính: Tính khoảng cách và thời gian đi lại để xem danh sách các cặp điểm xuất phát/đích.

API tuyến đường bao gồm nhiều tính năng mới, bao gồm:

  • Định tuyến TWO_WHEELER
  • Phí cầu đường
  • Đường liên kết nhận biết lưu lượng truy cập
  • Quản lý chất lượng hình nhiều đường
  • Quản lý độ trễ chất lượng
  • Truyền kết quả (Ma trận tuyến tính bằng chỉ sử dụng gRPC)
  • Hỗ trợ gRPC

Để biết thêm thông tin về API tuyến đường, hãy xem API tuyến đường.

Hướng dẫn này mô tả cách di chuyển các ứng dụng hiện có của bạn có sử dụng API Chỉ đường và API Ma trận khoảng cách để sử dụng API Tuyến đường mới.

Thay đổi chức năng trong API tuyến đường mới

Ở cấp độ cao, API Tuyến đường thực hiện những thay đổi sau đối với API Chỉ đường và API Ma trận khoảng cách:

  • Hợp nhất các tuyến tính toán và ma trận tuyến tính trong một dịch vụ duy nhất có tên là API tuyến đường

    Bạn phải bật API tuyến đường trong Bảng điều khiển API trước khi có thể sử dụng Tuyến tính và Ma trận tuyến tính. Hiện tại, bạn bật API Đường đi và API Ma trận khoảng cách dưới dạng các dịch vụ riêng biệt trong Bảng điều khiển API.

    Để biết thêm thông tin, hãy xem phần Thiết lập trong Google API Console.

  • API Tuyến đường mới sử dụng yêu cầu POST HTTP

    Trong API tuyến đường mới, bạn chuyển các thông số trong nội dung yêu cầu hoặc trong tiêu đề như một phần của yêu cầu POST HTTP. Ngược lại, với API Chỉ đường và API Ma trận khoảng cách, bạn truyền các tham số URL bằng cách sử dụng yêu cầu HTTP GET.

    Để biết ví dụ, hãy xem:

  • Bắt buộc đeo khẩu trang

    Khi gọi API Tuyến đường mới để tính toán tuyến đường hoặc tính toán ma trận tuyến, bạn phải chỉ định những trường mình muốn trả về trong phản hồi. Không có danh sách mặc định các trường được trả về. Nếu bạn bỏ qua danh sách này, các phương thức sẽ trả về lỗi.

    Chỉ định danh sách trường bằng cách tạo mặt nạ trường phản hồi. Sau đó, hãy chuyển mặt nạ trường phản hồi đến từng phương thức bằng cách sử dụng tham số URL $fields hoặc fields, hoặc bằng cách sử dụng tiêu đề HTTP/gRPC X-Goog-FieldMask.

    Che mặt trường là một phương pháp thiết kế hay để đảm bảo bạn không yêu cầu dữ liệu không cần thiết, giúp tránh thời gian xử lý và phí thanh toán không cần thiết.

    Để biết thêm thông tin, hãy xem phần Chọn trường cần trả về.

  • Giới hạn yêu cầu mới cho Ma trận tuyến tính

    API ma trận khoảng cách đã thực thi các giới hạn yêu cầu sau:

    • Tối đa 25 nguồn gốc hoặc 25 đích đến cho mỗi yêu cầu.
    • Tối đa 100 phần tử (số nguồn gốc × số đích) cho mỗi yêu cầu phía máy chủ.

    Ma trận tuyến tính thực thi các giới hạn của yêu cầu sau:

    • Số lượng phần tử không được vượt quá 625.

    • Nếu bạn chỉ định TRAFFIC_AWARE_OPTIMAL, thì số lượng phần tử không được vượt quá 100. Để biết thêm thông tin về TRAFFIC_AWARE_OPTIMAL, hãy xem phần Định cấu hình chất lượng so với độ trễ.

    • Số lượng điểm trung bình (nguồn gốc + điểm đến) tối đa mà bạn có thể chỉ định bằng cách sử dụng Mã địa điểm là 50.

  • Các tuỳ chọn mới để định cấu hình chất lượng và độ trễ

    API tuyến đường mới hỗ trợ ba tùy chọn định tuyến mà bạn có thể sử dụng để định cấu hình rõ ràng chất lượng tuyến đường và độ trễ phản hồi:

    • TRAFFIC_UNAWARE (mặc định) – Sử dụng dữ liệu lưu lượng truy cập độc lập trung bình không phụ thuộc vào thời gian, không phải dữ liệu giao thông trực tiếp để tính toán tuyến đường, dẫn đến độ trễ phản hồi thấp nhất. Chế độ cài đặt này tương đương với khi lưu lượng truy cập không được sử dụng trong API Chỉ đường và API Ma trận khoảng cách.

    • TRAFFIC_AWARE – Chất lượng lưu lượng truy cập trực tiếp được tối ưu hoá hiệu suất để giảm độ trễ. Chế độ cài đặt này mới dành cho API Tuyến đường và không tương đương với API Đường đi và API Ma trận khoảng cách.

      Trái ngược với TRAFFIC_AWARE_OPTIMAL, một số phương pháp tối ưu hoá được áp dụng để giảm đáng kể độ trễ.

    • TRAFFIC_AWARE_OPTIMAL – Dữ liệu lưu lượng truy cập toàn diện, chất lượng cao mà không cần áp dụng hầu hết các phương pháp tối ưu hóa hiệu suất. Chế độ cài đặt này tạo ra độ trễ cao nhất và tương đương với chế độ cài đặt của departure_time trong API Chỉ đường và API Ma trận khoảng cách.

      Tuỳ chọn định tuyến TRAFFIC_AWARE_OPTIMAL tương đương với chế độ mà maps.google.com và ứng dụng Google Maps dành cho thiết bị di động sử dụng.

    Trong API Chỉ đường và API Ma trận khoảng cách, chúng tôi chỉ cung cấp các tùy chọn tương đương cho TRAFFIC_AWARE_OPTIMALTRAFFIC_UNAWARE. Các tuỳ chọn này đã được đặt ngầm dựa trên việc bạn có thiết lập departure_time hay không.

    Bảng sau đây so sánh các tùy chọn hiện tại API Chỉ đường và Ma trận khoảng cách và với các tùy chọn Tuyến đường API mới:

    Chế độ Hiện tại Routes API Ghi chú
    Không có giao thông theo thời gian thực Chưa đặt thuộc tính departure_time TRAFFIC_UNAWARE Độ trễ nhanh nhất trong ba chế độ.
    Đã áp dụng tình trạng giao thông trực tiếp Không có phiên bản mới TRAFFIC_AWARE

    Chế độ mới được thêm bởi API tuyến đường. Phương thức này cung cấp độ trễ lớn hơn một chút so với TRAFFIC_UNAWARE trong khi chi phí cho chất lượng ETA là nhỏ.

    Nó có độ trễ thấp hơn nhiều so với TRAFFIC_AWARE_OPTIMAL.

    Đã áp dụng dữ liệu lưu lượng truy cập trực tiếp toàn diện và chất lượng cao Đã đặt departure_time cơ sở lưu trú TRAFFIC_AWARE_OPTIMAL

    Tương đương với chế độ mà maps.google.com và ứng dụng Google Maps dành cho thiết bị di động sử dụng.

    Đối với Ma trận tuyến tính, số lượng phần tử trong một yêu cầu (số điểm bắt đầu × số đích đến) không được vượt quá 100.

    API tuyến đường cũng sửa đổi cách đặt thuộc tính phản hồi duration và sửa đổi các thuộc tính được trả về trong phản hồi hiện tại, như hiển thị trong bảng sau:

    Loại thời gian đến dự kiến của chuyến đi Hiện tại Routes API
    Thời gian đến dự kiến, phụ thuộc vào thời gian mà giao thông không nhận biết được.

    Tương ứng với departure_time không được đặt trong yêu cầu.

    • ETA có trong thuộc tính phản hồi duration.
    • Thuộc tính phản hồi duration_in_traffic không được trả về.

    Tương ứng với TRAFFIC_UNAWARE.

    • ETA có trong thuộc tính phản hồi duration.
    • Các thuộc tính phản hồi durationstaticDuration chứa cùng một giá trị.
    ETA có cân nhắc lưu lượng truy cập theo thời gian thực.

    Tương ứng với việc đặt departure_time trong yêu cầu.

    • ETA xem xét lưu lượng truy cập theo thời gian thực có trong thuộc tính phản hồi duration_in_traffic.

    Tương ứng với TRAFFIC_AWARE hoặc TRAFFIC_AWARE_OPTIMAL.

    • ETA xem xét lưu lượng truy cập theo thời gian thực có trong thuộc tính phản hồi duration.
    • Thuộc tính phản hồi staticDuration chứa thời lượng di chuyển qua tuyến đường mà không tính đến tình trạng giao thông.
    • Thuộc tính duration_in_traffic không còn được trả về nữa.

    Để biết thêm thông tin, hãy xem phần nội dung Định cấu hình chất lượng so với độ trễ.

Các tính năng hiện có không được hỗ trợ trong API tuyến đường

Các tính năng sau đây sẽ không được hỗ trợ trong API Tuyến đường:

  • XML dưới dạng định dạng phản hồi. Hệ thống chỉ hỗ trợ JSON và gRPC.

  • Mã hoá địa lý ngược

    Giờ đây, bạn sử dụng API mã hoá địa lý ngược cho chức năng được xây dựng cho trường hợp sử dụng này và cung cấp kết quả chất lượng cao hơn.

Chuyển sang API Tuyến đường

Chúng tôi đã thực hiện một số thay đổi trong API Tuyến đường. Hầu hết các thay đổi đều tương thích ngược với các API hiện tại, nhưng có một vài thay đổi có thể gây lỗi được liệt kê bên dưới mà bạn cần chú ý khi di chuyển ứng dụng sang API Tuyến.

Cập nhật điểm cuối của API REST

Nếu bạn đang sử dụng API Chỉ đường, hãy cập nhật mã để sử dụng điểm cuối của Tuyến đường mới:

API Đường đi https://maps.googleapis.com/maps/api/directions/outputFormat?parameters
API Tuyến đường https://routes.googleapis.com/directions/v2:computeRoutes

Nếu bạn đang sử dụng Matrix Matrix API, hãy cập nhật mã để sử dụng điểm cuối của API Tuyến đường mới:

API Ma trận khoảng cách https://maps.googleapis.com/maps/api/distancematrix/outputFormat?parameters
API Tuyến đường https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

Chuyển đổi tham số URL để sử dụng nội dung yêu cầu HTTP

Với API Chỉ đường và API Ma trận khoảng cách, bạn chuyển các thuộc tính cấu hình dưới dạng tham số URL đến yêu cầu HTTP GET. Ví dụ: đối với API Chỉ đường:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

Với API tuyến đường, bạn truyền các tham số trong nội dung yêu cầu hoặc trong các tiêu đề của yêu cầu POST HTTP. Để biết ví dụ, hãy xem:

Chuyển đổi tham số hiện tại thành tham số API tuyến đường

Bảng sau đây liệt kê các thông số trong API Chỉ đường và API Ma trận khoảng cách hiện tại đã được đổi tên hoặc sửa đổi, hoặc các thông số không được hỗ trợ trong bản dùng thử. Hãy cập nhật mã của bạn nếu bạn đang sử dụng bất kỳ thông số nào trong số này.

Tham số hiện tại Thông số API tuyến đường Ghi chú
destination destination Địa chỉ và mã Plus không có trong Bản dùng thử.
origin origin Địa chỉ và mã Plus không có trong Bản dùng thử.
alternatives computeAlternativeRoutes
arrival_time Không sử dụng được vì chế độ TRANSIT không có trong tính năng Xem trước.
avoid routeModifiers
copyrights Không có trong Bản dùng thử.
departure_time departureTime
distance distanceMeters Khoảng cách chỉ có sẵn bằng mét.
duration_in_traffic Xoá trong Tuyến đường API, sử dụng duration. Để biết thêm thông tin, hãy xem phần Các thay đổi về chức năng cho API Tuyến đường mới ở trên.
language languageCode
mode travelMode

Thêm tính năng hỗ trợ cho TWO_WHEELER.

Chế độ TRANSIT không dùng được trong Bản xem trước.

region Không có trong Bản dùng thử vì các địa chỉ không được hỗ trợ.
status Không có trong Bản dùng thử. Sử dụng mã phản hồi HTTP cho các lỗi mà API báo cáo. Hãy xem bài viết Xử lý lỗi yêu cầu để biết thêm thông tin.
traffic_model Không có trong Bản dùng thử.
transit_mode Không sử dụng được vì chế độ TRANSIT không có trong tính năng Xem trước.
transit_routing_preference Không sử dụng được vì chế độ TRANSIT không có trong tính năng Xem trước.
units Không có cho Ma trận khoảng cách trong bản dùng thử.
waypoints intermediates Địa chỉ và nhiều đường liên kết không có trong Bản dùng thử.
optimize=true cho điểm tham chiếu Không có trong Bản dùng thử.