歡迎參加 12 月在舊金山舉辦的 Google Maps Platform 開發人員社群日！立即報名參加。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定 Places API (新版)

歐洲經濟區 (EEA) 開發人員

本文說明開始使用 Places API (新版) 的必要步驟。

必要條件

本程序將引導您設定 Google Cloud 帳戶和已啟用計費功能的 Google Cloud 專案。此外，您也應熟悉 Places API (新版) 的計費方式。

查看 Places API (新版) 的帳單和用量費用，詳情請參閱「Places API (新版) 用量與計費」。
確認您有 Google Cloud 帳戶。
登入 Google Cloud 控制台
注意： 如果您是新使用者，且沒有 Google Cloud 帳戶，因此無法登入控制台，請參閱「開始使用 Google Maps Platform」一文。
確認您有已啟用計費功能的 Google Cloud 雲端專案。
前往「帳單」頁面
注意： 如果您是新使用者，且沒有 Google Cloud 專案，請參閱「開始使用 Google 地圖平台」一文。

選取專案，開啟「Billing」(帳單) 頁面。
在「帳單」頁面中：
- 如果所選專案已啟用計費功能，且您只有一個帳單帳戶，系統會開啟「Billing」(帳單) 頁面。
- 如果您有多個帳單帳戶，請選取「前往連結的帳單帳戶」，查看與專案相關聯的帳單帳戶詳細資料。
- 如果已有帳單帳戶，但尚未與專案建立關聯，系統會提示您將帳單帳戶連結至專案。
- 如果沒有帳單帳戶，或想建立新的帳單帳戶，請選取「Manage Billing Accounts」(管理帳單帳戶)，建立新的帳單帳戶。詳情請參閱「建立新的自助式 Cloud Billing 帳戶」。

啟用 API

您必須先使用 Google Cloud 控制台或 gcloud 指令，在 Google Cloud 雲端專案中啟用 Places API (新版)，才能使用該 API。

啟用 API：

控制台

在 Google Cloud 控制台中開啟產品頁面：
啟用 Places API (新版)
點選「啟用」按鈕。

注意：如果 API 已啟用，系統會顯示「管理」按鈕，而非「啟用」。

gcloud

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

進一步瞭解 Google Cloud SDK、Cloud SDK 安裝和下列指令：

取得 API 金鑰，以便與 Places API (新版) 搭配使用

Google Maps Platform 產品會要求 API 呼叫必須包含 API 金鑰或 OAuth 權杖，以防未經授權的使用行為。首先是 API 金鑰程序。如要改用 OAuth 權杖，請參閱「建立 OAuth 權杖」。

API 金鑰是不重複的英數字串，可將 Cloud Billing 帳戶和 Google Cloud 專案，與應用程式向 Google Maps Platform API 或 SDK 提出的要求建立關聯。如要建立新金鑰，或將 API/SDK 新增至現有金鑰，請按照下列操作說明進行。

控制台

前往「Google Maps Platform」>「金鑰和憑證」頁面。

前往「Keys & Credentials」(金鑰和憑證) 頁面
如果出現系統提示，請選取您的專案。
請執行下列任一步驟：
- 建立新金鑰：
  1. 依序按一下 [Create credentials] (建立憑證) > [API key] (API 金鑰)。
  2. 在「建立 API 金鑰」面板中，開啟「選取 API 限制」清單。
  3. 清除這個金鑰不需要的所有 API，並確認 Places API (新版) 仍處於選取狀態。
  4. 按一下「建立」，面板會顯示新的 API 金鑰。
- 使用現有金鑰：
  1. 按一下金鑰名稱。
  2. 在「選取 API 限制」清單中，選取「Places API (New)」。
  3. 按一下 [儲存]。
在這裡選取 API 並不會啟用該 API。請務必在 API 程式庫頁面啟用 Places API (新版)。
如要日後查看金鑰字串，請前往「金鑰和憑證」頁面，然後按一下金鑰的「顯示金鑰」。

如果控制台與這些步驟不同，請參閱 Google Cloud 說明文件中的「建立 API 金鑰」和「新增 API 限制」。

gcloud

在下列指令中，將 PROJECT_ID 替換為您的專案 ID。

建立新金鑰：執行下列指令，並將 DISPLAY_NAME 替換為金鑰名稱。
```
gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=places.googleapis.com
```
進一步瞭解 Google Cloud SDK、Cloud SDK 安裝和下列指令：
- gcloud services api-keys create
使用現有金鑰：執行下列指令，並將 KEY_ID 替換為金鑰 ID。--append 旗標會保留金鑰已允許的 API。如果沒有這項參數，指令會替換這些執行個體。
```
gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=places.googleapis.com
```
進一步瞭解 Google Cloud SDK、Cloud SDK 安裝和下列指令：
- gcloud services api-keys update
- gcloud services api-keys list
金鑰 ID 不是金鑰字串或顯示名稱。如要找出這個值，請執行 gcloud services api-keys list --project="PROJECT_ID"。ID 是 name 欄位的最後一部分：projects/PROJECT_NUMBER/locations/global/keys/KEY_ID。

如要查看金鑰字串，請執行 gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID"。

提出 API 要求

提出 Places API (新版) 要求，針對「Spicy Vegetarian Food in Sydney, Australia」字串進行 Text Search，並傳回 JSON 回應。每個要求都必須包含 API 金鑰的英數字串，且包含 API 金鑰的要求必須使用 HTTPS。

按一下下方程式碼中的 API_KEY，插入金鑰的英數字串：

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

按一下程式碼範例中的複製圖示，複製 curl 指令。
在終端機視窗中貼上並執行指令。

回應是 JSON 物件，格式如下：

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegan_restaurant",
        "vegetarian_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "addressComponents": [
        {
          "longText": "29",
          "shortText": "29",
          "types": [
            "street_number"
          ],
          "languageCode": "en-US"
        },
  ...
}

套用 API 金鑰限制

Google 強烈建議您設定限制，只允許將 API 金鑰用於需要金鑰的 API 和應用程式。限制 API 金鑰可避免不必要的請求使用 API 金鑰，有助提升應用程式的安全性。API 金鑰支援兩種限制：

API 限制：指定可使用 API 金鑰呼叫的 SDK 和 API。建立金鑰時，控制台和 gcloud CLI 至少需要一項 API 限制。
應用程式限制：指定哪些網站、IP 位址或應用程式可以使用 API 金鑰。

如要進一步瞭解如何套用限制，請參閱「限制 API 金鑰」。

建立 OAuth 權杖

Places API (新版) 支援 OAuth 2.0 驗證。Google 支援常見的 OAuth 2.0 情境，例如網路伺服器情境。

本文說明如何在開發環境中，將 OAuth 權杖傳遞至 Places API (新版) 呼叫。如要進一步瞭解如何在正式環境中使用 OAuth，請參閱「Google 的驗證方式」。

您可以直接向伺服器發出 API 要求，呼叫 Google Maps API，也可以使用用戶端程式庫簡化程式碼。Google 地圖提供 Go、Java、Node.js 和 Python 適用的用戶端程式庫。詳情請參閱「Places API (新版) 用戶端程式庫」。

OAuth 總覽

您可以根據部署環境，透過多種方式使用 OAuth 建立及管理存取權杖。

您可以使用 OAuth 2.0，在應用程式和 Google 服務之間進行伺服器對伺服器互動。在這種情況下，您會使用與應用程式 (而非個別使用者) 相關聯的服務帳戶。您可以使用服務帳戶提出 API 要求，不必直接涉及使用者。如要進一步瞭解驗證方式，請參閱「Google 的驗證方式」。

或者，您也可以將 Places API (新版) 整合至 Android 或 iOS 行動應用程式。如要進一步瞭解如何使用 OAuth，以及管理不同部署環境的存取權杖，請參閱「使用 OAuth 2.0 存取 Google API」。

OAuth 範圍

如要搭配使用 OAuth 和 Places API (新版)，您必須為 OAuth 權杖指派下列範圍：

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

範例：在本機開發環境中試用 REST API 呼叫

如果您沒有可產生權杖的環境，但想使用 OAuth 權杖試用 Places API (新版)，請按照本節中的程序操作。

這個範例說明如何使用應用程式預設憑證 (ADC) 提供的 OAuth 權杖發出呼叫。如要進一步瞭解如何使用 ADC 搭配用戶端程式庫呼叫 Google API，請參閱「使用用戶端程式庫進行驗證」。

下列 REST 程序僅適用於開發或測試，不適用於正式環境。

必要條件

使用 ADC 發出 REST 要求前，請先透過 gcloud CLI 將憑證提供給 ADC：

安裝並初始化 gcloud CLI。詳情請參閱「安裝 gcloud CLI」。
使用 gcloud CLI 進行驗證：
```
gcloud auth application-default login
```
完成登入程序，將憑證儲存在 ADC 使用的本機憑證檔案中。

詳情請參閱「為本機開發環境設定 ADC」。

提出 REST 要求

在這個範例中，您會傳遞兩個要求標頭：

使用下列指令產生權杖，在 Authorization 標頭中傳遞 OAuth 權杖：

gcloud auth application-default print-access-token

傳回的權杖範圍為 https://www.googleapis.com/auth/cloud-platform。
在 X-Goog-User-Project 標頭中，傳遞已啟用計費功能的 Google Cloud 雲端專案 ID 或名稱。

如要使用 OAuth 權杖呼叫 Places API (新版)，請完成下列步驟：

在下列程式碼範例中，將 PROJECT_ID 替換為您的 Google Cloud 專案 ID：

curl -X POST -d '{
"textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress" \
"https://places.googleapis.com/v1/places:searchText"

如要複製 curl 指令，請按一下程式碼範例中的「Copy」(複製)。
將指令貼到終端機視窗中，然後執行。

回應為 JSON 物件：

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegan_restaurant",
        "vegetarian_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "addressComponents": [
        {
          "longText": "29",
          "shortText": "29",
          "types": [
            "street_number"
          ],
          "languageCode": "en-US"
        },
  ...
}

疑難排解

如果要求傳回錯誤訊息，指出這個 API 不支援使用者憑證，請參閱「排解 ADC 設定問題」。

後續步驟

您已啟用 Places API (新版) 並設定 API 金鑰，請參閱「Places API (新版) 簡介」，進一步瞭解如何使用 Places API (新版)。

設定 Places API (新版) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

必要條件

啟用 API

控制台

gcloud

取得 API 金鑰，以便與 Places API (新版) 搭配使用

控制台

gcloud

提出 API 要求

套用 API 金鑰限制

建立 OAuth 權杖

OAuth 總覽

OAuth 範圍

範例：在本機開發環境中試用 REST API 呼叫

必要條件

提出 REST 要求

疑難排解

後續步驟

設定 Places API (新版)