GCM (Google Cloud Messaging) 伺服器端 HTTP 協議發送訊息完整指南

前言

GCM (Google Cloud Messaging) 是 Google 提供的雲端推播服務，支援伺服器向 Android 裝置發送下行訊息。本文詳細說明 HTTP 協議介面的請求格式、回應格式與 Java 實作範例。

1. HTTP 請求格式

POST https://gcm-http.googleapis.com/gcm/send
Content-Type: application/json
Authorization: key=API_KEY

{
  "to": "/topics/foo-bar",
  "data": {
    "message": "This is a GCM Topic Message!"
  }
}

關鍵欄位說明：

• to — 目標：單一裝置註冊 ID、裝置群組、或主題（/topics/主題名）
• data — 自訂負載資料，Key-Value 格式
• Authorization — 必須攜帶 key=API_KEY，從 Google Cloud Console 取得

2. 回應格式範例

發送給單一/多個 Registration IDs

{
  "multicast_id": 216,
  "success": 3,
  "failure": 3,
  "canonical_ids": 1,
  "results": [
    { "message_id": "1:0408" },
    { "error": "Unavailable" },
    { "error": "InvalidRegistration" },
    { "message_id": "1:1516" },
    { "message_id": "1:2342", "registration_id": "32" },
    { "error": "NotRegistered" }
  ]
}

欄位解讀：

• success/failure — 成功/失敗筆數
• canonical_ids — 需更新註冊 ID 的數量
• registration_id — 新的標準註冊 ID（需更新資料庫）
• 常見錯誤：Unavailable（重試）、InvalidRegistration（格式錯誤）、NotRegistered（裝置已註銷）

發送給 Topic

// 成功
{ "message_id": "10" }

// 失敗
{ "error": "TopicsMessageRateExceeded" }

3. Java 伺服器端實作

try {
    // 建構 GCM 訊息內容
    JSONObject jGcmData = new JSONObject();
    jGcmData.put("to", "/topics/global");  // 目標主題
    
    JSONObject jData = new JSONObject();
    jData.put("message", "天王蓋地虎，小雞燉蘑菇");  // 自訂負載
    jGcmData.put("data", jData);

    // 建立 HTTP 連線
    URL url = new URL("https://android.googleapis.com/gcm/send");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestProperty("Authorization", "key=" + API_KEY);
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setRequestMethod("POST");
    conn.setDoOutput(true);

    // 發送請求
    OutputStream outputStream = conn.getOutputStream();
    outputStream.write(jGcmData.toString().getBytes());
    outputStream.flush();
    outputStream.close();

    // 讀取回應
    InputStream inputStream = conn.getInputStream();
    String resp = IOUtils.toString(inputStream);
    System.out.println("GCM Response: " + resp);

} catch (IOException e) {
    e.printStackTrace();
}

關鍵注意事項

• API Key 安全：嚴禁硬編碼於客戶端，僅伺服器端持有
• 重試機制：遇到 Unavailable 需指數退避重試
• 註冊 ID 管理：收到 canonical_ids 時必須更新資料庫中的舊 ID
• 主題訂閱：客戶端需先訂閱主題（GcmPubSub.subscribe()）
• 頻率限制：Topic 訊息有發送頻率限制，注意 TopicsMessageRateExceeded

遷移提醒

GCM 已於 2019 年 4 月 10 日正式停止服務，現建議遷移至 Firebase Cloud Messaging (FCM)，FCM 繼承 GCM 功能並提供更豐富特性（如訊息優先級、設備群組、分析儀表板等）。本文僅供維護舊系統參考。