Hướng dẫn di chuyển mã ứng dụng khách

Tổng quan

Để tăng cường tính bảo mật và độ tin cậy của quy trình xác thực, mã ứng dụng khách của Nền tảng Google Maps đã ngừng hoạt động kể từ ngày 26 tháng 5 năm 2025 và không còn dùng được sau ngày 31 tháng 5 năm 2026.

Thay vì sử dụng mã ứng dụng khách, bạn phải sử dụng thông tin xác thực Khoá API để xác thực lưu lượng truy cập dịch vụ API Google Maps. Tài liệu này sẽ hướng dẫn bạn cách di chuyển từ việc sử dụng mã ứng dụng khách sang sử dụng khoá API.

Hãy làm theo các bước sau để bắt đầu:

1. Kiểm tra mức sử dụng mã ứng dụng khách hiện tại
2. Chuẩn bị khoá API
3. Xem xét chế độ cài đặt hạn mức
4. Cập nhật mã
5. Theo dõi lưu lượng truy cập mã ứng dụng khách
6. Tạm dừng mã ứng dụng khách

Kiểm tra mức sử dụng mã ứng dụng khách hiện tại

Trước khi bắt đầu quy trình di chuyển, hãy liệt kê những nội dung sau:

• Các Dịch vụ của Nền tảng Google Maps mà bạn đang sử dụng bằng mã ứng dụng khách.
• Các ứng dụng, trang web hoặc hệ thống mà bạn đang sử dụng bằng mã ứng dụng khách.

Google đã gửi một email thông báo cho những khách hàng bị ảnh hưởng về việc ngừng hoạt động mã ứng dụng khách vào tháng 5 năm 2025. Bạn cũng có thể tìm thấy thông tin này trong email thông báo.

Trên Cloud Console, bạn có thể kiểm tra trạng thái mới nhất về mức sử dụng Mã ứng dụng khách trên Trang chỉ số Google Maps

Đối với danh sách Dịch vụ của Nền tảng Google Maps:

1. Mở trang Chỉ số trên Cloud Console.
2. Lọc mức sử dụng của bạn bằng các chế độ cài đặt sau:
   • Thông tin xác thực: Chỉ chọn "project_number:<numerical identifier>" (số dự án:<mã nhận dạng dạng số).
3. Đặt bộ lọc sau.
   • Đã nhóm theo: API

Đối với các gợi ý về ứng dụng, trang web hoặc hệ thống:

Cloud Console không hiển thị thông tin chi tiết về các ứng dụng, trang web hoặc hệ thống của bạn. Tuy nhiên, bạn có thể tìm thấy một số gợi ý về nguồn lưu lượng truy cập Mã ứng dụng khách. Hãy làm theo các bước sau:

1. Mở trang Chỉ số trên Cloud Console.
2. Chọn một dịch vụ của Nền tảng Google Maps trong trình đơn thả xuống.
3. Lọc mức sử dụng của bạn bằng các chế độ cài đặt sau:
   • Thông tin xác thực: Chỉ chọn "project_number:<numerical identifier>" (số dự án:<mã nhận dạng dạng số).
4. Đặt bộ lọc sau.
   • Nhóm theo: Nền tảng hoặc Miền
5. Lặp lại từ bước 2 cho từng dịch vụ của Nền tảng Google Maps mà bạn cần kiểm tra lưu lượng truy cập.

Chuẩn bị khoá API

Tất cả mã ứng dụng khách đều được liên kết với một dự án trên đám mây của Google Cloud. Việc sử dụng khoá API từ dự án đó sẽ cho phép bạn truy cập vào các tính năng tương tự mà bạn đã truy cập trước đó bằng mã ứng dụng khách. Bạn nên di chuyển sang dự án được liên kết để tránh gặp vấn đề về hạn mức hoặc thiếu tính năng.

1. Tìm Dự án trên Cloud mà mã ứng dụng khách của bạn được liên kết:
   • Câu hỏi thường gặp về việc di chuyển cổng thông tin
2. Đảm bảo Dự án trên Cloud của bạn được liên kết với một Tài khoản thanh toán đang mở.
3. Tạo khoá API mới để di chuyển mã ứng dụng khách.
   • Bạn có thể sử dụng lại mọi khoá API hiện có trên Dự án trên Cloud.
   • Bạn có thể sử dụng nhiều khoá API từ cùng một Dự án trên Cloud, chẳng hạn như để tách lưu lượng truy cập cho từng dịch vụ của Nền tảng Google Maps hoặc để tách lưu lượng truy cập từ các nền tảng khác nhau (trình duyệt, ứng dụng di động, v.v.). Tham khảo hướng dẫn bảo mật để biết các phương pháp hay nhất về việc quản lý khoá API.

Bảo mật khoá API

Hãy nhớ bảo mật khoá API để bảo vệ khoá của bạn khỏi hành vi truy cập trái phép.

• Đặt quy tắc hạn chế ứng dụng cho khoá API (ví dụ: Trang web, địa chỉ IP, ứng dụng Android hoặc ứng dụng iOS).
• Đặt quy tắc hạn chế API cho khoá API.

Để biết thêm thông tin chi tiết, hãy xem hướng dẫn bảo mật của Google Maps Platform.

Đối với Maps JavaScript API, Maps Static API và Street View Static API, bạn có thể di chuyển các trang giới thiệu đáng tin cậy trên mã ứng dụng khách sang các quy tắc hạn chế đối với khoá API. Bạn có thể tìm thấy danh sách các trang giới thiệu đáng tin cậy trên Cloud Console.

Xem xét chế độ cài đặt hạn mức

Đảm bảo bạn có chế độ cài đặt hạn mức như mong đợi trên Dự án trên Cloud. Bạn chỉ cần thực hiện việc này nếu đang gọi các dịch vụ phía máy khách của Maps JavaScript API từ một mã ứng dụng khách. Bạn có thể kiểm tra và điều chỉnh chế độ cài đặt hạn mức trên Trang hạn mức của Google Maps.

Tìm hiểu thêm về báo cáo hạn mức

Tăng hạn mức cho các dịch vụ phía máy khách của Maps JavaScript API

Cảnh báo: Mức sử dụng mã ứng dụng khách trên các dịch vụ phía máy khách của Maps JavaScript API không tiêu thụ hạn mức dự án. Sau khi di chuyển sang khoá API, mức sử dụng của bạn sẽ tiêu thụ hạn mức dự án. Bạn nên đảm bảo có đủ hạn mức trước khi di chuyển.

Nếu đang sử dụng các dịch vụ sau trên Maps JavaScript API, bạn sẽ thấy mức sử dụng hạn mức tăng lên sau khi di chuyển khoá API.

Xem xét cấu hình hạn mức hiện tại, mức sử dụng hiện tại và điều chỉnh giới hạn hạn mức cho phù hợp.

1. Kiểm tra xem bạn có đang sử dụng các dịch vụ phía máy khách của Maps JavaScript API bằng mã ứng dụng khách hay không.
   • Mở trang Chỉ số trên Cloud Console.
   • Lọc mức sử dụng của bạn bằng các chế độ cài đặt sau:
     • Đã nhóm theo: Phương thức API
     • Thông tin xác thực: Chỉ chọn "project_number:<numerical identifier>" (số dự án:<mã nhận dạng dạng số).
   • Sau đó, bạn sẽ thấy danh sách Tên phương thức cùng với lưu lượng truy cập của phương thức đó trong biểu đồ "Lưu lượng truy cập theo phương thức API".

Phương thức API	Dịch vụ phía máy khách	Dịch vụ điều chỉnh hạn mức
google.routes.Directions.Javascript	Dịch vụ chỉ đường	Directions API
google.routes.DistanceMatrix.Javascript	Dịch vụ ma trận khoảng cách	Distance Matrix API
google.maps.Elevation.Javascript	Dịch vụ dữ liệu độ cao	API dữ liệu độ cao
google.places.Geocoding.Javascript	Dịch vụ mã hoá địa lý	Geocoding API
google.places.*.Javascript, ngoại trừ google.places.Geocoding.Javascript	Thư viện Places	Places API

• Nếu không sử dụng các phương thức API đó, bạn không cần lo lắng về chế độ cài đặt hạn mức, vì lưu lượng truy cập mã ứng dụng khách đã tiêu thụ hạn mức dự án.
• Ước tính mức sử dụng hạn mức mã ứng dụng khách
  • Đối với từng dịch vụ, hãy kiểm tra cả độ chi tiết Theo giây và Theo ngày.
  • Biểu đồ Theo giây: nhân lưu lượng truy cập cao điểm với 60 để biết nhu cầu về Hạn mức bổ sung mỗi phút.
  • Biểu đồ Theo ngày: Lưu lượng truy cập cao điểm phải là Hạn mức bổ sung mỗi ngày.
• Điều chỉnh hạn mức trên các dịch vụ tương ứng của Nền tảng Google Maps
  • Dựa trên tên phương thức mà bạn tìm thấy ở Bước 1, hãy điều chỉnh hạn mức trên các dịch vụ tương ứng.

Cập nhật mã

Thay thế tham số ứng dụng khách bằng tham số khoá

Cập nhật thông tin xác thực từ URL&client={value} thành URL&key={value} trong các lệnh gọi API GMP gửi đi. Nếu các ứng dụng của bạn đang sử dụng HTTP để truy cập vào các dịch vụ GMP, hãy cập nhật để sử dụng HTTPS.

Cập nhật tham số kênh để báo cáo

Bạn có thể theo dõi mức sử dụng theo từng kênh bằng cách chỉ định tham số kênh cho các yêu cầu API. Khoá API chỉ hỗ trợ các giá trị dạng số cho tham số kênh. Nếu đang sử dụng Mã ứng dụng khách với bất kỳ giá trị không phải dạng số nào cho tham số kênh, hãy cập nhật thành giá trị dạng số được hỗ trợ.

Xem phần Báo cáo của Google Maps Platform để biết thêm thông tin.

Xoá tham số chữ ký cho các dịch vụ web

Đối với các API Dịch vụ web sau đây, bạn không cần tham số chữ ký khi truy cập vào các API này bằng khoá API. Chỉ xoá tham số chữ ký khỏi các yêu cầu API.

• Directions API (Cũ)
• Distance Matrix API (Cũ)
• Geocoding API
• API dữ liệu độ cao
• Time Zone API

Xem phần Tổng quan về gói cao cấp để biết thêm thông tin.

Ký bí mật cho API Hình ảnh

Maps Static API và Street View Static API vẫn yêu cầu tham số chữ ký. Các API này chấp nhận một số ít yêu cầu không có chữ ký cho mục đích thử nghiệm, nhưng sẽ bắt đầu gặp lỗi khi đạt đến ngưỡng trong môi trường sản xuất. Thay thế bí mật ký từ bí mật cho mã ứng dụng khách thành bí mật cho khoá API. Bạn có thể sử dụng cùng một thuật toán ký, nhưng cần sử dụng một bí mật ký khác. Để tìm hiểu thêm, hãy xem bài viết Sử dụng chữ ký số.

Cảnh báo: Trước khi triển khai các thay đổi về mã vào môi trường sản xuất, hãy xác minh rằng chức năng đầu cuối không bị ảnh hưởng.

Theo dõi lưu lượng truy cập mã ứng dụng khách

Sau khi triển khai, hãy xác nhận rằng lưu lượng truy cập của bạn đã di chuyển thành công bằng trang tổng quan Cloud Console. Bạn sẽ bắt đầu thấy lưu lượng truy cập mã ứng dụng khách giảm xuống. Lưu lượng truy cập này được hiển thị ở định dạng "project_number:123456" (số dự án:123456) trên bảng điều khiển khi nhóm theo thông tin xác thực.

Tạm dừng mã ứng dụng khách

Nhà phát triển nên tạm dừng mã ứng dụng khách sau khi di chuyển. Việc này nhằm bảo vệ thông tin xác thực của bạn khỏi mọi lưu lượng truy cập không mong muốn và xác nhận rằng mọi mức sử dụng còn lại trên mã ứng dụng khách đều không quan trọng (ví dụ: thử nghiệm, bộ nhớ đệm, bot,...) và có thể trả về lỗi mà không gây ảnh hưởng đến hoạt động kinh doanh. Bạn có thể tạm dừng mã ứng dụng khách trên Cloud Console. Xem phần Tổng quan về quy trình xác thực gói cao cấp để biết thêm thông tin chi tiết.

Khắc phục sự cố

Làm cách nào để biết yêu cầu của chúng tôi có gặp lỗi hay không?

Bạn có thể kiểm tra số liệu thống kê về lỗi trên biểu đồ Mã phản hồi

Lỗi ApiNotActivatedMapError hoặc REQUEST_DENIED

Bạn sẽ thấy lỗi ApiNotActivatedMapError hoặc REQUEST_DENIED nếu chưa bật dịch vụ trên Dự án trên Cloud. Hãy làm theo hướng dẫn để bật dịch vụ.

Lỗi RefererNotAllowedMapError

Bạn sẽ thấy lỗi RefererNotAllowedMapError nếu miền nguồn của bạn chưa được thêm vào khoá API. Kiểm tra phần "Bảo mật khoá API" rồi thêm miền của bạn vào khoá API.

Lỗi OverQuotaMapError hoặc OVER_QUERY_LIMIT

Bạn sẽ thấy lỗi OverQuotaMapError hoặc OVER_QUERY_LIMIT nếu hạn mức đã định cấu hình không đủ để đáp ứng lưu lượng truy cập. Kiểm tra phần "Xem xét chế độ cài đặt hạn mức" rồi điều chỉnh hạn mức cho phù hợp.

Lỗi "Requests to this API must be over SSL" (Các yêu cầu gửi đến API này phải được thực hiện qua SSL)

Nếu bạn nhận được thông báo lỗi sau, hãy cập nhật các yêu cầu API từ "http://" thành "https://".

{
  "error_message" : "Requests to this API must be over SSL. Load the API with
  \"https://\" instead of \"http://\".",

  "results" : [],

  "status" : "REQUEST_DENIED"
}