使用 Management REST API 设置和管理 Firebase 项目

Firebase Management API 让您通过编程方式对 Firebase 项目（包括项目的 Firebase 资源和 Firebase 应用）进行设置和管理。

本文概括性地介绍了以下常规工作流：将 Firebase 资源和应用添加到当前未使用 Firebase 服务的现有 Google Cloud 项目。

如果您只需要执行以下操作，可以前往本页面的相应部分：

• 将 Firebase 服务添加到您的项目中
• 将 Firebase 应用添加到 Firebase 项目
• 将您的 Firebase 项目与 Google Analytics（分析）帐号关联
• 完成项目默认位置的设置

在执行此页面上的任何步骤之前，请确保启用了 API。

如需了解 Firebase Management API 的访问权限管理，请访问 Cloud Identity Access Management (IAM) API 文档。

注意：如果您还没有 Google Cloud 项目，可以使用 Google Cloud Resource Manager API 中的 projects.create 方法或使用 Google Cloud 控制台创建一个。

如需详细了解每个帐号允许的项目数量上限，请访问了解 Firebase 项目。

准备工作

开始之前，您需要为 Google Cloud 项目启用 Management API 并生成访问令牌。

为您的 Google Cloud 项目启用 Management REST API

如果您尚未启用 Firebase Management API，则需要启用该 API 以用于您的 Google Cloud 项目。

1. 在 Google API 控制台中打开 Firebase Management API 页面。
2. 出现提示时，选择您的 Google Cloud 项目。
3. 在 Firebase Management API 页面上点击启用。

生成 API 访问令牌

下方展示了一个检索访问令牌的 Node.js 示例。

首先，如果您使用的不是 Google Cloud 环境，请将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为您的服务帐号密钥的路径。

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"

Windows

使用 PowerShell：

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\service-account-file.json"

然后，使用 Firebase Admin SDK 从您的服务帐号凭据获取访问令牌：

const admin = require('firebase-admin');

function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}

查找项目的资源名称

您可以找到适合添加 Firebase 服务的 Google Cloud 项目。

如需调用此端点，请执行以下操作：

• 您必须已有 Google Cloud 项目和 API 访问令牌。
• 项目成员必须至少具备现有 Google Cloud 项目的 Viewer 角色。

请求

调用 availableProjects.list。 此调用的请求正文必须为空。

下方展示了请求可用 Google Cloud 项目列表的 Node.js 示例：

const fetch = require('node-fetch');

async function listProjects() {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/availableProjects';
  const options = {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    const projects = resp['projectInfo'];
    console.log('Project total: ' + projects.length);
    console.log('');
    for (let i in projects) {
      const project = projects[i];
      console.log('Project ' + i);
      console.log('ID: ' + project['project']);
      console.log('Display Name: ' + project['displayName']);
      console.log('');
    }
  } catch(err) {
    console.error(err);
  }
}

结果

调用 availableProjects.list 时的响应正文包含 ProjectInfo 对象的列表。如果项目列表过长，则响应正文还会包含一个 nextPageToken，您可以将其用作查询参数来获取下一页的项目。

以下是 availableProjects.list 调用的响应正文示例：

{
  "projectInfo": [
    {
      "project": "projects/first-cloud-project",
      "displayName": "First Cloud Project"
    },
    {
      "project": "projects/second-cloud-project",
      "displayName": "Second Cloud Project"
    }
  ]
}

此示例响应包含可以向其中添加 Firebase 服务的两个 Google Cloud 项目。请注意，project 字段提供对项目而言全局唯一的资源名称。

您可以使用 availableProjects.list 发出的响应中列出的任意 project 值，向您的项目添加 Firebase 服务或添加应用。

在下一部分中，我们将使用 projects/first-gcp-project 资源名称将 Firebase 服务添加到 First Cloud Project。

将 Firebase 服务添加到您的项目中

Google Cloud 项目可以利用 Firebase 提供的服务。在本部分中，您将了解如何以编程方式将 Firebase 服务添加到现有 Google Cloud 项目中。请注意，您还可以在 Firebase 控制台中将 Firebase 服务添加到现有 Google Cloud 项目中。

如需调用此端点，请执行以下操作：

• 您必须已具有 Google Cloud 项目、API 访问令牌和 project 的唯一资源名称。
• 项目成员或服务帐号必须具有以下权限。如果您是现有 Google Cloud 项目的 Editor 或 Owner，则已拥有这些权限。
  firebase.projects.update
resourcemanager.projects.get
serviceusage.services.enable
serviceusage.services.get

请求

调用 projects.addFirebase。 此调用的请求正文必须为空。

下方展示了将 Firebase 服务添加到 Google Cloud 项目的 Node.js 示例：

const fetch = require('node-fetch');

async function addFirebase(projectId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + ':addFirebase';
  const options = {
    method: 'POST',
    // Use a manual access token here since explicit user access token is required.
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

结果

调用 projects.addFirebase 的结果是一个 Operation。此操作必须成功，您才能为项目调用其他与 Firebase 相关的端点。

如需检查操作是否成功，您可以对操作调用 operations.get，直到 done 的值为 true 及其 response 的类型为 FirebaseProject 为止。如果操作失败，其 error 会设置为 google.rpc.Status。

以下是 operations.get 调用的响应正文：

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.FirebaseProject",
    "projectId": "first-cloud-project",
    "projectNumber": "...",
    "displayName": "First Cloud Project",
    "name": "projects/first-cloud-project",
    "resources": {
      "hostingSite": "first-cloud-project",
      "realtimeDatabaseInstance": "first-cloud-project"
    }
  }
}

由于 done 为 true 且 response 类型是 FirebaseProject，因此 Google Cloud 项目现在已具有 Firebase 服务。响应还包含有关新建的 FirebaseProject 的其他实用信息，例如其 projectNumber 及其默认 resources。操作完成后，系统将自动删除 Operation。

将 Firebase 应用添加到您的项目中

许多不同的应用（包括 iOS、Android 和 Web 应用）都可以使用 FirebaseProject。在本部分中，您将了解如何以编程方式将 Firebase 应用添加到现有的 FirebaseProject。请注意，您还可以在 Firebase 控制台中将 Firebase 应用添加到现有 Firebase 项目。

如需调用此部分中的端点，请执行以下操作：

• 您必须具备 API 访问令牌和现有的 FirebaseProject。
• 项目成员必须是现有 Firebase 项目的 Editor 或 Owner。

选择要添加到 Firebase 项目的 Firebase 应用的类型。

iOS Android Web

您可以将 Firebase Android 应用添加到现有 Firebase 项目中。

请求

调用 projects.androidApps.create。 以下是构建请求正文的方法：

• 必需：

  • packageName：Android 应用的规范软件包名称，此名称将会在 Google Play 管理中心中显示。

• 可选，但建议提供：

  • displayName：应用的显示名，由用户指定。此值用于稍后在 Firebase 控制台中查找应用。

在我们的示例请求正文中，我们将使用 packageName 和 displayName：

{
  "displayName": "My Firebase Android App"
  "packageName": "com.firebase.android"
}

下方展示了将 Firebase Android 应用添加到 Firebase 项目的 Node.js 示例：

const fetch = require('node-fetch');

async function addAndroidApp(projectId, displayName, packageName) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + '/androidApps';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'displayName': displayName,
      'packageName': packageName
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

结果

调用 projects.androidApps.create 的结果是一个 Operation。此操作必须成功，您才能为项目调用其他与 Firebase 相关的端点。

如需检查操作是否成功，您可以对操作调用 operations.get，直到 done 的值为 true 及其 response 的类型为 AndroidApp 为止。如果操作失败，其 error 会设置为 google.rpc.Status。

以下是 operations.get 调用的响应正文：

{
  "name": "operations/...",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.AndroidApp",
    "name": "projects/first-cloud-project/androidApps/...",
    "appId": "...",
    "displayName": "My Firebase Android App",
    "projectId": "first-cloud-project",
    "packageName": "com.firebase.android"
  }
}

由于 done 是 true 且 response 类型是 AndroidApp，因此 FirebaseProject 现在具有 AndroidApp。响应中还包含您新建的 Firebase Android 应用的其他实用信息，例如唯一的 Firebase appId。操作完成后，系统将自动删除 Operation。

添加 SHA 证书

您可以通过调用 projects.androidApps.sha.create 将 SHA 证书添加到任何现有 Firebase Android 应用。此方法调用的请求正文必须包含空的 name 字段。 此调用的结果是新创建的 ShaCertificate 实例。

调用 projects.androidApps.sha.create 时，您需要提供有效的 SHA-1 或 SHA-256 证书哈希。您可以使用 Gradle signingReport 命令获取签名证书的 SHA 哈希：

./gradlew signingReport

如需了解详情，请访问 Google API for Android。

将您的 Firebase 项目与 Google Analytics（分析）帐号关联（可选）

您可以通过编程方式将现有 Google Analytics（分析）帐号与现有的 FirebaseProject 关联。请注意，您还可以在项目设置的集成标签页中将现有的 Firebase 项目与 Google Analytics（分析）关联。

如需调用此端点，请执行以下操作：

• 您必须具备 API 访问令牌和现有的 FirebaseProject。
• 项目成员必须是现有 Firebase 项目的 Owner。

调用 projects.addGoogleAnalytics 需要 analytics_resource（可以是 analyticsAccountId 或 analyticsPropertyId）：

• 指定现有的 analyticsAccountId 以在指定的帐号中预配新的 Google Analytics（分析）媒体资源，并将新媒体资源与您的 Firebase 项目关联。

• 指定现有的 analyticsPropertyId 以将 Google Analytics（分析）媒体资源与您的 Firebase 项目关联。

您可以在 Google Analytics（分析）网站上找到 analyticsAccountId 和任何现有的 analyticsPropertyId。

调用 projects.addGoogleAnalytics 时，请执行以下操作：

1. 首先，确定 Google Analytics（分析）媒体资源中现有的数据流是否对应于 FirebaseProject 中的任何现有 Firebase 应用（基于数据流关联的 packageName 或 bundleId）。然后，关联数据流和应用（如果适用）。 请注意，此自动关联仅适用于 Android 应用和 iOS 应用。

2. 如果没有为您的 Firebase 应用找到对应的数据流，则系统会在 Google Analytics（分析）媒体资源中为每个 Firebase 应用预配新的数据流。请注意，即使 Web 应用之前已与您的 Analytics（分析）媒体资源中的某个数据流关联，系统也总是会为该 Web 应用预配新的数据流。

如需详细了解 Google Analytics（分析）帐号的层次结构和构造，请参阅 Google Analytics（分析）文档。

注意：如果您在将 Firebase 项目与 Google Analytics（分析）关联之前，该项目中已有 Firebase Web 应用，则系统会使用新的 measurementId 字段更新这些应用的 Firebase 配置对象。为了使 Web 应用能够使用 Analytics（分析），必须使用更新后的配置对象。调用 projects.webApps.getConfig 可获取更新后的配置对象。

请求

调用 projects.addGoogleAnalytics。

在我们调用 project.addGoogleAnalytics 的示例请求正文中，我们将指定 Google Analytics（分析）帐号 analyticsAccountId。此调用将预配新的 Google Analytics（分析）媒体资源，并将新媒体资源与 FirebaseProject 关联。

{
  "analyticsAccountId": "<your-google-analytics-account-id>"
}

下方展示了将 Firebase 项目与 Google Analytics（分析）帐号关联的 Node.js 示例：

const fetch = require('node-fetch');

async function addGoogleAnalytics(projectId, analyticsAccountId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + ':addGoogleAnalytics';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'analyticsAccountId': analyticsAccountId
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

结果

调用 projects.addGoogleAnalytics 的结果是一个 Operation。此操作必须成功，您才能为项目调用其他与 Firebase 相关的端点。

如需检查操作是否成功，您可以对操作调用 operations.get，直到 done 的值为 true 且 response 的类型为 analyticsDetails 为止。如果操作失败，其 error 会设置为 google.rpc.Status。

以下是 operations.get 调用的响应正文：

{
  "name": "operations/...",
  "none": true,
  "response": {
    "@type": "type.googleapis.com/google.firebase.service.v1beta1.AnalyticsDetails",
    "analyticsProperty": [
      {
        "id": "...",
        "displayName": "..."
      }
    ],
    "streamMappings": [
      {
        "app": "...",
        "streamId": "...",
        "measurementId": "..."
      }
    ]
  }
}

由于 done 为 true，且 response 类型为 analyticsDetails，因此 FirebaseProject 现已与指定的 Google Analytics（分析）帐号关联。操作完成后，系统将自动删除 Operation。

完成项目默认位置的设置（可选）

如果您的 Firebase 项目将使用 Cloud Firestore、Cloud Storage 或 App Engine (GAE) 应用，那么您能够以编程方式完成默认 Google Cloud Platform (GCP) 资源位置的设置。请注意，您还可以在 Firebase 控制台中选择位置。

如需调用此端点，请执行以下操作：

• 您必须具备 API 访问令牌和现有的 FirebaseProject。
• 项目成员必须是现有 Firebase 项目的 Owner。

警告： 此设置一经设定便无法撤消或更改。项目的默认 Google Cloud Platform (GCP) 资源位置一旦设置便无法更改。

在设置此位置之前，请查看为您的项目选择位置，了解最适合您的项目的位置。您还应该调用 projects.availableLocations 以返回您的项目的有效位置列表，因为如果您的项目属于 Google Cloud 组织，那么组织政策可能会限制项目的有效位置。

调用此 defaultLocation.finalize 方法创建一个 App Engine 应用，该应用的默认 Cloud Storage 存储分区位于您在请求正文中提供的 locationId。

如果 Project 已有 App Engine 应用或此 defaultLocation.finalize 方法之前已被调用，则表示可能已指定默认 GCP 资源位置。

注意：如果在完成默认资源位置设置之前，Firebase 项目中已有 Firebase Web 应用，系统将使用项目默认存储桶的 storageUrl 更新这些应用的 Firebase 配置对象。为了使 Web 应用能够使用 Cloud Storage，必须使用更新后的配置对象。调用 projects.webApps.getConfig 可获取更新后的配置对象。

请求

调用 projects.defaultLocation.finalize。 以下是构建请求正文的方法：

• 必需：

  • locationId：为需要设置位置信息的 GCP 服务（例如 Cloud Firestore 或 Cloud Storage）存储数据的位置。

{
  "locationId": "us-west2"
}

下方展示了完成项目的默认位置设置的 Node.js 示例：

const fetch = require('node-fetch');

async function finalizeProjectLocation(projectId, locationId) {
  const accessToken = getAccessToken();
  const uri = 'https://firebase.googleapis.com/v1beta1/projects/' + projectId + '/defaultLocation:finalize';
  const options = {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
    },
    body: JSON.stringify({
      'locationId': locationId
    }),
  };

  try {
    const rawResponse = await fetch(uri, options);
    const resp = await rawResponse.json();
    console.log(resp);
  } catch(err) {
    console.error(err['message']);
  }
}

结果

调用 projects.defaultLocation.finalize 的结果是一个 Operation。此操作必须成功，您才能为项目调用其他与 Firebase 相关的端点。

如需检查操作是否成功，您可以对操作调用 operations.get，直到 done 的值为 true 且 response 的类型为 google.protobuf.Empty 为止。如果操作失败，响应正文 error 将是 google.rpc.Status 类型。操作完成后，系统将自动删除 Operation。