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 Maps Platform sẽ ngừng hoạt động 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, bạn phải sử dụng thông tin đăng nhập Khoá API để xác thực lưu lượng truy cập dịch vụ Google Maps API. Hướng dẫn này sẽ hướng dẫn bạn cách di chuyển từ việc sử dụng mã ứng dụng 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 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 theo mã nhận dạng khách hàng
  6. Tạm dừng mã ứng dụng khách

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

Trước khi bắt đầu quá trình di chuyển, hãy liệt kê những thông tin sau:

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

Google đã gửi email thông báo cho những khách hàng bị ảnh hưởng về việc ngừng sử dụng mã nhận dạng ứng dụng 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ề việc sử dụng Mã ứng dụng khách trên Trang chỉ số Google Maps

Để xem danh sách Dịch vụ của Nền tảng Maps:

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

Đối với 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 của 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ụ Maps Platform trong trình đơn thả xuống.
  3. Lọc mức sử dụng bằng các chế độ cài đặt sau:
    • Thông tin đăng nhập: Chỉ chọn "project_number:<numerical identifier>".
  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 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 đều được liên kết với một dự án trên Google Cloud và việc sử dụng khoá API từ dự án đó sẽ cho phép bạn truy cập vào những tính năng mà trước đây bạn đã truy cập bằng mã ứng dụng. Bạn nên di chuyển sang dự án được liên kết để tránh gặp phải vấn đề về hạn mức hoặc thiếu tính năng.

  1. Tìm Dự án trên đám mây mà mã ứng dụng của bạn được liên kết:
  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.
    • Bạn có thể dùng lại mọi khoá API hiện có trên Dự án trên đám mây.
    • Bạn có thể sử dụng nhiều khoá API từ cùng một Dự án trên đám mây, 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 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 của bạn (ví dụ: Trang web, địa chỉ IP, ứng dụng Android hoặc ứng dụng iOS).
  • Đặt các quy tắc hạn chế đối với API cho khoá API.

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

Đố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 đơn vị giới thiệu đáng tin cậy trên Cloud Console.

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

Đảm bảo bạn có chế độ cài đặt hạn mức dự kiến trên dự á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

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

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 bằng các chế độ cài đặt sau:
      • Được nhóm theo: Phương thức API
      • Thông tin đăng nhập: Chỉ chọn "project_number:<numerical identifier>".
    • 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ụ độ cao

Elevation API

google.places.Geocoding.Javascript

Dịch vụ mã hoá địa lý

Geocoding API

google.places.*.Javascript, ngoại trừ google.places.Geocoding.Javascript

Places Library

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 của bạn đã tiêu thụ hạn mức dự án.
  • Ước tính mức sử dụng hạn mức mã nhận dạng ứng dụng khách
    • Đối với mỗi dịch vụ, hãy kiểm tra cả độ chi tiết Theo giây và Theo ngày.
    • Biểu đồ Mỗi giây: nhân lưu lượng truy cập cao điểm với 60 để có thêm Hạn mức mỗi phút cần thiết.
    • Biểu đồ mỗi ngày: Lưu lượng truy cập cao nhất phải là hạn mức bổ sung cần thiết mỗi ngày.
  • Điều chỉnh hạn mức cho các dịch vụ tương ứng của Nền tảng 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ố máy 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 ứ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 thông 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ị bằng số cho tham số kênh. Nếu bạn đang sử dụng Mã ứng dụng khách với bất kỳ giá trị không phải là số nào cho tham số kênh, hãy cập nhật giá trị đó thành giá trị bằng số được hỗ trợ.

Hãy xem phần Báo cáo của Nền tảng Google Maps để 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 của bạn.

  • Directions API (Cũ)
  • Distance Matrix API (Cũ)
  • Geocoding API
  • Elevation API
  • Time Zone API

Hãy xem bài viết Tổng quan về gói Premium để biết thêm thông tin.

Khoá bí mật để ký cho Imagery API

Maps Static API và Street View Static API vẫn yêu cầu tham số chữ ký. Họ chấp nhận một số ít yêu cầu không có chữ ký cho mục đích kiểm thử, nhưng các yêu cầu này sẽ bắt đầu không thành công khi đạt đến ngưỡng trong quá trình phát hành công khai. Thay thế khoá bí mật ký của bạn từ khoá bí mật ký cho mã ứng dụng khách thành khoá bí mật ký cho khoá API. Bạn có thể sử dụng cùng một thuật toán ký, nhưng bạn cần sử dụng một khoá 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ố.

Theo dõi lưu lượng truy cập theo mã nhận dạng ứng dụng

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

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

Nhà phát triển nên tạm dừng mã nhận dạng ứng dụng khách sau khi di chuyển. Mục đích là để bảo vệ thông tin đăng nhập 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 của bạn đề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 của mình trên Cloud Console. Hãy xem bài viết Tổng quan về việc xác thực gói Premium để 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 ta có thất bạ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

ApiNotActivatedMapError hoặc REQUEST_DENIED lỗi

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 đám mây của mình. Làm theo hướng dẫn để bật dịch vụ.

RefererNotAllowedMapError lỗi

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 mục "Bảo mật khoá API" và thêm miền của bạn vào khoá API.

OverQuotaMapError hoặc OVER_QUERY_LIMIT lỗi

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

Lỗi "Yêu cầu đến API này phải qua SSL"

Nếu bạn nhận được thông báo lỗi sau, hãy cập nhật 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"
}