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

Tổng quan

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ã ứng dụng khách
  6. Tạm dừng mã ứng dụng khách
  7. Tự kích hoạt lại Mã ứng dụng khách tạm thời

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 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 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ã ứ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ề 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. 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 của bạn 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 khách đều được liên kết với một dự án 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 giống như trước đây bạn đã truy cập 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 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 khách của bạn được liên kết:
  2. Đảm bảo Dự án trên đám mây 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 khách.
    • 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 trong cùng một Dự án trên đám mây, chẳng hạn như để tách biệt 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 biệt 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á của bạn khỏi bị truy cập trái phép.

  • Đặt quy tắc 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ế đối với 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 liên kết 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 trên đám mây. Bạn chỉ cần thực hiện thao tá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

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 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 đã sử dụng hạn mức dự án của bạ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 đồ Số yêu cầ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à nhu cầu về Hạn mức bổ sung mỗi ngày.
  • Điều chỉnh hạn mức của bạn trên 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 cho 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 đ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 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ố channel. 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 một giá trị bằng số được hỗ trợ.

Hãy 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 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 Tổng quan về gói Premium để biết thêm thông tin.

Khoá 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ý. Họ 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 các yêu cầu này sẽ bắt đầu không thành công khi đạt đến ngưỡng trong môi trường thực tế. Thay thế khoá bí mật ký của bạn từ khoá bí mật ký của mã ứng dụng khách thành khoá bí mật ký của 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 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 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 mã ứng dụng khách giảm xuống. Lưu lượng truy cập này sẽ xuất hiện ở định dạng "project_number:123456" trên trang tổng quan khi bạn bộ lọc nhóm theo thông tin đăng nhập.

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

Chúng tôi đặc biệt khuyên rằng các 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 đă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 khách trên Cloud Console. Hãy xem phần Tổng quan về việc xác thực gói Premium để biết thêm thông tin.

Tự kích hoạt lại tạm thời mã ứng dụng khách

Vì Mã ứng dụng khách của Google Maps Platform đã bước vào giai đoạn ngừng hoạt động theo từng giai đoạn vào tháng 5 năm 2026, nên chúng tôi không còn đảm bảo khả năng cung cấp dịch vụ nữa. Quyền truy cập sẽ bị hạn chế định kỳ trong quá trình chấm dứt dịch vụ theo lịch. Mặc dù dịch vụ thường được khôi phục tự động trong vòng vài giờ, nhưng bạn có thể chọn kích hoạt lại quyền truy cập theo cách thủ công nếu cần khôi phục ngay lập tức.

Để khẩn cấp khôi phục quyền truy cập, bạn có thể tự kích hoạt lại thông qua Google Cloud Console:

  • Chuyển đến trang Thông tin đăng nhập của Google Maps Platform.
  • Xác định vị trí Dự án trên đám mây cụ thể được liên kết với Mã ứng dụng khách của bạn.
  • Nhấp vào biểu tượng tiếp tục ở ngoài cùng bên phải của mục nhập để khôi phục dịch vụ.

Nếu bạn không thể nhanh chóng di chuyển sang khoá API và muốn được tạm thời miễn trừ khỏi các gián đoạn khác, vui lòng liên hệ với Nhóm hỗ trợ Nền tảng Google Maps kèm theo các thông tin sau:

  • ID khách hàng
  • Trường hợp sử dụng cụ thể
  • Ngày di chuyển mục tiêu
  • Đánh giá tác động đối với hoạt động kinh doanh

Báo cáo mức sử dụng mã ứng dụng khách – trong Báo cáo thanh toán

Việc kiểm tra Báo cáo thanh toán thay vì Chỉ số dự án có thể hữu ích cho những người dùng không có quyền truy cập vào chỉ số dự án (ví dụ: quản trị viên thanh toán, đặc biệt là Đối tác nền tảng của Nền tảng Maps). Mặc dù Báo cáo thanh toán có độ trễ từ 1 đến 2 ngày, nhưng báo cáo này có lợi ích là cho thấy thông tin chi tiết về mức sử dụng và chi phí trong hơn 30 ngày.

Bạn có thể theo dõi mức sử dụng Mã ứng dụng khách thông qua Google Cloud Console bằng cách làm theo các bước sau:

  1. Chuyển đến trang Thanh toán > Báo cáo trong Google Cloud Console.
  2. (Không bắt buộc, chỉ dành cho Đối tác) Áp dụng bộ lọc để chọn tài khoản thanh toán phụ mong muốn.
  3. Nhóm dữ liệu báo cáo theo khoá nhãn goog-maps-api-key-suffix. Nhãn này hiển thị các ký tự cuối của một khoá API.
  4. Xác định lưu lượng truy cập của mã ứng dụng khách bằng cách tìm các mục nhập thiếu hoặc trống nhãn goog-maps-api-key-suffix, vì nhãn này không được điền sẵn cho các yêu cầu về mã ứng dụng khách.
  5. Bỏ qua những SKU không được dùng để liên kết với các yêu cầu API, chẳng hạn như SKU gói thuê bao.

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 trê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 không được thêm vào khoá API. Kiểm tra phần "Bảo mật khoá API" và 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 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 xét 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"
}