本頁面由 Cloud Translation API 翻譯而成。

從舊版 FCM API 遷移至 HTTP v1

應用程式若為 HTTP 和 XMPP 使用已淘汰的 FCM 舊版 API，則應遷移至以下版本：搶先試用 HTTP v1 API傳送訊息 (包括上游訊息) 已於下列期間淘汰 2023 年 6 月 20 日，我們將在 2024 年 7 月 22 日停止服務。

進一步瞭解受影響的特定功能。

除了持續支援及新功能外，HTTP v1 API 還具備舊版 API 的優點：

透過存取權杖提升安全性 HTTP v1 API 使用短期存取符記。在：存取權杖變成公開狀態，但只能惡意使用大約一小時過期。更新權杖的傳送頻率與使用的安全金鑰不相同所以幾乎不會被擷取
更有效率地在各平台上自訂訊息：訊息 HTTP v1 API 內文具有傳送至所有指定執行個體的共用鍵，以及平台專屬金鑰自訂多種平台的訊息。您可以藉此建立「覆寫」會將稍有不同的酬載傳送至用戶端平台。
對於新版用戶端平台版本來說，更完善且符合前瞻性： HTTP v1 API 完全支援 Apple 平台、Android 及網頁。因為每個平台在 JSON 酬載中各有自己的定義區塊 FCM 可以將 API 擴充至新版本和新平台將物件的使用中版本還原為舊版或依需要永久刪除封存版本

更新伺服器端點

HTTP v1 API 的端點網址與當中的舊版端點不同方式：

此為版本編號，且路徑包含 /v1。
這個路徑包含格式為 /projects/myproject-ID/。這個 ID 適用於「一般專案設定」分頁 Firebase 控制台。
這會明確將 send 方法指定為 :send。

如要更新 HTTP v1 的伺服器端點，請將這些元素新增至端點。

HTTP 要求之前

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

XMPP 要求早於

舊版 XMPP 訊息會透過連線傳送至下列端點：

fcm-xmpp.googleapis.com:5235

晚於

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 上執行， Google Kubernetes Engine、App Engine 或 Cloud Functions (包括 Cloud Functions for Firebase) 使用應用程式預設憑證 (ADC)。ADC 會使用現有的預設服務以取得憑證來授權要求，而 ADC 會啟用您可以使用環境變數 GOOGLE_APPLICATION_CREDENTIALS。如要充分運用授權流程，可搭配 Admin SDK 伺服器程式庫使用 ADC。

如果應用程式在非 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 程式碼範例說明這項策略。這個範例並未明確指定應用程式憑證，不過 ADC 可以只要已設定環境變數，即可以隱含方式找到憑證；或只要應用程式在 Compute Engine 上運作 Google Kubernetes Engine、App Engine 或 Cloud Functions。

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)
}init.go

C#

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

手動提供憑證

Firebase 專案支援 Google 服務帳戶可用來呼叫 Firebase 伺服器 API。如果您正在開發或在地端部署環境部署應用程式您就能使用取得透過這個服務帳戶授權伺服器要求

驗證及授權服務帳戶您必須先產生 JSON 格式的私密金鑰檔案，才能存取 Firebase 服務格式。

如何產生服務帳戶的私密金鑰檔案：

在 Firebase 控制台中開啟 設定 >服務帳戶。
按一下「產生新私密金鑰」，然後按一下「產生金鑰」加以確認。
安全地儲存包含金鑰的 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) 系統會以隱含方式判斷您的憑證，方便您使用 Service 在非 Google 環境中測試或執行時，就使用服務帳戶憑證

使用憑證建立存取權杖

搭配使用 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);
    });
  });
}index.js

在此範例中，Google API 用戶端程式庫使用 JSON Web Token 或 JWT若需更多資訊，請參閲 JSON 網路權杖。

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.tokenmessaging.py

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();
}Messaging.java

存取權杖到期後，系統會呼叫憑證更新方法自動擷取更新過的存取權杖。

如要授權存取「FCM」，請要求範圍 https://www.googleapis.com/auth/firebase.messaging。

如何將存取權杖新增至 HTTP 要求標頭：

請將權杖新增為 Authorization 標頭的值，並採用下列格式 Authorization: Bearer <access_token>:

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}index.js

Python

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

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;FirebaseMessagingSnippets.java

更新傳送要求的酬載

FCM HTTP v1 在建構 JSON 訊息的結構方面發生了重大異動酬載。主要來說，這些變更可確保訊息能正確處理在不同用戶端平台上收到要求的時間；這些變動也能帶給您自訂或「覆寫」功能的額外彈性每個平台的訊息欄位

除了查看本節中的範例之外，請參閱自訂跨平台訊息，並查看要取得的 API 參考資料熟悉 HTTP v1

範例：簡單通知訊息

以下比較非常簡單的通知酬載：僅限 title、body 和 data 欄位：說明基本知識舊版和 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"
    }
  }
}

範例：巢狀 JSON 資料

與舊版 Messaging API 不同，HTTP v1 API 不支援 data 欄位中的巢狀 JSON 值。必須從 JSON 轉換為字串。

早於

{
  ...
  "data": {
    "keysandvalues": {"key1": "value1", "key2": 123}
  }
}

晚於

{
  "message": {
   ...
    "data": {
      "keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
    }
  }
}

範例：指定多個平台

為了啟用多平台指定功能，舊版 API 已執行覆寫作業設定 HTTP(S) 負載平衡器相較之下，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"
  }
}
// Apple
{
  "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"
      }
    },
    "apns": {
      "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"
  }
}
// Apple
{
  "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"
        }
      }
    }
  }
}

範例：指定特定裝置

如要使用 HTTP v1 API 指定特定裝置，請提供裝置的目前使用的註冊權杖是 token 金鑰，而不是 to 鍵。

早於

  { "notification": {
      "body": "This is an FCM notification message!",
      "title": "FCM Message"
    },
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }

晚於

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

如需更多 FCM HTTP v1 API 的範例和資訊，請參閱以下內容：

使用 HTTP v1 API 建構應用程式伺服器傳送要求的指南。所有「REST」除非另有註明，否則程式碼片段使用第 1 版 API。
Firebase 網誌。