Thiết lập Geocoding API

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Nếu địa chỉ thanh toán của bạn ở Khu vực kinh tế Châu Âu, thì kể từ ngày 8 tháng 7 năm 2025, Điều khoản dịch vụ của Google Maps Platform ở EEA sẽ áp dụng cho việc bạn sử dụng Dịch vụ. Chức năng có thể khác nhau tuỳ theo khu vực. Tìm hiểu thêm.

Tài liệu này mô tả các bước cần thiết để bắt đầu sử dụng Geocoding API.

1. Tài khoản và thanh toán Đảm bảo bạn đáp ứng các điều kiện tiên quyết.

2. Bật API Bật API trong dự án Google Cloud của bạn.

3. Đưa ra yêu cầu đầu tiên Định cấu hình khoá API hoặc OAuth để đưa ra yêu cầu API đã xác thực.

Lưu ý quan trọng: Hướng dẫn thiết lập này bao gồm quy trình định cấu hình khoá API và tạo mã thông báo OAuth. Chọn quy trình áp dụng cho môi trường triển khai của bạn.

Các sản phẩm của Nền tảng Google Maps được bảo mật khỏi việc sử dụng trái phép bằng cách yêu cầu các lệnh gọi API phải bao gồm một trong hai khoá API hoặc mã thông báo OAuth.

Khoá API Mã thông báo OAuth

Tạo mã thông báo OAuth

Geocoding API hỗ trợ việc sử dụng OAuth 2.0 để xác thực. Google hỗ trợ các trường hợp OAuth 2.0 phổ biến, chẳng hạn như các trường hợp dành cho máy chủ web.

Tài liệu này mô tả cách truyền mã thông báo OAuth đến lệnh gọi Geocoding API trong môi trường phát triển của bạn. Để biết hướng dẫn về cách sử dụng OAuth trong môi trường sản xuất, hãy xem Các phương thức xác thực tại Google.

Lưu ý:

Mặc dù có thể sử dụng trực tiếp Google Maps API bằng cách gửi yêu cầu API đến máy chủ, nhưng thư viện ứng dụng giúp đơn giản hoá đáng kể lượng mã bạn cần viết. Google Maps cung cấp thư viện ứng dụng cho nhiều ngôn ngữ lập trình, bao gồm cả Go, Java, Node.js và Python.

Hãy xem Thư viện ứng dụng Geocoding API để biết tài liệu và ví dụ.

Giới thiệu về OAuth

Có nhiều cách để tạo và quản lý mã thông báo truy cập bằng OAuth dựa trên môi trường triển khai của bạn.

Ví dụ: hệ thống Google OAuth 2.0 hỗ trợ các hoạt động tương tác giữa máy chủ với máy chủ, chẳng hạn như giữa ứng dụng của bạn và một dịch vụ của Google. Đối với trường hợp này, bạn cần có một tài khoản dịch vụ. Đây là tài khoản thuộc về ứng dụng của bạn chứ không phải thuộc về người dùng cuối cá nhân. Ứng dụng của bạn gọi các API của Google thay cho tài khoản dịch vụ, vì vậy, người dùng không trực tiếp tham gia. Để biết thêm thông tin về các phương thức xác thực, hãy xem bài viết Các phương thức xác thực tại Google.

Ngoài ra, bạn có thể sử dụng Geocoding API trong một ứng dụng di động Android hoặc iOS. Để biết thông tin chung về cách sử dụng OAuth với Geocoding API, bao gồm cả thông tin về cách quản lý mã truy cập cho các môi trường triển khai khác nhau, hãy xem phần Sử dụng OAuth 2.0 để truy cập vào các API của Google.

Giới thiệu về phạm vi OAuth

Để sử dụng OAuth với Geocoding API, bạn phải chỉ định phạm vi chính xác cho mã thông báo OAuth. Geocoding API hỗ trợ các phạm vi sau:

• https://www.googleapis.com/auth/maps-platform.geocode – Sử dụng với tất cả các điểm cuối của Geocoding API.
• https://www.googleapis.com/auth/maps-platform.geocode.address – Chỉ sử dụng với GeocodeAddress để chuyển đổi địa chỉ thành toạ độ.
• https://www.googleapis.com/auth/maps-platform.geocode.location – Chỉ sử dụng với GeocodeLocation để mã hoá địa lý ngược.
• https://www.googleapis.com/auth/maps-platform.geocode.place – Chỉ dùng với GeocodePlace để mã hoá địa lý vị trí.

Ngoài ra, bạn có thể sử dụng phạm vi https://www.googleapis.com/auth/cloud-platform chung cho tất cả các điểm cuối của Geocoding API. Phạm vi đó rất hữu ích trong quá trình phát triển vì đây là phạm vi mặc định được dùng khi tạo mã thông báo bằng gcloud.

Ví dụ: Thử các lệnh gọi API REST trong môi trường phát triển cục bộ

Nếu muốn dùng Geocoding API bằng mã thông báo OAuth nhưng chưa thiết lập môi trường để tạo mã thông báo, bạn có thể dùng quy trình trong phần này để thực hiện lệnh gọi.

Ví dụ này mô tả cách sử dụng mã thông báo OAuth do Thông tin xác thực mặc định của ứng dụng (ADC) cung cấp để thực hiện lệnh gọi. Để biết thông tin về cách sử dụng ADC để gọi các API của Google bằng thư viện ứng dụng, hãy xem phần Xác thực bằng thư viện ứng dụng.

Lưu ý: Quy trình gọi REST bên dưới không dành cho việc sử dụng trong môi trường sản xuất. Chỉ sử dụng quy trình này cho môi trường phát triển hoặc thử nghiệm.

Điều kiện tiên quyết

Trước khi bạn có thể thực hiện yêu cầu REST bằng ADC, hãy sử dụng Google Cloud CLI để cung cấp thông tin đăng nhập cho ADC:

1. Cài đặt và khởi chạy gcloud CLI.

2. Chạy lệnh gcloud sau đây trên máy cục bộ để tạo tệp thông tin đăng nhập:

   gcloud auth application-default login

3. Màn hình đăng nhập sẽ xuất hiện. Sau khi bạn đăng nhập, thông tin đăng nhập của bạn sẽ được lưu trữ trong tệp thông tin đăng nhập cục bộ mà ADC sử dụng.

Để biết thêm thông tin, hãy xem phần Thiết lập ADC cho môi trường phát triển cục bộ.

Đưa ra yêu cầu REST

Trong ví dụ này, bạn sẽ truyền 2 tiêu đề yêu cầu:

• Truyền mã thông báo OAuth trong tiêu đề Authorization bằng cách dùng lệnh sau để tạo mã thông báo:

  gcloud auth application-default print-access-token

  Mã thông báo được trả về có phạm vi là https://www.googleapis.com/auth/cloud-platform.

• Truyền mã nhận dạng hoặc tên của dự án Google Cloud đã bật tính năng thanh toán trong tiêu đề X-Goog-User-Project.

Ví dụ sau đây gọi đến Geocoding API bằng mã thông báo OAuth.

1. Chỉnh sửa trường PROJECT_ID để truyền mã nhận dạng của dự án Google Cloud.

   curl -X GET -H 'Content-Type: application/json' \
   -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
   

2. Nhấp vào biểu tượng sao chép trong mã mẫu, , để sao chép lệnh curl.
3. Dán lệnh vào cửa sổ dòng lệnh rồi chạy lệnh.

Phản hồi là một đối tượng JSON:

Khắc phục sự cố

Nếu yêu cầu của bạn trả về thông báo lỗi về việc API này không hỗ trợ thông tin đăng nhập của người dùng cuối, hãy xem phần Khắc phục sự cố khi thiết lập ADC.