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

Tổng quan

Để tăng cường độ tin cậy và bảo mật cho quy trình xác thực, chúng tôi sẽ ngừng sử dụng mã ứng dụng của Nền tảng Maps kể từ ngày 26 tháng 5 năm 2025 và không thể sử dụng mã này 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 xác thực Khoá API để xác thực lưu lượng truy cập dịch vụ API Google Maps. 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 lại 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ã ứng dụng
  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 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 với 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 các khách hàng chịu ảnh hưởng về việc ngừng sử dụng mã ứ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 của việc sử dụng Mã ứng dụng trên Trang chỉ số của Google Maps

Để biết 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 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>".
  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ề ứ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ụ của Nền tảng 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>".
  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ụ trên 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. Việc sử dụng khoá API từ dự án đó sẽ cấp cho bạn quyền truy cập vào các 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 các 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 Google Cloud của bạn được liên kết với một Tài khoản thanh toán đang hoạt động.
  3. Tạo khoá API mới để di chuyển mã ứng dụng.
    • Bạn có thể sử 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ư để phân tách lưu lượng truy cập cho từng dịch vụ trên Nền tảng Maps hoặc để phân 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.). Hãy tham khảo hướng dẫn bảo mật để biết các phương pháp hay nhất về quản lý khoá API.

Bảo mật khoá API

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

  • Đặt hạn chế về ứng dụng cho khoá API (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ế API cho khoá API.

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

Đối với API JavaScript của Maps, API tĩnh của Maps và API tĩnh của Chế độ xem đường phố, bạn có thể di chuyển các trình giới thiệu đáng tin cậy trên mã ứng dụng của mình 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 trình 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 đã thiết lập hạn mức dự kiến trên Dự án trên Google Cloud. Bạn chỉ cần làm việc này nếu đang gọi các dịch vụ phía ứng dụng khách của API JavaScript của Maps 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 API Maps JavaScript

Nếu đang sử dụng các dịch vụ sau trên API JavaScript của Maps, 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 lại 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 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 API JavaScript của Maps 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>".
    • 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

Thư viện địa điểm

Places API
  • Nếu không sử dụng các phương thức API đó, bạn không cần phải lo lắng về chế độ cài đặt hạn mức vì lưu lượng truy cập mã ứng dụng của bạn đã sử dụng hạn mức dự án.
  • Ước tính mức sử dụng hạn mức mã ứng dụng của bạn
    • Đối với từng dịch vụ, hãy kiểm tra cả mức độ chi tiết Mỗi giây và Mỗi ngày.
    • Biểu đồ Mỗi 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 mỗi phút bổ sung.
    • Biểu đồ Mỗi ngày: Lưu lượng truy cập cao nhất phải là nhu cầu về Định 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 Maps Platform
    • Dựa trên tên phương thức mà bạn tìm thấy trong 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ã

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 đ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 ứng dụng để sử dụng HTTPS.

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

Đối với API Dịch vụ web (*), bạn không cần thông số chữ ký khi truy cập vào các API đó 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
  • 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.

Mã thông báo bí mật ký 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 dịch vụ này 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 sẽ bắt đầu từ chối khi đạt đến ngưỡng trong phiên bản phát hành công khai. Thay thế khoá ký của bạn từ khoá cho mã ứng dụng khách thành khoá 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 khoá ký bí mật khác. Để tìm hiểu thêm, hãy xem phần Sử dụng chữ ký số.

Theo dõi lưu lượng truy cập theo mã khách hà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 đã di chuyển thành công bằng cách sử dụng trang tổng quan của Cloud Console. Bạn sẽ bắt đầu thấy lưu lượng truy cập theo mã ứng dụng giảm xuống. Lưu lượng truy cập này hiển thị ở định dạng "project_number:123456" trên trang tổng quan 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 sau khi di chuyển. Mục đích của việc này là 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 ngoài ý muốn và xác nhận rằng mọi hoạt động sử dụng còn lại trên mã ứng dụng của bạn đều không quan trọng (ví dụ: kiểm thử, bộ nhớ đệm, bot, v.v.) 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. Hãy xem bài viết Tổng quan về quy trình xác thực của 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ành công 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ụ này trên Dự án trên đám mây. 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 không được thêm vào khoá API. Đánh dấu vào mục "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 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 của bạn. Kiểm tra mục "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 gửi đế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 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"
}