ย้ายข้อมูลจาก FCM API เดิมไปยัง HTTP v1

แอปที่ใช้ API เดิมของ FCM ที่เลิกใช้งานแล้วสำหรับ HTTP และ XMPP ควรย้ายข้อมูลไปยัง HTTP v1 API โดยเร็วที่สุด เราได้เลิกใช้งานการส่งข้อความ (รวมถึงข้อความอัปสตรีม) ด้วย API เหล่านั้นเมื่อวันที่ 20 มิถุนายน 2023 และการปิดให้บริการในวันที่ 22 กรกฎาคม 2024

ดูข้อมูลเพิ่มเติมเกี่ยวกับฟีเจอร์ที่ได้รับผลกระทบ

นอกจากการสนับสนุนอย่างต่อเนื่องและฟีเจอร์ใหม่แล้ว HTTP v1 API ยังมีข้อได้เปรียบเหนือ API เดิมดังนี้

  • การรักษาความปลอดภัยที่ดียิ่งขึ้นผ่านโทเค็นเพื่อการเข้าถึง HTTP v1 API ใช้โทเค็นเพื่อการเข้าถึงที่มีอายุสั้นตามโมเดลความปลอดภัยของ OAuth2 ในกรณีที่โทเค็นเพื่อการเข้าถึงเป็นแบบสาธารณะ โทเค็นดังกล่าวจะใช้งานได้อย่างอันตรายเป็นเวลาประมาณ 1 ชั่วโมงเท่านั้นก่อนหมดอายุ ระบบจะไม่ส่งโทเค็นการรีเฟรชบ่อยเท่ากับคีย์ความปลอดภัยที่ใช้ใน API เดิม จึงมีแนวโน้มที่จะมีการตรวจจับโทเค็นน้อยกว่ามาก

  • การปรับแต่งข้อความในแพลตฟอร์มต่างๆ ได้อย่างมีประสิทธิภาพมากขึ้น สำหรับเนื้อหาข้อความนั้น HTTP v1 API มีคีย์ทั่วไปที่ใช้กับอินสแตนซ์เป้าหมายทั้งหมด รวมถึงคีย์เฉพาะแพลตฟอร์มที่ช่วยให้คุณปรับแต่งข้อความในแพลตฟอร์มต่างๆ ได้ การดำเนินการนี้ช่วยให้คุณสร้าง "การลบล้าง" ที่ส่งเพย์โหลดที่แตกต่างกันเล็กน้อยไปยังแพลตฟอร์มลูกค้าต่างๆ ในข้อความเดียวได้

  • ขยายการใช้งานได้มากขึ้นและรองรับการใช้งานในอนาคตมากขึ้นสำหรับแพลตฟอร์มไคลเอ็นต์รุ่นใหม่ HTTP v1 API รองรับตัวเลือกการรับส่งข้อความที่มีในแพลตฟอร์ม Apple, Android และเว็บอย่างเต็มรูปแบบ เนื่องจากแต่ละแพลตฟอร์มมีบล็อกที่กำหนดไว้ในเพย์โหลด JSON ของตนเอง FCM จึงสามารถขยาย API ไปยังเวอร์ชันใหม่และแพลตฟอร์มใหม่ๆ ได้ตามต้องการ

อัปเดตปลายทางเซิร์ฟเวอร์

URL ปลายทางสำหรับ HTTP v1 API แตกต่างจากปลายทางเดิมดังนี้

  • เวอร์ชันนี้มีเวอร์ชัน โดยมี /v1 อยู่ในเส้นทาง
  • เส้นทางจะมีรหัสโปรเจ็กต์ของโปรเจ็กต์ Firebase สำหรับแอปในรูปแบบ /projects/myproject-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 เพื่อให้ขั้นตอนการให้สิทธิ์เป็นอัตโนมัติอย่างสมบูรณ์ ให้ใช้ ADC ร่วมกับไลบรารีเซิร์ฟเวอร์ของ Admin SDK

หากแอปพลิเคชันทำงานบนสภาพแวดล้อมของเซิร์ฟเวอร์ที่ไม่ใช่ Google คุณจะต้องดาวน์โหลดไฟล์ JSON ของบัญชีบริการจากโปรเจ็กต์ Firebase ตราบใดที่คุณมีสิทธิ์เข้าถึงระบบไฟล์ที่มีไฟล์คีย์ส่วนตัว คุณก็สามารถใช้ตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS เพื่อให้สิทธิ์คำขอด้วยข้อมูลเข้าสู่ระบบที่ได้มาด้วยตนเอง หากไม่มีสิทธิ์เข้าถึงไฟล์ดังกล่าว คุณต้องอ้างอิงไฟล์บัญชีบริการในโค้ด ซึ่งควรใช้ด้วยความระมัดระวังอย่างยิ่งเนื่องจากมีความเสี่ยงที่การเปิดเผยข้อมูลเข้าสู่ระบบของคุณ

ระบุข้อมูลเข้าสู่ระบบโดยใช้ ADC

ข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชัน Google (ADC) จะตรวจสอบข้อมูลเข้าสู่ระบบของคุณตามลำดับต่อไปนี้

  1. ADC จะตรวจสอบว่ามีการตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS หรือไม่ หากตั้งค่าตัวแปรแล้ว ADC จะใช้ไฟล์บัญชีบริการที่ตัวแปรชี้ไป

  2. หากไม่ได้ตั้งค่าตัวแปรสภาพแวดล้อม ADC จะใช้บัญชีบริการเริ่มต้นที่ Compute Engine, Google Kubernetes Engine, App Engine และ Cloud Functions มีให้สำหรับแอปพลิเคชันที่ทำงานบนบริการเหล่านั้น

  3. หาก 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)
}

C#

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

ระบุข้อมูลเข้าสู่ระบบด้วยตนเอง

โปรเจ็กต์ Firebase รองรับบัญชีบริการของ Google ซึ่งคุณสามารถใช้เพื่อเรียก API ของเซิร์ฟเวอร์ Firebase จากเซิร์ฟเวอร์แอปหรือสภาพแวดล้อมที่เชื่อถือได้ หากคุณกำลังพัฒนาโค้ดในเครื่องหรือทำให้แอปพลิเคชันใช้งานได้ภายในองค์กร คุณจะใช้ข้อมูลเข้าสู่ระบบที่ได้รับผ่านบัญชีบริการนี้เพื่อให้สิทธิ์คำขอของเซิร์ฟเวอร์ได้

หากต้องการตรวจสอบสิทธิ์บัญชีบริการและให้สิทธิ์เข้าถึงบริการ Firebase คุณต้องสร้างไฟล์คีย์ส่วนตัวในรูปแบบ JSON

วิธีสร้างไฟล์คีย์ส่วนตัวสำหรับบัญชีบริการ

  1. ในคอนโซล Firebase ให้เปิด การตั้งค่า > บัญชีบริการ

  2. คลิกสร้างคีย์ส่วนตัวใหม่ แล้วยืนยันโดยคลิกสร้างคีย์

  3. จัดเก็บไฟล์ JSON ที่มีคีย์ดังกล่าวอย่างปลอดภัย

เมื่อให้สิทธิ์ผ่านบัญชีบริการ คุณมี 2 ตัวเลือกในการระบุข้อมูลเข้าสู่ระบบให้กับแอปพลิเคชัน คุณจะตั้งค่าตัวแปรสภาพแวดล้อม 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 สำหรับภาษาที่ต้องการเพื่อเรียกโทเค็นเพื่อการเข้าถึง 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 หรือ 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.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;

อัปเดตเพย์โหลดของการส่งคำขอ

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"
    }
  }
}

ตัวอย่าง: การกำหนดเป้าหมายหลายแพลตฟอร์ม

หากต้องการเปิดใช้การกําหนดเป้าหมายหลายแพลตฟอร์ม 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"
  }
}
// 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!",
      "time": "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 ที่