了解如何使用和管理 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 密钥。您可以在本页面稍后部分中详细了解何时推荐执行此操作。

查找 API 密钥

您可以在 Google Cloud 控制台内的 API 和服务 > 凭据面板中查看和管理所有项目的 API 密钥。

您还可以在以下位置找到自动匹配到 Firebase 应用的 API 密钥。默认情况下,项目在同一平台(Apple、Android 或 Web)上的所有 Firebase 应用都将使用同一个 API 密钥。

  • Firebase Apple 应用 - 可在 Firebase 配置文件 GoogleService-Info.plistAPI_KEY 字段中查找自动匹配的 API 密钥。

  • Firebase Android 应用 - 可在 Firebase 配置文件 google-services.jsoncurrent_key 字段中查找自动匹配的 API 密钥。

  • Firebase Web 应用 - 可在 Firebase 配置对象的 apiKey 字段中查找自动匹配的 API 密钥。

使用 API 密钥

API 密钥用于在与 Firebase/Google 服务交互时标识 Firebase 项目。具体而言,它们可以将 API 请求与您的项目关联,用于配额和结算目的。它们也有助于访问公开数据。

例如,您可以显式使用 API 密钥,只需将其值作为查询参数传入 REST API 调用即可。以下示例展示了如何向 Dynamic Links Link Shortener API 发出请求:

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

当您的应用调用需要移动/Web 客户端提供的 API 密钥的 Firebase API 时,会在 Firebase 配置文件/对象中自动查找项目的 API 密钥。不过,您也可以使用环境变量等其他机制为您的应用提供 API 密钥。

查看限制并对 API 密钥施加适当的限制(推荐)

虽然没有必要将 Firebase 服务的 API 密钥视为机密,但您应该查看并应用本部分中所述的限制。

查看系统自动添加到 Firebase API 密钥许可名单的 API

当 Firebase 在您的项目中创建 API 密钥时,我们会自动为该密钥添加“API 限制”添加到此许可名单中的 API 是 Firebase 相关 API,这些 API 要求客户端在调用时提供 API 密钥。请注意,使用 Firebase 服务所需的大多数 API 实际上不需要列入 API 密钥的许可名单。

由于 Firebase 会为所有 Firebase 服务添加必要的 API,因此 API 密钥的许可名单可能包含您未使用的 API。您可以从许可名单中移除 API,但必须非常小心,不要移除 Firebase 和您使用的 Firebase 服务所需的 API(请参阅每个服务/产品需要在许可名单中的 Firebase 相关 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 密钥一般不需要视为机密,但如果这类 API 密钥是用于其他 Google Cloud 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 限制”部分选择了“不限制密钥”时,即表示一个 API 密钥可用于访问已为项目启用的所有 API。

现在,您现有的 API 密钥不会授予对 Super Service API 的访问权限,但对于您添加到每个密钥的“API 限制”列表中的任何 API,仍可继续使用该密钥进行访问。

第 2 步:创建并使用用于访问 Super Service API 的新 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 SuiteFirebase ML 进行开发,则必须创建并使用仅用于调试的 API 密钥。如需了解如何创建此类密钥,请参阅 Firebase ML 文档

常见问题解答和问题排查

常见问题解答

是的,默认情况下,Firebase 自动配置的所有 API 密钥(用于 Firebase 相关 API)都会自动应用“API 限制”。请参阅此许可名单中的 Firebase 相关 API 列表

添加到此许可名单中的 API 是 Firebase 服务从客户端代码调用的 API,并且需要 API 密钥来标识您的 Firebase 项目或应用。请注意,使用 Firebase 服务所需的大多数 API 实际上不需要包含在 API 密钥的许可名单中。

由于 Firebase 会为所有 Firebase 服务添加必要的 API,因此 API 密钥的许可名单可能包含您未使用的 API。 您可以从许可名单中移除 API,但必须非常小心,不要移除 Firebase 和您使用的 Firebase 服务所需的 API(请参阅每个服务/产品需要在许可名单中的 Firebase 相关 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 密钥都不会发生变化。

您可以使用以下任一方法来确定您的 Firebase 应用所关联的 API 密钥:

  1. 转到 项目设置,然后向下滚动到您的应用卡片。

  2. 选择相关应用。

  3. 获取相关应用的 Firebase 配置文件/对象,然后查找其 API 密钥:

    • Apple:下载 GoogleService-Info.plist,然后找到 API_KEY 字段

    • Android:下载 google-services.json,找到相关应用的配置(查找其软件包名称),然后找到 current_key 字段

    • Web:选择“配置”选项,然后找到 apiKey 字段

  1. 运行下面的命令来获取相关应用的 Firebase 配置文件/对象:

    firebase apps:sdkconfig PLATFORM FIREBASE_APP_ID
    • PLATFORM(任一项):IOS | ANDROID | WEB
    • FIREBASE_APP_ID:Firebase 为您的 Firebase 应用分配的唯一标识符(请参阅查找您的应用 ID
  2. 在应用输出的 Firebase 配置中,找到其 API 密钥:

    • Apple:找到 API_KEY 字段

    • Android:找到相关应用的配置(查找其软件包名称),然后找到 current_key 字段

    • Web:找到 apiKey 字段

  1. 调用相关应用的适用端点,然后将 apiKeyId 值传递给下一步,以获取 API 密钥的 apiKeyId (UID)。

  2. 通过调用 projects.locations.keys.getKeyString 获取 API 密钥字符串。

    keyString 值可以在应用的配置工件中找到 (Apple | Android | Web)。

  • Firebase Apple 应用 - 每个应用都有自己的配置文件,并且只列出一个 API 密钥。

  • Firebase Android 应用 - Firebase 项目中的所有 Android 应用都列在同一个配置文件中,并且每个应用只能列出一个 API 密钥。不过,这个配置文件中的每个应用都可以列出不同的密钥。

  • Firebase Web 应用 - 每个应用都有自己的配置对象,并且只列出一个 API 密钥。

不过,您可以对一个应用使用多个 API 密钥。您必须提供一种供应用访问其他这些 API 密钥的机制,例如通过环境变量。用于访问其他 API 密钥的机制不能依赖于 Firebase 配置文件/对象中列出的这些 API 密钥。

在您首次获取应用的 Firebase 配置文件/对象时,Firebase 会检查您的项目中是否有任何施加了与应用相匹配的“应用限制”(如 Apple 应用的匹配软件包 ID)的现有 API 密钥。

如果 Firebase 没有找到任何匹配的受限密钥,那么它将在配置文件/对象中列出 iOS key(对于 Apple 应用)、Android key(对于 Android 应用)以及 Browser key(对于 Web 应用)(假设这些密钥存在,并且没有施加阻止它们与该应用匹配的“应用限制”)。

您可以手动删除配置文件/对象中的 API 密钥。不过,您必须提供其他一些供您的应用访问 API 密钥的机制(例如通过环境变量)。否则,对 Firebase 服务的任何调用都将失败。

可以,您可以手动修改配置文件/对象,以便将其他 API 密钥与应用相关联。

请注意,如果您从控制台重新获取了应用的配置文件/对象,它将始终列出 Firebase 自动匹配到该应用的 API 密钥。因此,您需要酌情重复执行手动修改。

不可以,API 密钥仅标识某个特定的项目,无法移至其他项目。

如果您删除应用正在使用的 API 密钥,该应用发出的 API 调用将失败。您可能会收到表明您正在尝试使用无效 API 密钥的报告、电子邮件或错误。

删除 API 密钥是永久性操作,无法撤消。

对于 Firebase API 密钥,需要在密钥的“API 限制”许可名单中的唯一 API 是要求客户端在调用时提供 API 密钥的 API。请注意,很少有 Firebase 相关 API 具有此要求。您项目中启用的大多数 Firebase 相关 API 都不需要列入密钥的“API 限制”许可名单。

请使用下表确定哪些 Firebase 相关 API 需要添加到 Firebase API 密钥的“API 限制”许可名单中。请注意,Firebase API 密钥只能用于 Firebase 服务。详细了解如何针对特定类型的 API 使用单独的受限 API 密钥

您可以在 Google Cloud 控制台内的 API 和服务 > 凭据面板中查看和管理项目的 API 密钥。

API 名称(服务名称) API 显示名称 关联的 Firebase
服务/产品
firebase.googleapis.com Firebase Management API 所有产品
logging.googleapis.com Cloud Logging API 所有产品
firebaseinstallations.googleapis.com Firebase Installations API Cloud MessagingCrashlyticsIn-App MessagingPerformance MonitoringRemote ConfigFirebase 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 FirestoreCloud StorageRealtime 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 MonitoringRemote Config
firebaseremoteconfigrealtime.googleapis.com Firebase Remote Config Realtime API Performance MonitoringRemote Config
cloudconfig.googleapis.com ** 不适用 Remote Config
firebasedatabase.googleapis.com * Firebase Realtime Database API Realtime Database
firebasevertexai.googleapis.com Vertex AI in Firebase API 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。

您的 Web 应用所用的 API 密钥可能施加了“API 限制”。如果是这种情况,请确保 Firebase Management API 位于允许的 API 列表中。

以下是导致 API 密钥无效的几个最常见的原因:

  • 该 API 密钥施加了“API 密钥限制”,这使其无法匹配到尝试使用该密钥的应用(以下简称“应用限制”)或无法用于被调用的 API(以下简称“API 限制”)。

  • 该 API 密钥已从 Google Cloud 控制台内的项目中删除。

  • 该 API 密钥不是为应用的 Firebase 配置文件/对象中列出的项目 ID 创建的。

解决此问题的一种方法是,获取应用的 Firebase 配置文件/对象的更新版本,然后用更新后的配置文件/对象替换掉旧的文件/对象。在发送配置文件以供下载或在控制台中显示配置对象之前,Firebase 会检查所列出的 API 密钥是否与应用匹配