ส่งข้อความโดยใช้ FCM HTTP v1 API

เมื่อใช้ FCM HTTP v1 API คุณจะสร้างคำขอข้อความและส่งไปยังเป้าหมายประเภทต่อไปนี้ได้

  • ชื่อหัวข้อ
  • เงื่อนไข
  • โทเค็นการลงทะเบียนอุปกรณ์
  • ชื่อกลุ่มอุปกรณ์ (เลิกใช้งานแล้ว ระบบจะนำออกในวันที่ 29 กันยายน 2027)

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

ให้สิทธิ์คำขอส่ง HTTP v1

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

  • ข้อมูลรับรองเริ่มต้นของแอปพลิเคชัน (ADC) ของ Google
  • ไฟล์ 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

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

  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 ได้ในแท็บ การตั้งค่า > บัญชีบริการ

หากต้องการตรวจสอบสิทธิ์บัญชีบริการและให้สิทธิ์เข้าถึงบริการ 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 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 หรือ 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;

ให้สิทธิ์บัญชีบริการจากโปรเจ็กต์อื่น

คุณสามารถส่งข้อความสำหรับโปรเจ็กต์หนึ่งซึ่งเป็น "โปรเจ็กต์เป้าหมาย" ขณะใช้โทเค็น OAuth 2.0 ที่สร้างจากบัญชีบริการในโปรเจ็กต์อื่นซึ่งเป็น "โปรเจ็กต์ผู้ส่ง" ได้ ซึ่งจะช่วยให้คุณจัดการบัญชีบริการแบบรวมศูนย์ในโปรเจ็กต์เดียวได้ขณะส่งข้อความในนามของผู้อื่น หากต้องการดูวิธีดำเนินการ ให้ทำตามขั้นตอนต่อไปนี้

  1. ในโปรเจ็กต์ผู้ส่ง ให้ตรวจสอบว่าได้เปิดใช้ Firebase Cloud Messaging API แล้ว ตรวจสอบการเปิดใช้ในคอนโซล Firebase โดยไปที่ การตั้งค่า > ทั่วไป จากนั้นคลิกแท็บ Cloud Messaging

  2. สร้างบัญชีบริการในโปรเจ็กต์ผู้ส่ง

  3. ในโปรเจ็กต์เป้าหมาย ให้มอบหมายบทบาทผู้ดูแลระบบ Firebase Cloud Messaging API ให้กับอีเมลของบัญชีบริการ โดยดำเนินการในหน้า IAM และผู้ดูแลระบบ > IAM ของคอนโซล Google Cloud บทบาทนี้ช่วยให้บัญชีบริการจากโปรเจ็กต์ผู้ส่งสามารถส่งข้อความไปยังโปรเจ็กต์เป้าหมายได้

  4. สร้างโทเค็นเพื่อการเข้าถึง OAuth 2.0 สำหรับบัญชีบริการในโปรเจ็กต์ผู้ส่ง ซึ่งทำได้โดยใช้ตัวเลือกใดตัวเลือกหนึ่งต่อไปนี้

    • การดาวน์โหลดและใช้ไฟล์ JSON ของคีย์บัญชีบริการ
    • ใช้ Workload Identity หากบริการของคุณทำงานใน Google Cloud

  5. ใช้โทเค็นเพื่อการเข้าถึงที่ได้รับในส่วนหัว 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 จะเป็นออบเจ็กต์ JSON ที่มีรหัสข้อความดังนี้

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

ส่งข้อความแจ้งเตือนทดสอบโดยใช้ FCM HTTP v1 API

ส่วนนี้จะอธิบายวิธีส่งข้อความแจ้งเตือนทดสอบโดยใช้ FCM HTTP v1 API

URL คำขอ HTTP

คำขอประกอบด้วย HTTP POST ไปยังเป้าหมายที่ระบุ (โทเค็นการลงทะเบียน หัวข้อ หรือเงื่อนไข) ที่ URL ต่อไปนี้

POST https://fcm.googleapis.com/v1/projectId/messages:send

ตัวอย่าง JSON ของคำขอ HTTP ที่สมบูรณ์

ต่อไปนี้เป็นตัวอย่างที่สมบูรณ์ซึ่งแสดงวิธีโพสต์การแจ้งเตือนภายในคำขอ 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