使用 API 金鑰

本指南說明如何為 GCP 應用程式建立 API 金鑰以及設定 API 金鑰限制。如要進一步瞭解如何通過 GCP API 驗證，請參閱驗證總覽。如要瞭解如何為 Google 地圖設定 API 金鑰，請參閱 Google 地圖說明文件。

附註：除了下列所述的特定情況外，請勿將 API 金鑰用於本機或正式版應用程式。在幾乎所有情況下，您都應使用服務帳戶。

API 金鑰是一種簡易加密字串，可在呼叫某些不需要存取私人使用者資料的 API 時使用。在瀏覽器和沒有後端伺服器的行動應用程式等用戶端中，API 金鑰相當實用。API 金鑰可用於追蹤與專案配額和帳單相關聯的 API 要求。

API 金鑰具有重要限制，例如：

• 所有 GCP 服務都可以使用服務帳戶等憑證進行存取。不過，只有部分 GCP 服務允許只使用 API 金鑰進行存取，而不搭配其他憑證一起使用：

  • Google Cloud Natural Language API
  • Google Cloud Speech API
  • Google Cloud Translation API
  • Google Cloud Vision API
  • Google Cloud Endpoints
  • Google Cloud Billing Catalog API
  • Cloud Data Loss Prevention API

• API 金鑰不會識別發出 API 要求的使用者或應用程式，因此您無法限制特定使用者或服務帳戶的存取權。

• 其他人更容易發現和使用您的 API 金鑰。

綜合以上所述，我們建議您改用標準的驗證流程。不過，在少數情況下，使用 API 金鑰會是更適合的方案。例如，如果您正在開發一個行動應用程式，這個應用程式需要使用 Google Cloud Translation API 但不需要後端伺服器，則要通過該 API 的驗證，使用 API 金鑰會是最簡單的方法。大多數情況下，我們仍建議讓您的應用程式與後端伺服器通訊，由後端伺服器處理 Google Cloud Platform 服務的驗證與呼叫作業。

建立 API 金鑰

如要建立 API 金鑰，您必須在目前的專案中針對帳戶授予原始編輯者 (roles/editor) 角色。詳情請參閱原始角色。

如何建立 API 金鑰：

1. 在 GCP 主控台中，前往 API 和服務→憑證面板。

2. 選取 [建立憑證]，然後從下拉式選單中選取 [API 金鑰]。

3. 按一下 [建立] 按鈕。「已建立 API 金鑰」對話方塊中會顯示您新建立的金鑰。

您可以複製您的金鑰並妥善保管。除非您使用的是測試金鑰並將在稍後刪除，否則請加上應用程式和 API 金鑰限制。

使用 API 金鑰

使用以下格式，將 API 金鑰做為查詢參數傳遞至 REST API 呼叫。使用您的 API 金鑰取代 API_KEY：

key=API_KEY

比方說，如要傳遞 Cloud Natural Language API 要求 documents.analyzeEntities 的 API 金鑰：

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

保護 API 金鑰

在應用程式中使用 API 金鑰時，請務必妥善保管這些金鑰。 公開您的憑證可能會使您的帳戶遭到盜用，導致您的帳戶產生意外的費用。為協助確保您的 API 金鑰的安全，請遵循下列最佳做法：

• 不要直接在程式碼中嵌入 API 金鑰。嵌入程式碼中的 API 金鑰可能會意外公開。例如，您可能會忘記從分享出去的程式碼中移除金鑰。您可以將 API 金鑰儲存在環境變數或應用程式來源樹狀結構外的檔案中，而不要將它們嵌入應用程式中。

• 不要將 API 金鑰儲存在應用程式來源樹狀結構內的檔案中。如果您將 API 金鑰儲存在檔案中，請將檔案放在應用程式來源樹狀結構外，確保您的金鑰不會出現在原始碼控制系統中。 如果您使用公開原始碼管理系統 (例如 GitHub)，這項做法尤為重要。

• 設定應用程式和 API 金鑰限制。透過加上限制，可以減少 API 金鑰遭到盜用所造成的影響。

• 刪除不需要的 API 金鑰以盡量減少被攻擊的可能。

• 定期重新產生 API 金鑰。您可以在「Credentials」(憑證) 頁面上，針對每個金鑰按一下 [Regenerate key] (重新產生金鑰) 來重新產生 API 金鑰。然後，更新您的應用程式以使用新產生的金鑰。產生替代金鑰後，舊的金鑰可繼續使用 24 小時。

• 在公開釋出程式碼之前再檢查一次。在公開程式碼之前，請確保您的程式碼不包含 API 金鑰或任何其他私人資訊。

新增 API 金鑰限制

API 金鑰根據預設並沒有限制。未受限制的金鑰並不安全，因為所有人都可以公開檢視這些金鑰 (例如從瀏覽器內部)，或者在金鑰所在的裝置上存取這些金鑰。

對於正式版應用程式，請設定應用程式和 API 限制。

如何新增 API 金鑰限制：

1. 在 GCP 主控台中，前往 API 和服務→憑證面板。

2. 選取現有 API 金鑰的名稱。限制區段會顯示在頁面底部。

   

應用程式限制

應用程式限制可指定哪些網站、IP 位址或應用程式可以使用 API 金鑰。請根據應用程式類型新增應用程式限制。您只能為每個 API 金鑰設定一種限制類型。

1. 在「金鑰限制」區段中選取 [應用程式限制] 分頁標籤。

2. 根據您的應用程式需求選擇限制類型。如要針對任何限制新增多個值，請輸入第一個值，然後按下 Enter 鍵。重複以上動作以新增值。

   • 如果只是要用來測試，請使用「無」。

   • 針對在網路瀏覽器上執行的 API 用戶端使用 HTTP 參照網址，如此一來，只有指定的頁面才能呼叫 API。這些類型的應用程式會公開自己 API 金鑰，因此我們建議您改用服務帳戶。如需相關範例，請參閱新增 HTTP 限制。

   • 使用「IP 位址」來指定可存取 API 金鑰的 IP 位址。

   • 針對 Android 應用程式使用「Android 應用程式」。這個選項需要新增您的套件名稱和 SHA-1 簽署憑證指紋。

   • 針對 iOS 應用程式使用「iOS 應用程式」。這個選項需要新增至少一個 iOS 軟體包 ID 以指定可進行 API 呼叫的 iOS 軟體包。

3. 選取 [儲存] 按鈕。

新增 HTTP 限制

如何新增 HTTP 限制：

• 在表單欄位中輸入至少一個限制。

• 如果您的網域同時支援 HTTP 和 HTTPS，則必須分別新增這兩項限制。

• 如要新增多個值，請輸入第一個值，然後按下 Enter 鍵。重複以上動作以新增值。

  

• 您可以針對子網域和/或路徑選擇使用萬用字元 (*)。

下表顯示範例情境和限制，從上到下顯示最嚴格到最寬鬆的限制。建議您針對您的用途使用最嚴格的限制範例。

情境	限制
允許特定網址。	新增具有確切路徑的單一限制。例如： https://www.example.com/path http://www.example.com/path/path
允許單一子網域或裸名網域中的任何網址。	您必須設定至少兩個限制才能允許整個網域。 為網域設定限制，拿掉結尾的斜線。例如： https://www.example.com http://sub.example.com http://example.com 為網域設定第二個限制，路徑部分以萬用字元表示。例如： https://www.example.com/* http://sub.example.com/* http://example.com/* 如果您的網域同時允許 HTTP 和 HTTPS，則必須分別新增其他限制。
允許單一網域中的任何子網域網址。	您必須設定至少兩個限制。 為網域設定限制，子網域以萬用字元表示，並拿掉結尾的斜線。例如： https://*.example.com 為網域設定第二個限制，路徑部分以萬用字元表示。例如： https://*.example.com/* 如果您的網域同時允許 HTTP 和 HTTPS，則必須分別新增其他限制。

API 限制

API 限制指定了 API 金鑰可以呼叫哪些 API。正式版應用程式中使用的所有 API 金鑰都應使用 API 限制。

如何設定 API 限制：

1. 在「金鑰限制」區段中，選取 [API 限制] 分頁標籤。

2. 從下拉式選單中選取 API 名稱。

3. 針對您的 API 金鑰需要呼叫的所有 API 重複上述步驟。

4. 選取 [儲存] 按鈕。

查看現有的 API 金鑰

您可以使用 GCP 主控台來查看現有的 API 金鑰。在 GCP 主控台中前往「APIs & Services」(API 和服務) → 「Credentials」(憑證) 面板後，現有的 API 金鑰會顯示在「API keys」(API 金鑰) 標頭下方。

後續步驟

• 瞭解如何通過 GCP API 驗證。

• 瞭解如何為正式版應用程式設定驗證。

• 瞭解如何以使用者身分設定驗證。