設定 Time Zone API

本文說明開始使用 Time Zone API 的必要步驟。

必要條件

本程序將引導您設定 Google Cloud 帳戶和已啟用計費功能的 Google Cloud 專案。 您也應熟悉 Time Zone API 的計費方式。

  1. 如要查看用量計費和費用，請參閱「Time Zone API 用量與計費」一文。

  2. 確認您有 Google Cloud 帳戶。

    登入 Google Cloud 控制台

  3. 確認您有已啟用計費功能的 Google Cloud 雲端專案。

    前往「帳單」頁面
    1. 選取專案，開啟「Billing」(帳單) 頁面。

    2. 在「帳單」頁面中：

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

啟用 API

您必須先使用 Google Cloud 控制台或 gcloud 指令，在 Google Cloud 專案中啟用 Time Zone API，才能使用這項 API。

啟用 API：

控制台

  1. 在 Google Cloud 控制台中開啟產品頁面：

    啟用 Time Zone API

  2. 點選「啟用」按鈕。

gcloud

gcloud services enable \
    --project "PROJECT" \
    "timezone-backend.googleapis.com"

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

取得 API 金鑰，以便與 Time Zone API 搭配使用

Google 地圖平台產品會要求 API 呼叫必須包含 API 金鑰，以防未經授權使用。

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

控制台

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

    前往「Keys & Credentials」(金鑰和憑證) 頁面

  2. 如果出現系統提示，請選取您的專案。

  3. 請執行下列任一步驟：

    • 建立新金鑰：

      1. 依序按一下 [Create credentials] (建立憑證) > [API key] (API 金鑰)。
      2. 在「建立 API 金鑰」面板中，開啟「選取 API 限制」清單。
      3. 清除這個金鑰不需要的所有 API，並確認「Time Zone API」仍處於選取狀態。
      4. 按一下「建立」，面板會顯示新的 API 金鑰。

    • 使用現有金鑰：

      1. 按一下金鑰名稱。
      2. 在「Select API restrictions」清單中，選取「Time Zone API」。
      3. 按一下 [儲存]。

    在這裡選取 API 並不會啟用該 API。確認 Time Zone API 已在 API 程式庫頁面啟用。

  4. 如要日後查看金鑰字串，請前往「金鑰和憑證」頁面，然後按一下金鑰的「顯示金鑰」。

如果控制台與這些步驟不同，請參閱 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=timezone-backend.googleapis.com

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

  • 使用現有金鑰：執行下列指令，並將 KEY_ID 替換為金鑰 ID。--append 旗標會保留金鑰已允許的 API。如果沒有這項參數，指令會替換這些執行個體。

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

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

    金鑰 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 要求

向 Time Zone API 傳送要求，傳回包含美國內華達州時區資訊的 JSON 回應。時間戳記設為 2024 年 12 月 5 日。每個要求都必須包含 API 金鑰的英數字串，且包含 API 金鑰的要求必須使用 HTTPS。

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

    curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510&timestamp=1733428634&key=YOUR_API_KEY'
  2. 按一下程式碼範例中的複製圖示 選取「複製」圖示。，複製 curl 指令。
  3. 在終端機視窗中貼上並執行指令。

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

{
   "dstOffset" : 0,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Standard Time"
}

套用 API 金鑰限制

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

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

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

後續步驟

您已啟用 Time Zone API 並成功提出要求，接著請參閱「Time Zone 要求和回應」，進一步瞭解如何使用 API。