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

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

以下是 Firebase 適用 API 金鑰的幾項重要事項：

• Firebase 相關 API 只會使用 API 金鑰識別 Firebase 專案或應用程式，不會用於授權呼叫 API (其他一些 API 允許這麼做)。Firebase 相關 API 的授權會透過 Google Cloud IAM 權限、Firebase Security Rules 或 Firebase App Check 與 API 金鑰分開處理。因此，如果您只將 Firebase API 金鑰用於 Firebase 相關 API，則可以將這些金鑰納入程式碼中。
• 建議您檢查並套用適當的限制，套用對象為所有 API 金鑰 (包括 Firebase API 金鑰)。具體來說，請限制金鑰只能用於應用程式實際使用的 API，並視情況限制配額。請注意，所有 Firebase 佈建的 API 金鑰都會預設套用「API 限制」。
• 僅使用 Firebase 佈建的 API 金鑰，用於 Firebase 相關 API。針對所有其他 API (例如 Maps 的 Places API 或 Google AI Gemini API)，請使用專屬 API 金鑰。
• 強烈建議您使用 Firebase Security Rules 保護 Realtime Database、Cloud Firestore 和 Cloud Storage 資料。請勿只依賴 API 金鑰限制。

API 金鑰和 Firebase 的一般資訊

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

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

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

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

使用 Firebase Security Rules，保護 Realtime Database、Cloud Firestore 和 Cloud Storage 資料。請勿只依賴限制和/或隱藏 API 金鑰。

建立 API 金鑰

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

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

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

重要事項： 根據預設，Firebase 自動建立的 API 金鑰會自動限制於一組 API 清單，要求用戶端在呼叫時提供 API 金鑰。請參閱「常見問題」Firebase 服務的 API 金鑰是否預設為受限？

您也可以在 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 金鑰視為機密，但您仍應按照本節所述，檢查並套用限制。

如果是正式版應用程式使用的 API 金鑰，請謹慎變更其限制或限制。請先在測試應用程式中使用測試 API 金鑰測試新設定，再變更正式版 API 金鑰的限制。

注意： 如果您用於 Firebase 服務的 API 金鑰設有「API 限制」，且您收到 API_KEY_SERVICE_BLOCKED 或 Forbidden 403 錯誤，請確認 API 金鑰已包含所有金鑰「API 限制」許可清單中的必要 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 服務時會發生錯誤。

注意： 在 2024 年 5 月，Firebase 會自動將 API 限制套用至所有現有的不受限制 Firebase 佈建的 API 金鑰。如需更多資訊，請參閱「Firebase 服務的 API 金鑰是否預設為受限制？」一文。

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

無論您使用哪種驗證選項，請使用 Firebase Security Rules 保護 Realtime Database、Cloud Firestore 和 Cloud Storage 資料。

如果您使用密碼式 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 服務的使用。

查看建立 API 專屬金鑰的操作說明

這些操作說明說明如何為名為 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。

重要事項： 如果日後啟用其他 API，請務必將這些 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 服務的 API 金鑰是否預設為受限？

是的，根據預設，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 服務時會收到錯誤訊息。

重要事項： 所有 Firebase 相關 API 都不會使用 API 金鑰做為呼叫 API 的授權。透過 API 呼叫傳遞的 API 金鑰，僅用於識別 Firebase 專案或應用程式。

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

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

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

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

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

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

重要事項： 如果您在任何平台上使用非 Firebase 服務 / 產品的 Google Cloud API，強烈建議您建立個別的受限 API 金鑰，以便搭配這些 API 使用。

如何判斷哪個 API 金鑰與我的 Firebase 應用程式相關聯？

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

Firebase 控制台

1. 前往 「Project settings」，然後向下捲動至「Your apps」資訊卡。

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)。

   • Apple：呼叫 projects.iosApps.get
   • Android：呼叫 projects.androidApps.get
   • 網頁：呼叫 projects.webApps.get

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

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

在 Firebase 設定檔案/物件中，我可以為同一個 Firebase 應用程式列出兩個 API 金鑰嗎？

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

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

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

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

Firebase 如何得知要將哪個 API 金鑰與應用程式相符 (例如在 Firebase 設定檔案/物件中)？

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

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

我可以手動從 Firebase 設定檔/物件中刪除 API 金鑰和欄位嗎？

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

我可以手動使用不同的 API 金鑰編輯 Firebase 設定檔/物件嗎？

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

您可以手動編輯 Firebase 設定檔/物件中的 API 金鑰，但通常不建議這麼做。這會增加存取 Firebase 服務時發生問題的機率。不過，如果您選擇編輯設定檔/物件，請按照下列步驟操作：

• 請確認 API 金鑰的範圍僅限於設定檔/物件中列出的 Project ID。
• 請確認沒有任何「API 金鑰限制」會阻止 API 金鑰與該應用程式搭配使用。
• 請確認 API 金鑰已套用適當的「API 限制」。請參閱Firebase 相關 API 清單，瞭解每項 Firebase 服務 / 產品需要加入許可清單的 API。

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

我可以將 API 金鑰從一個 Firebase 專案移至另一個專案嗎？

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

如果刪除 Google Cloud 主控台中列出的 API 金鑰，會發生什麼情況？

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

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

Firebase API 金鑰的「API 限制」許可清單中需要哪些 API？

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

重要事項： 所有 Firebase 相關 API 都不會使用 API 金鑰做為呼叫 API 的授權。透過 API 呼叫傳遞的 API 金鑰，僅用於識別 Firebase 專案或應用程式。

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

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

注意： 如果您在嘗試呼叫 Firebase 相關 API 時收到 API_KEY_SERVICE_BLOCKED 或 Forbidden 403 錯誤，且您使用的 API 金鑰已包含此表格中列出的所有必要 API，請與 Firebase 支援團隊聯絡。

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 錯誤，指出對此 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。

• 如果您在嘗試使用 Firebase 相關服務 / 產品時收到此錯誤，請確認您使用的 API 金鑰含有所有金鑰「API 限制」許可清單中的必要 API。

• 如果您在嘗試使用非 Firebase 服務時收到此錯誤，強烈建議您為該服務和 API 建立新的 API 金鑰。Firebase API 金鑰只能用於 Firebase 服務 / 產品。進一步瞭解如何為特定類型的 API 建立個別的限制 API 金鑰。

該如何修正這個錯誤？「無法從伺服器擷取這個 Firebase 應用程式的評估 ID。」

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

我收到電子郵件或錯誤訊息，指出我的 API 金鑰無效。發生了什麼事？該如何解決這個問題？

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

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

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

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

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