瞭解如何使用及管理 Firebase 的 API 金鑰

API 金鑰是一組專屬字串，可用於在與 Firebase 和 Google 服務互動時，將要求路由至 Firebase 專案。本頁面說明 API 金鑰的基本資訊，以及透過 Firebase 應用程式使用及管理 API 金鑰的最佳做法。

API 金鑰和 Firebase 的一般資訊

Firebase 的 API 金鑰與一般 API 金鑰不同

與 API 金鑰的一般用途不同，Firebase 服務的 API 金鑰不用於控制後端資源的存取權，這項功能只能透過 Firebase Security Rules (用於控制哪些使用者可以存取資源) 和 Firebase App Check (用於控制哪些應用程式可以存取資源) 來執行。

通常，您需要小心保護 API 金鑰 (例如使用保險庫服務或將金鑰設為環境變數)；不過，Firebase 服務的 API 金鑰可納入程式碼或已簽入的設定檔。

雖然 Firebase 服務的 API 金鑰可安全地納入程式碼，但您仍應檢查並套用適當的限制。

建立 API 金鑰

Firebase 專案可以有多個 API 金鑰，但每個 API 金鑰只能與單一 Firebase 專案建立關聯。

Firebase 為您的 Firebase 應用程式自動建立的 API 金鑰

當您執行下列任何操作時，Firebase 會自動為專案建立 API 金鑰：

  • 建立 Firebase 專案 > Browser key 自動建立
  • 建立 Firebase Apple 應用程式 > iOS key 自動建立
  • 建立 Firebase Android 應用程式 > Android key 自動建立

您也可以在 Google Cloud 控制台中建立自己的 API 金鑰，例如用於開發或偵錯。請參閱本頁後續內容，進一步瞭解何時建議使用這項功能。

找出 API 金鑰

您可以在 Google Cloud 主控台的「API 和服務」>「憑證」面板中，查看及管理專案的「所有」API 金鑰。

您也可以在下列位置查看系統自動配對至 Firebase 應用程式的 API 金鑰。根據預設，所有專案的 Firebase 應用程式 (適用於相同平台，例如 Apple、Android 和網頁) 都會使用相同的 API 金鑰。

  • Firebase Apple 應用程式：在 Firebase 設定檔 GoogleService-Info.plist 的 API_KEY 欄位中，找出自動比對的 API 金鑰。

  • Firebase Android 應用程式：在 Firebase 設定檔 google-services.json 的 current_key 欄位中，找出自動比對的 API 金鑰。

  • Firebase Web 應用程式：在 Firebase 設定物件中的 apiKey 欄位中，找出自動比對的 API 金鑰。

使用 API 金鑰

與 Firebase/Google 服務互動時，API 金鑰可用於識別您的 Firebase 專案。具體來說，這些金鑰可用於將 API 要求與您的專案配額和帳單相關聯。也適用於存取公開資料。

舉例來說，您可以將 API 金鑰的值做為查詢參數傳遞至 REST API 呼叫，藉此明確使用 API 金鑰。以下範例說明如何向 Dynamic Links 連結縮短器 API 提出要求：

POST https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY

當應用程式呼叫需要由行動/網頁端用戶端提供 API 金鑰的 Firebase API 時，應用程式會自動在 Firebase 設定檔案/物件中尋找專案的 API 金鑰。不過，您可以使用其他機制 (包括環境變數) 為應用程式提供 API 金鑰。

查看 API 金鑰並套用適當的限制 (建議)

雖然您不必將 Firebase 服務的 API 金鑰視為機密，但仍應按照本節所述，檢查並套用限制。

查看系統自動新增至 Firebase API 金鑰許可清單的 API

當 Firebase 在專案中建立 API 金鑰時，我們會自動為該金鑰新增「API 限制」。加入此許可清單的 API 是 Firebase 相關 API，需要用戶端在呼叫時提供 API 金鑰。請注意，使用 Firebase 服務所需的大多數 API 其實不需要列入 API 金鑰的許可清單。

由於 Firebase 會為所有 Firebase 服務新增必要的 API，因此 API 金鑰的許可清單可能會包含您未使用的產品 API。您可以從許可清單中移除 API，但請務必小心，不要移除 Firebase 和您使用的 Firebase 服務所需的 API (請參閱每項服務 / 產品的Firebase 相關 API 清單，瞭解哪些 API 需要列入許可清單)。否則，呼叫 Firebase 服務時會發生錯誤。

如果您使用密碼驗證的 Authentication，請縮減配額

如果您使用密碼式 Firebase Authentication，且有人取得您的 API 金鑰，他們將無法存取任何 Firebase 專案資料庫或 Cloud Storage 資料，前提是這些資料受到 Firebase Security Rules 保護。不過，他們可以使用您的 API 金鑰存取 Firebase 驗證端點，並針對您的專案提出驗證要求。

為降低有人濫用 API 金鑰嘗試暴力攻擊的可能性，您可以縮緊 identitytoolkit.googleapis.com 端點的預設配額，以反映應用程式預期的正常流量。請注意，如果您縮緊配額，而應用程式突然獲得大量使用者，您可能會收到登入錯誤，直到增加配額為止。您可以在 Google Cloud 控制台中變更專案的 API 配額。

針對任何非 Firebase 服務使用不同的受限 API 金鑰

雖然用於 Firebase 服務的 API 金鑰通常不必視為機密，但您應對搭配其他 Google Cloud API 使用的 API 金鑰採取額外防範措施。

如果您在任何平台上使用非 Firebase 服務 / 產品的 Google Cloud API，強烈建議您為這些 API 建立個別的受限 API 金鑰。如果 API 是用於可計費的 Google Cloud 服務，這點就特別重要。

舉例來說，如果您在 iOS 上使用 Firebase ML 和 Cloud Vision API，應建立不同的 API 金鑰，專門用於存取 Cloud Vision API。

為非 Firebase API 使用獨立的限制 API 金鑰，您就能在必要時輪替或取代金鑰，並為 API 金鑰新增額外限制，不必中斷 Firebase 服務的使用。

這些操作說明說明如何為名為 Super Service API 的假冒 API 建立個別的受限制 API 金鑰。

步驟 1：設定現有的 API 金鑰，禁止存取 Super Service API

  1. 開啟 Google Cloud 控制台的「憑證」頁面。系統顯示提示時，請選取專案。

  2. 針對清單中的每個現有 API 金鑰，開啟編輯檢視畫面。

  3. 在「API 限制」專區中，選取「限制金鑰」，然後將您希望 API 金鑰可存取的所有 API 新增至清單。請務必不加入要建立個別 API 金鑰的 API (在本例中為 Super Service API)。

    設定 API 金鑰的 API 限制時，您會明確宣告金鑰可存取的 API。根據預設，如果「API 限制」專區已選取「Don't restrict key」，則可使用 API 金鑰存取專案已啟用的任何 API。

現有的 API 金鑰將不會授予 Super Service API 存取權，但每個金鑰仍可繼續運作，適用於您已將其加入API 限制清單的任何 API。

步驟 2：建立並使用新的 API 金鑰，存取 Super Service API

  1. 返回「憑證」頁面。確認您仍選取 Firebase 專案。

  2. 依序按一下「建立憑證」>「API 金鑰」。記下新的 API 金鑰，然後按一下「限制金鑰」。

  3. 在「API 限制」部分中，選取「限制金鑰」，然後將 Super Service API 加入「僅限」清單。

    這個新的 API 金鑰只會授予 Super Service API 存取權。

  4. 設定應用程式和服務，以便使用新的 API 金鑰。

使用環境專屬 API 金鑰(建議)

如果您為不同環境 (例如測試和實際工作環境) 設定不同的 Firebase 專案，請務必讓每個應用程式執行個體與對應的 Firebase 專案互動。舉例來說，您的測試版應用程式執行個體不應與實際的 Firebase 專案通訊。這也表示您的測試版應用程式必須使用與測試版 Firebase 專案相關聯的 API 金鑰。

為減少將程式碼變更從開發階段提交至測試階段和正式版時發生的問題，請不要在程式碼中加入 API 金鑰，而是將其設為環境變數，或加入設定檔中。

請注意，如果您要使用 Firebase Local Emulator Suite 進行開發，並搭配使用 Firebase ML，就必須建立並使用僅供偵錯的 API 金鑰。如需建立這類金鑰的操作說明，請參閱 Firebase ML 說明文件。

常見問題與疑難排解

常見問題

是的，根據預設，Firebase 自動佈建用於 Firebase 相關 API 的所有 API 金鑰，都會自動套用「API 限制」。請參閱這個許可清單中的Firebase 相關 API 清單。

加入此許可清單的 API 是 Firebase 服務透過用戶端程式碼呼叫的 API，且需要 API 金鑰才能識別 Firebase 專案或應用程式。請注意，大部分 用於使用 Firebase 服務的 API 其實不需要加入 API 金鑰許可清單。

由於 Firebase 會為所有 Firebase 服務新增必要的 API，因此 API 金鑰的許可清單可能會包含您未使用的產品 API。您可以從許可清單中移除 API，但請務必小心，不要移除 Firebase 和您使用的 Firebase 服務所需的 API (請參閱每項服務 / 產品的Firebase 相關 API 清單，瞭解哪些 API 需要加入許可清單)。否則，呼叫 Firebase 服務時會發生錯誤。

您可以在 Google Cloud 控制台的「API 和服務」>「憑證」面板中，查看所有 API 金鑰及其「API 限制」。

請注意下列 Firebase 套用這些「API 限制」的方式：

  • 自 2024 年 5 月起，所有由 Firebase 自動佈建的新 API 金鑰，都會自動限制只能用於 Firebase 相關 API 清單。

  • 在 2024 年 5 月，Firebase 先前自動佈建的所有現有且未受限的 API 金鑰，將限制於Firebase 相關 API 清單 加上任何目前已啟用的專案 API。

  • Firebase 先前自動佈建的任何現有且已受限制的 API 金鑰，都不會受到影響。

  • Firebase 未自動佈建的任何現有 API 金鑰都不會變更。

您可以使用下列任一選項，判斷哪個 API 金鑰與 Firebase 應用程式相關聯：

Firebase 主控台

  1. 前往 「專案設定」，然後向下捲動至「您的應用程式」資訊卡。

  2. 選取感興趣的應用程式。

  3. 取得所需應用程式的 Firebase 設定檔/物件，然後找出其 API 金鑰：

    • Apple：下載 GoogleService-Info.plist，然後找出 API_KEY 欄位

    • Android：下載 google-services.json，找出所需應用程式的設定 (尋找其套件名稱)，然後找出 current_key 欄位

    • 網頁：選取「Config」選項，然後找出 apiKey 欄位

Firebase CLI

  1. 執行下列指令，取得所需應用程式的 Firebase 設定檔/物件：

    firebase apps:sdkconfig PLATFORM FIREBASE_APP_ID
    • PLATFORM (其中一個)：IOS | ANDROID | WEB
    • FIREBASE_APP_ID：Firebase 指派給 Firebase 應用程式的專屬 ID (查看應用程式 ID)

  2. 在應用程式的 Firebase 設定列印內容中，找出 API 金鑰：

    • Apple：找出 API_KEY 欄位

    • Android：找出所需應用程式的設定 (尋找其套件名稱)，然後找出 current_key 欄位

    • 網頁版：找出 apiKey 欄位

REST API

  1. 呼叫所需應用程式的適用端點，然後將 apiKeyId 值傳遞至下一個步驟，即可取得 API 金鑰的 apiKeyId (UID)。

  2. 請呼叫 projects.locations.keys.getKeyString 取得 API 金鑰字串。

    這個 keyString 與應用程式設定構件 (Apple | Android | 網頁版) 中的值相同。

  • Firebase Apple 應用程式：每個應用程式都有自己的設定檔，且只能列出一個 API 金鑰。

  • Firebase Android 應用程式：Firebase 專案中的所有 Android 應用程式都會列在同一個設定檔中，且每個應用程式只能列出一個 API 金鑰。不過，這個設定檔中的每個應用程式都可能列出不同的鍵。

  • Firebase Web 應用程式：每個應用程式都有專屬的設定物件，且只能列出一個 API 金鑰。

不過，您可以在一個應用程式中使用多個 API 金鑰。您必須提供機制，讓應用程式存取其他 API 金鑰，例如透過環境變數。存取其他 API 金鑰的機制不能依賴 Firebase 設定檔/物件中列出的 API 金鑰。

首次取得應用程式的 Firebase 設定檔案/物件時，Firebase 會檢查專案中是否有任何現有的 API 金鑰，且該金鑰具有與應用程式相符的「應用程式限制」 (例如 Apple 應用程式的相符套件 ID)。

如果 Firebase 找不到任何相符的受限制鍵，就會在設定檔案/物件中列出 Apple 應用程式的 iOS key、Android 應用程式的 Android key，以及網頁應用程式的 Browser key (假設這些鍵存在且沒有「應用程式限制」導致無法與該應用程式相符)。

可以，您可以手動從設定檔/物件中刪除 API 金鑰。不過，您必須提供其他機制，讓應用程式存取 API 金鑰 (例如透過環境變數)。否則，任何對 Firebase 服務的呼叫都會失敗。

可以，您可以手動編輯設定檔/物件，將不同的 API 金鑰與應用程式建立關聯。

請注意，如果您從控制台重新取得應用程式的設定檔/物件，系統一律會列出 Firebase 自動比對該應用程式的 API 金鑰。因此，您需要視需要重複手動編輯。

否，API 金鑰只能識別特定專案，無法移至其他專案。

如果刪除應用程式正在使用的 API 金鑰，該應用程式將無法呼叫 API。您可能會收到報告、電子郵件或錯誤訊息，指出您嘗試使用無效的 API 金鑰。

API 金鑰一經刪除即無法復原。

針對 Firebase API 金鑰，只有要求用戶端在呼叫時提供 API 金鑰的 API，才需要列入金鑰的「API 限制」許可清單。請注意，只有少數 Firebase 相關 API 有這項規定。專案中啟用的大部分 Firebase 相關 API 不需要列入金鑰的「API 限制」許可清單。

請參閱下表，判斷哪些 Firebase 相關 API 需要納入 Firebase API 金鑰的「API 限制」許可清單。請注意，Firebase API 金鑰只能用於 Firebase 服務。進一步瞭解如何為特定類型的 API 建立個別的受限制 API 金鑰。

您可以在 Google Cloud 主控台的「APIs & Services」 >「Credentials」面板中，查看及管理專案的 API 金鑰。

API 名稱 (服務名稱) API 顯示名稱 相關聯的 Firebase
服務 / 產品
firebase.googleapis.com Firebase Management API 所有產品
logging.googleapis.com Cloud Logging API 所有產品
firebaseinstallations.googleapis.com Firebase Installations API Cloud Messaging、Crashlytics、In-App Messaging、Performance Monitoring、Remote Config、Firebase ML
firebaseappcheck.googleapis.com Firebase App Check API App Check
firebaseappdistribution.googleapis.com Firebase App Distribution API App Distribution
firebaseapptesters.googleapis.com Firebase App Testers API App Distribution
identitytoolkit.googleapis.com Identity Toolkit API Authentication
securetoken.googleapis.com Token Service API Authentication
firebaserules.googleapis.com * Firebase Rules API Cloud Firestore、Cloud Storage、Realtime Database
datastore.googleapis.com Cloud Datastore API Cloud Firestore
firestore.googleapis.com Google Cloud Firestore API Cloud Firestore
fcmregistrations.googleapis.com FCM Registration API Cloud Messaging
firebasestorage.googleapis.com Cloud Storage for Firebase API Cloud Storage
firebasedynamiclinks.googleapis.com Firebase Dynamic Links API Dynamic Links
firebasehosting.googleapis.com * Firebase Hosting API Hosting
firebaseinappmessaging.googleapis.com Firebase In-App Messaging API In-App Messaging
firebaseml.googleapis.com Firebase ML API Firebase ML
mlkit.googleapis.com ** ML Kit API Firebase ML
mobilecrashreporting.googleapis.com Mobile Crash Reporting API Performance Monitoring
play.googleapis.com Google Play Android Developer API Performance Monitoring
firebaseremoteconfig.googleapis.com Firebase Remote Config API Performance Monitoring、Remote Config
firebaseremoteconfigrealtime.googleapis.com Firebase 遠端設定即時 API Performance Monitoring、Remote Config
cloudconfig.googleapis.com ** 不適用 Remote Config
firebasedatabase.googleapis.com * Firebase 即時資料庫 API Realtime Database
firebasevertexai.googleapis.com Firebase API 中的 Vertex AI Vertex AI in Firebase

* 只有在您使用 Firebase API 金鑰搭配第三方工具，或直接透過 REST 存取 Firebase 服務 / 產品時，才需要提供這項資訊。

** 適用於產品舊版 SDK。如果您使用的是最新版 SDK，API 就不需要列在鍵的許可清單中。

疑難排解

如果您收到 API_KEY_SERVICE_BLOCKED 錯誤或類似下方的錯誤訊息，請按照本常見問題中的指示操作：

Forbidden: 403 POST https://example-service.googleapis.com/method: Requests to this API example-service.googleapis.com method google.example-service.rest.method are blocked.

應用程式用來呼叫 API 的 API 金鑰可能已套用 「API 限制」，且金鑰的許可清單中未納入該 API。

網頁應用程式使用的 API 金鑰可能已套用 「API 限制」。如果是這種情況，請確認 Firebase Management API 已列入允許的 API 清單。

以下是 API 金鑰無效的幾個最常見原因：

  • API 金鑰已套用 「API 金鑰限制」，因此無法與嘗試使用金鑰的應用程式相符 (「應用程式限制」)，或是無法用於呼叫的 API (「API 限制」)。

  • 在 Google Cloud 控制台中從專案中刪除 API 金鑰。

  • 系統未為應用程式 Firebase 設定檔案/物件中列出的專案 ID 建立 API 金鑰。

修正這個問題的方法之一是取得應用程式 Firebase 設定檔/物件的更新版本，然後取代舊的設定檔/物件，並使用新的更新檔案/物件。在傳送設定檔供下載或在控制台中顯示設定物件之前，Firebase 會檢查列出的 API 金鑰是否與應用程式相符。