Thiết lập Places Aggregate API

Tài liệu này mô tả các bước bạn cần thực hiện để bắt đầu sử dụng Places Aggregate API.

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

Quy trình này hướng dẫn bạn cách thiết lập Tài khoản Google Cloud và dự án trên đám mây của Google Cloud đã bật tính năng thanh toán. Bạn cũng nên nắm rõ cách tính phí khi sử dụng Places Aggregate API.

  1. Xem lại thông tin thanh toán và chi phí sử dụng tại Mức sử dụng và thông tin thanh toán của Places Aggregate API.

  2. Xác minh rằng bạn có Tài khoản Google Cloud.

    Đăng nhập vào Google Cloud Console

  3. Xác minh rằng bạn có một dự án trên đám mây của Google Cloud đã bật tính năng thanh toán.

    Chuyển đến trang Thanh toán
    1. Chọn dự án của bạn để mở trang Thanh toán.

    2. Trên trang Thanh toán:

      • Nếu bạn đã bật tính năng thanh toán cho dự án đã chọn và chỉ có một tài khoản thanh toán, thì trang Thanh toán sẽ mở ra.
      • Nếu bạn có nhiều tài khoản thanh toán, hãy chọn Chuyển đến tài khoản thanh toán được liên kết để xem thông tin chi tiết về tài khoản thanh toán liên kết với dự án.
      • Nếu tài khoản thanh toán tồn tại nhưng không được liên kết với dự án, thì bạn sẽ được nhắc liên kết tài khoản thanh toán với dự án.
      • Nếu không có tài khoản thanh toán nào hoặc bạn muốn tạo một tài khoản thanh toán mới, hãy chọn Quản lý tài khoản thanh toán để tạo một tài khoản thanh toán mới. Để biết thêm thông tin, hãy xem bài viết Tạo tài khoản thanh toán mới trên Cloud theo hình thức tự phục vụ.

Bật API

Trước khi có thể sử dụng Places Aggregate API, bạn phải dùng Google Cloud Console hoặc lệnh gcloud để bật API này trong dự án trên đám mây của Google Cloud.

Cách bật API:

Giao diện dòng lệnh

  1. Mở trang sản phẩm trong Google Cloud Console:

    Bật Places Aggregate API

  2. Nhấp vào nút Bật.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "areainsights.googleapis.com"

Đọc thêm về Google Cloud SDK, cách cài đặt Cloud SDK và các lệnh sau:

Lấy khoá API để sử dụng với Places Aggregate API

Các sản phẩm của Google Maps Platform được bảo vệ khỏi hành vi 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 khoá API hoặc mã thông báo OAuth. Quy trình khoá API được thực hiện trước tiên. Để sử dụng mã thông báo OAuth, hãy xem phần Tạo mã thông báo OAuth.

Khoá API là một chuỗi chữ và số riêng biệt liên kết tài khoản Cloud Billing và dự án Google Cloud của bạn với yêu cầu mà ứng dụng của bạn gửi đến một API hoặc SDK của Google Maps Platform. Để tạo khoá mới hoặc thêm API hay SDK vào khoá hiện có, hãy làm theo các hướng dẫn sau.

Giao diện dòng lệnh

  1. Chuyển đến trang Google Maps Platform > Khoá và thông tin xác thực.

    Chuyển đến trang Khoá và thông tin xác thực

  2. Nếu thấy lời nhắc, hãy chọn dự án của bạn.

  3. Thực hiện một trong các thao tác sau:

    • Tạo khoá mới:

      1. Nhấp vào Tạo thông tin xác thực > Khoá API.
      2. Trong bảng điều khiển Create API key (Tạo khoá API), hãy mở danh sách Select API restrictions (Chọn các quy định hạn chế đối với API).
      3. Xoá mọi API mà khoá này không cần, đồng thời đảm bảo rằng Places Aggregate API vẫn được chọn.
      4. Nhấp vào Tạo. Bảng điều khiển sẽ hiển thị khoá API mới của bạn.

    • Sử dụng khoá hiện có:

      1. Nhấp vào tên của khoá.
      2. Trong danh sách Select API restrictions (Chọn các quy định hạn chế về API), hãy chọn Places Aggregate API.
      3. Nhấp vào Lưu.

    Việc chọn một API ở đây không giúp bật API đó. Đảm bảo rằng bạn đã bật Places Aggregate API trên trang Thư viện API.

  4. Để xem chuỗi khoá sau này, hãy chuyển đến trang Khoá và thông tin xác thực rồi nhấp vào Hiện khoá cho khoá đó.

Nếu bảng điều khiển có giao diện khác với các bước này, hãy xem phần Tạo khoá API và Thêm quy định hạn chế về API trong tài liệu của Google Cloud.

gcloud

Thay thế PROJECT_ID bằng mã dự án của bạn trong các lệnh sau.

  • Tạo khoá mới: Chạy lệnh sau và thay thế DISPLAY_NAME bằng tên cho khoá. 

    gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=areainsights.googleapis.com

    Đọc thêm về Google Cloud SDK, cách cài đặt Cloud SDK và các lệnh sau:

  • Sử dụng khoá hiện có: Chạy lệnh sau và thay thế KEY_ID bằng mã nhận dạng của khoá. Cờ --append giữ lại các API mà khoá đã cho phép. Nếu không có, lệnh sẽ thay thế các tệp đó.

    gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=areainsights.googleapis.com

    Đọc thêm về Google Cloud SDK, cách cài đặt Cloud SDK và các lệnh sau:

    Mã khoá không phải là chuỗi khoá hoặc tên hiển thị. Để tìm tệp này, hãy chạy gcloud services api-keys list --project="PROJECT_ID". Mã nhận dạng là phần cuối cùng của trường name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

Để xem chuỗi khoá, hãy chạy gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

Tạo yêu cầu API

Ví dụ này cho thấy một yêu cầu trả về số lượng nhà hàng có giá vừa phải ở San Francisco.

  1. Nhấp vào API_KEY trong mã bên dưới để chèn chuỗi chữ và số của khoá:

    curl --location 'https://areainsights.googleapis.com/v1:computeInsights' \
--header 'X-Goog-Api-Key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
   "insights":[
      "INSIGHT_COUNT"
   ],
   "filter":{
      "locationFilter":{
         "region":{
            "place":"places/ChIJIQBpAG2ahYAR_6128GcTUEo"
         }
      },
      "typeFilter":{
         "includedTypes":[
            "restaurant"
         ]
      },
      "priceLevels":[
         "PRICE_LEVEL_INEXPENSIVE"
      ]
   }
}'
  2. Nhấp vào biểu tượng sao chép trong mã mẫu, Chọn biểu tượng sao chép., để 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 ở dạng:

{
  "count": "1025"
}

Áp dụng các quy tắc hạn chế đối với khoá API

Google đặc biệt khuyến khích bạn hạn chế khoá API bằng cách chỉ cho phép các API và ứng dụng cần thiết sử dụng khoá API. Việc hạn chế khoá API giúp tăng cường bảo mật cho ứng dụng của bạn bằng cách bảo vệ ứng dụng khỏi các yêu cầu không mong muốn. Khoá API hỗ trợ hai loại quy định hạn chế:

Để biết thêm thông tin về cách áp dụng các quy tắc hạn chế, hãy xem bài viết Hạn chế khoá API.

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

Places Aggregate API hỗ trợ 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 cho máy chủ web.

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

Bạn có thể gọi trực tiếp các API Google Maps bằng cách gửi yêu cầu API đến máy chủ hoặc có thể sử dụng thư viện ứng dụng để đơn giản hoá mã. Google Maps cung cấp thư viện ứng dụng cho Go, Java, Node.js và Python. Để biết thêm thông tin, hãy xem Thư viện ứng dụng API Places Aggregate.

Tổng quan về OAuth

Bạn có thể tạo và quản lý mã truy cập bằng OAuth theo một số cách, tuỳ thuộc vào môi trường triển khai của bạn.

Bạn có thể sử dụng OAuth 2.0 cho các hoạt động tương tác giữa máy chủ với máy chủ giữa ứng dụng của bạn và một dịch vụ của Google. Trong trường hợp này, bạn sử dụng một tài khoản dịch vụ được liên kết với ứng dụng của bạn thay vì một người dùng cá nhân. Bạn có thể đưa ra yêu cầu API bằng tài khoản dịch vụ mà không cần người dù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ể tích hợp Places Aggregate API vào một ứng dụng di động Android hoặc iOS. Để biết thêm thông tin về cách sử dụng OAuth và quản lý mã truy cập cho các môi trường triển khai khác nhau, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập vào API của Google.

Phạm vi OAuth

Để sử dụng OAuth với Places Aggregate API, bạn phải chỉ định mã thông báo OAuth cho phạm vi sau:

https://www.googleapis.com/auth/cloud-platform

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 bạn không có môi trường tạo mã thông báo và muốn thử dùng Places Aggregate API bằng mã thông báo OAuth, hãy làm theo quy trình trong phần này.

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êm thông tin về cách sử dụng ADC để gọi API của Google bằng thư viện ứng dụng, hãy xem bài viết Xác thực bằng thư viện ứng dụng.

Chỉ sử dụng quy trình REST sau đây cho mục đích phát triển hoặc thử nghiệm, không dùng cho môi trường thực tế.

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

Trước khi bạn gửi yêu cầu REST bằng ADC, hãy sử dụng CLI gcloud để cung cấp thông tin xác thực cho ADC:

  1. Cài đặt và khởi chạy CLI gcloud. Để biết thêm thông tin, hãy xem bài viết Cài đặt gcloud CLI.

  2. Xác thực bằng CLI gcloud:

    gcloud auth application-default login

  3. Hoàn tất quy trình đăng nhập để lưu thông tin đăng nhập vào 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 bài viết Thiết lập ADC cho môi trường phát triển cục bộ.

Tạo yêu cầu REST

Trong ví dụ này, bạn truyền hai tiêu đề của yêu cầu:

  • Truyền mã thông báo OAuth trong tiêu đề Authorization bằng cách sử 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 trên đám mây Google Cloud đã bật tính năng thanh toán trong tiêu đề X-Goog-User-Project.

Để gọi Places Aggregate API bằng mã thông báo OAuth, hãy hoàn tất các bước sau:

  1. Trong mã mẫu sau, hãy thay thế PROJECT_NUMBER_OR_ID bằng số hoặc mã dự án trên đám mây của bạn trên Google Cloud.

    Ví dụ này cho thấy một yêu cầu trả về số lượng nhà hàng ở San Francisco có giá vừa phải:

    curl -X POST 'https://areainsights.googleapis.com/v1:computeInsights' \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data '{
"insights":[
  "INSIGHT_COUNT"
],
"filter":{
  "location_filter":{
     "region":{
        "place":"places/ChIJIQBpAG2ahYAR_6128GcTUEo"
     }
  },
  "type_filter":{
     "included_types":[
        "restaurant"
     ]
  },
  "price_levels":[
     "PRICE_LEVEL_INEXPENSIVE"
  ]
}
}'

  2. Để sao chép lệnh curl, hãy nhấp vào Sao chép trong mã mẫu.

  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:

{
  "count": "1025"
}

Khắc phục sự cố

Nếu yêu cầu của bạn trả về một thông báo lỗi cho biết API này không hỗ trợ thông tin xác thực 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.

Bước tiếp theo

Giờ đây, bạn đã bật Places Aggregate API và gửi yêu cầu thành công, hãy xem bài viết Gửi yêu cầu đầu tiên để tìm hiểu thêm về cách sử dụng API này.