使用 FCM HTTP v1 API,您可以建構訊息要求,並傳送至下列類型的目標:
- 主題名稱
- 條件
- 裝置註冊權杖
- 裝置群組名稱 (已淘汰,將於 2027 年 9 月 29 日移除)
您可以傳送含有預先定義欄位的通知酬載、含有使用者自訂欄位的資料酬載,或是同時含有這兩種酬載的訊息。詳情請參閱「訊息類型」。
授權 HTTP v1 傳送要求
視伺服器環境的詳細資料而定,請結合使用下列策略,授權伺服器向 Firebase 服務發出要求:
- Google 應用程式預設憑證 (ADC)
- 服務帳戶 JSON 檔案
- 從服務帳戶衍生的短期 OAuth 2.0 存取權杖
如果應用程式是在 Compute Engine、Google Kubernetes Engine、App Engine 或 Cloud Functions (包括 Cloud Functions for Firebase) 上執行,請使用應用程式預設憑證 (ADC)。ADC 會使用現有的預設服務帳戶取得授權要求所需的憑證,並透過 GOOGLE_APPLICATION_CREDENTIALS 環境變數啟用彈性的本機測試。如要盡可能自動化授權流程,請搭配使用 ADC 和 Admin SDK 伺服器程式庫。
如果應用程式在非 Google 伺服器環境中執行,您必須從 Firebase 專案下載服務帳戶 JSON 檔案。只要您能存取含有私密金鑰檔案的檔案系統,就能使用環境變數 GOOGLE_APPLICATION_CREDENTIALS,透過這些手動取得的憑證授權要求。如果您沒有這類檔案存取權,就必須在程式碼中參照服務帳戶檔案,但請務必小心,以免憑證外洩。
使用 ADC 提供憑證
Google 應用程式預設憑證 (ADC) 會依下列順序檢查憑證:
ADC 會檢查是否已設定環境變數 GOOGLE_APPLICATION_CREDENTIALS。如果已設定變數,ADC 會使用變數指向的服務帳戶檔案。
如果未設定環境變數,ADC 會使用 Compute Engine、Google Kubernetes Engine、App Engine 和 Cloud Functions 為在這些服務上執行的應用程式提供的預設服務帳戶。
如果 ADC 無法使用上述任一憑證,系統會擲回錯誤。
以下 Admin SDK 程式碼範例說明這項策略。這個範例並未明確指定應用程式憑證,不過,只要設定環境變數,或應用程式在 Compute Engine、Google Kubernetes Engine、App Engine 或 Cloud Functions 上執行,ADC 就能隱含地找到憑證。
Node.js
admin.initializeApp({
credential: admin.credential.applicationDefault(),
});
Java
FirebaseOptions options = 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。如果您在本機開發程式碼,或是在地端部署應用程式,可以使用透過這個服務帳戶取得的憑證,授權伺服器要求。
您可以在
如要驗證服務帳戶並授權其存取 Firebase 服務,您必須產生 JSON 格式的私密金鑰檔案。
如何為服務帳戶產生私密金鑰檔案:
在 Firebase 控制台中,依序前往「
Settings 」(設定) >「Service accounts tab」(服務帳戶分頁)。依序點選「Generate New Private Key」(產生新的私密金鑰) 和「Generate Key」(產生金鑰) 來確認操作。
妥善保存含有金鑰的 JSON 檔案。
透過服務帳戶授權時,您可以選擇兩種方式,將憑證提供給應用程式。您可以設定 GOOGLE_APPLICATION_CREDENTIALS 環境變數,也可以在程式碼中明確傳遞服務帳戶金鑰的路徑。第一種做法較安全,我們強烈建議採用。
如何設定環境變數:
將環境變數 GOOGLE_APPLICATION_CREDENTIALS 設為包含服務帳戶金鑰的 JSON 檔案路徑。這個變數只會套用至當前的殼層工作階段,因此如果開啟新的工作階段,請再次設定變數。
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 Admin SDK (會自動處理授權),否則必須建立存取權杖,並將其新增至傳送要求。
使用 Firebase 憑證和偏好語言的 Google 驗證程式庫,擷取短期 OAuth 2.0 存取權杖:
node.js
function getAccessToken() {
return new Promise(function(resolve, reject) {
const key = require('../placeholders/service-account.json');
const 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);
});
});
}
在本範例中,Google API 用戶端程式庫會使用 JSON Web Token (JWT) 驗證要求。詳情請參閱「JSON Web Token」。
Python
def _get_access_token():
"""Retrieve a valid access token that can be used to authorize requests.
:return: Access token.
"""
credentials = service_account.Credentials.from_service_account_file(
'service-account.json', scopes=SCOPES)
request = google.auth.transport.requests.Request()
credentials.refresh(request)
return credentials.token
Java
private static String getAccessToken() throws IOException {
GoogleCredentials googleCredentials = GoogleCredentials
.fromStream(new FileInputStream("service-account.json"))
.createScoped(Arrays.asList(SCOPES));
googleCredentials.refresh();
return googleCredentials.getAccessToken().getTokenValue();
}
存取權杖到期後,系統會自動呼叫權杖更新方法,擷取更新後的存取權杖。
如要授權存取 FCM,請要求 https://www.googleapis.com/auth/firebase.messaging 範圍。
如要將存取權杖新增至 HTTP 要求標頭:
將權杖新增為 Authorization 標頭的值,格式為 Authorization: Bearer <access_token>:
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 " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;
授權其他專案的服務帳戶
您可以使用「傳送者專案」中服務帳戶產生的 OAuth 2.0 權杖,為「目標專案」傳送訊息。這樣一來,您就能在單一專案中集中管理服務帳戶,同時代表其他專案傳送訊息。如要瞭解如何執行這項操作,請按照下列步驟操作:
在傳送者專案中,確認已啟用 Firebase 雲端通訊 API。前往 Firebase 控制台,依序點選「設定」
>「一般」,確認是否已啟用。接著,按一下「Cloud Messaging」(雲端通訊) 分頁標籤。 在傳送者專案中,建立服務帳戶。
在目標專案中,將 Firebase 雲端通訊 API 管理員角色指派給服務帳戶的電子郵件地址。請在 Google Cloud 控制台的「IAM & Admin」(IAM 與管理) >「IAM」(身分與存取權管理) 頁面中執行這項操作。這個角色可讓傳送者專案的服務帳戶,將訊息傳送至目標專案。
在傳送者專案中,為服務帳戶產生 OAuth 2.0 存取權杖。您可以採取下列任一做法:
- 下載並使用服務帳戶金鑰 JSON 檔案。
- 如果服務在 Google Cloud 上執行,請使用 Workload Identity。
在傳送要求的
Authorization標頭中使用取得的存取權權杖。要求必須傳送至目標專案的 HTTP v1 端點:POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send
傳送訊息至特定裝置
如要傳送至單一特定裝置,請傳遞裝置的註冊權杖,如下所示。
REST
POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"body":"This is an FCM notification message!",
"title":"FCM Message"
}
}
}
cURL 指令:
curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
"notification":{
"title":"FCM Message",
"body":"This is an FCM Message"
},
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send
如果成功,HTTP v1 API 回應會是包含訊息 ID 的 JSON 物件:
{
"name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
}
使用 FCM HTTP v1 API 傳送測試通知訊息
本節說明如何使用 FCM HTTP v1 API 傳送測試通知訊息。
HTTP 要求網址
要求包含 HTTP POST,傳送至下列網址的指定目標 (註冊權杖、主題或條件):
POST https://fcm.googleapis.com/v1/projectId/messages:send
完整的 HTTP 要求 JSON 範例
以下是完整範例,說明如何在 HTTP POST 要求中發布通知:
{
"message": {
"token": REGISTRATION_TOKEN,
"notification": {
"title": "FCM API test",
"body": "This is the body of the notification.",
"image": "https://firebase.google.com/static/images/products/cloud-messaging/cloud-messaging-hero_1x.png"
}
}
}按一下「執行」,在 API Explorer 中試用範例。