由使用旧版 HTTP 改为使用 HTTP v1

如果应用使用的是 FCM 旧版 HTTP API,您应该考虑按照本指南中的说明改为使用 HTTP v1 API。与旧版 API 相比,HTTP v1 API 具有以下优势:

  • 可通过访问令牌提供更好的安全性:HTTP v1 API 会根据 OAuth2 安全模型使用只在短时间内有效的访问令牌。即使访问令牌变成公开状态,能被恶意使用的时间也只有 1 小时,之后令牌就会失效。传输刷新令牌的频率不像传输旧版 API 中使用的安全密钥那样频繁,因此这些令牌被捕获的可能性要低得多。

  • 可针对不同平台更高效地自定义消息:在消息正文中,HTTP v1 API 加入了会传输到所有已定位实例的通用键,以及针对具体平台的键(方便您针对不同平台自定义消息)。这样,您就可以创建“替换项”,这些替换项可在一则消息中向不同的客户端平台发送略有不同的有效负载。

  • 对于新的客户端平台版本,扩展性和适应性更出色:HTTP v1 API 完全支持 iOS、Android 和网页支持的消息传递选项。由于 JSONN 有效负载中包含每个平台自己的定义块,因此 FCM 可以根据需要扩展 API 以支持新版本及新平台。

更新服务器端点

HTTP v1 API 的端点网址与旧版端点的不同之处表现在以下几个方面:

  • 带版本号,并且路径中包含 /v1
  • 路径中包含您应用的 Firebase 项目的项目 ID(格式为 /projects/myproject-ID/)。您可以在 Firebase 控制台的常规项目设置标签中找到此 ID。
  • 它明确将 send 方法指定为 :send

要更新 HTTP v1 的服务器端点,请在发送请求的标头中向端点中添加这些元素。

以前

POST https://fcm.googleapis.com/fcm/send

此后

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

更新发送请求的授权

HTTP v1 发送请求需要 OAuth 2.0 访问令牌,以替换旧版请求中使用的服务器密钥字符串。如果您使用 Admin SDK 发送消息,该库会为您处理令牌。如果您使用的是原始协议,请按照本部分中的说明获取令牌,并将其作为 Authorization: Bearer <valid Oauth 2.0 token> 添加到标头中。

早于

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

晚于

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

根据服务器环境的详细信息,您可以组合使用以下策略来授权服务器向 Firebase 服务发送请求:

  • Google 应用默认凭据 (ADC)
  • 服务帐号 JSON 文件
  • 源自服务帐号的短期有效的 OAuth 2.0 访问令牌

如果您的应用在 Compute Engine、Kubernetes Engine、App Engine 或 Cloud Functions(包括 Firebase 的 Cloud Functions)上运行,请使用应用默认凭据 (ADC)。ADC 使用您现有的默认服务帐号来获取向请求授权的凭据,并且通过 GOOGLE_APPLICATION_CREDENTIALS 环境变量实现灵活的本地测试。为了最大限度地自动化授权流程,请将 ADC 与 Admin SDK 服务器库一起使用。

如果您的应用在非 Google 服务器环境中运行,则需要从 Firebase 项目下载服务帐号 JSON 文件。只要您可以访问包含私钥文件的文件系统,就可以使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量以及这些手动获取的凭据向请求授权。如果您没有此类文件访问权限,则必须在代码中引用服务帐号文件,但由于存在凭据泄露的风险,因此应非常谨慎地处理。

使用 ADC 提供凭据

Google 应用默认凭据 (ADC) 按以下顺序检查您的凭据:

  1. ADC 检查是否设置了 GOOGLE_APPLICATION_CREDENTIALS 环境变量。如果设置了该变量,ADC 就会使用该变量指向的服务帐号文件。

  2. 如果未设置环境变量,则对于在 Compute Engine、Kubernetes Engine、App Engine 和 Cloud Functions 上运行的应用,ADC 使用这些服务提供的默认服务帐号。

  3. 如果 ADC 无法使用上述任何凭据,系统会抛出一个错误。

以下 Admin SDK 代码示例展示了该策略。该示例并未明确指定应用凭据。但是,只要设置了环境变量,或者只要应用在 Compute Engine、Kubernetes Engine、App Engine 或 Cloud Functions 上运行,ADC 便能够隐式查找凭据。

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Java

FirebaseOptions options = new FirebaseOptions.Builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

Python

default_app = firebase_admin.initialize_app()

Go

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

C#

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

手动提供凭据

Firebase 项目支持 Google 服务帐号,您可以使用这些帐号从应用服务器或受信任环境调用 Firebase 服务器 API。如果您在本地开发代码,在本地部署您的应用,或部署到不支持应用默认凭据 (ADC) 的非 Google 云端,则可以使用通过此服务帐号获取的凭据来向服务器请求授权。

要对服务帐号进行身份验证并授权其访问 Firebase 服务,您必须生成 JSON 格式的私钥文件。

要为您的服务帐号生成私钥文件,请执行以下操作:

  1. 在 Firebase 控制台中,打开设置 > 服务帐号

  2. 点击生成新的私钥,然后点击生成密钥进行确认。

  3. 妥善存储包含密钥的 JSON 文件。您将需要使用此 JSON 文件以手动方式向服务器请求授权。

通过服务帐号进行授权时,若要为您的应用提供凭据,有两种方式可供您选择。您可以设置 GOOGLE_APPLICATION_CREDENTIALS 环境变量,也可以在代码中明确传递指向服务帐号密钥的路径。第一种方式更安全,我们强烈建议使用。

要设置环境变量,请执行以下操作:

将 GOOGLE_APPLICATION_CREDENTIALS 环境变量设置为包含服务帐号密钥的 JSON 文件的文件路径。此变量仅适用于当前的 Shell 会话,因此,如果您打开新的会话,请重新设置该变量。

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

使用 PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

完成上述步骤后,应用默认凭据 (ADC) 能够隐式确定您的凭据,允许您在非 Google 环境中测试或运行时使用服务帐号凭据。

使用凭据来创建访问令牌

将您的 Firebase 凭据与 Google API 客户端库一起用于首选语言,以检索短期有效的 OAuth 2.0 访问令牌,从而引用私钥 JSON 文件,如下所示:

node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    var key = require('./service-account.json');
    var jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

Java

private static String getAccessToken() throws IOException {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

在您的访问令牌到期后,系统会自动调用令牌刷新方法以检索更新的访问令牌。

要授予访问 FCM 的权限,应请求范围 https://www.googleapis.com/auth/firebase.messaging

将访问令牌添加到 HTTP 请求标头中:

Authorization: Bearer <access_token> 格式将令牌添加为 Authorization 标头的值:

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

Python

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}

Java

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;

更新发送请求的有效负载

FCM HTTP v1 使 JSON 消息有效负载的结构发生了极大的变化。首先,这些变化可确保不同的客户端平台在收到消息后会正确处理这些消息;此外,这些变化还能让您更加灵活地为每个平台自定义或“替换”消息字段。

除了查看本部分中的示例外,您还可以参阅针对不同平台自定义消息和查看 API 参考,以熟悉 HTTP v1。

示例:简单的通知消息

下文通过一个非常简单的通知有效负载(仅包含 titlebodydata 字段)进行了对比,展示了旧版有效负载与 HTTP v1 有效负载之间的基本差异。

以前

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

此后

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

示例:定位多个平台

旧版 API 通过在后端执行替换来实现多平台定位。相比之下,HTTP v1 则提供针对具体平台的键块,让开发者对平台之间的任何差异一目了然。这样可让您始终通过一个请求定位多个平台,如以下示例所示。

以前

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// iOS
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

此后

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "aps": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

示例:通过平台替换项进行自定义

除了简化了消息的跨平台定位外,HTTP v1 API 还可让您灵活地为每个平台自定义消息。

以前

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// iOS
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

此后

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

如需查看更多示例并详细了解 FCM HTTP v1 API,请参阅 Firebase 博客

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面