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

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

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

  • การรักษาความปลอดภัยที่ดีขึ้นผ่านโทเค็นการเข้าถึง HTTP v1 API ใช้โทเค็นการเข้าถึงที่มีอายุสั้นตามโมเดลความปลอดภัย OAuth2 ในกรณีที่โทเค็นการเข้าถึงกลายเป็นแบบสาธารณะ โทเค็นนั้นจะถูกนำไปใช้ในทางที่ผิดได้เพียงหนึ่งชั่วโมงเท่านั้นก่อนที่จะหมดอายุ โทเค็นการรีเฟรชจะไม่ถูกส่งบ่อยเท่ากับคีย์ความปลอดภัยที่ใช้ใน 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 หรือฟังก์ชันคลาวด์ (รวมถึงฟังก์ชันคลาวด์สำหรับ Firebase) ให้ใช้ Application Default Credentials (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

โหนด js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

ชวา

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

หลาม

default_app = firebase_admin.initialize_app()

ไป

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}
init.go

ค#

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

ระบุข้อมูลประจำตัวด้วยตนเอง

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

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

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

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

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

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

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

ในการตั้งค่าตัวแปรสภาพแวดล้อม:

ตั้งค่าตัวแปรสภาพแวดล้อม GOOGLE_APPLICATION_CREDENTIALS เป็นเส้นทางไฟล์ของไฟล์ JSON ที่มีคีย์บัญชีบริการของคุณ ตัวแปรนี้ใช้กับเซสชันเชลล์ปัจจุบันของคุณเท่านั้น ดังนั้นหากคุณเปิดเซสชันใหม่ ให้ตั้งค่าตัวแปรอีกครั้ง

ลินุกซ์หรือ macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

หน้าต่าง

ด้วย PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

หลังจากที่คุณทำตามขั้นตอนข้างต้นเสร็จแล้ว Application Default Credentials (ADC) จะสามารถระบุข้อมูลรับรองของคุณโดยปริยายได้ ซึ่งทำให้คุณสามารถใช้ข้อมูลรับรองบัญชีบริการเมื่อทดสอบหรือทำงานในสภาพแวดล้อมที่ไม่ใช่ของ Google

ใช้ข้อมูลรับรองเพื่อสร้างโทเค็นการเข้าถึง

ใช้ข้อมูลรับรอง Firebase ของคุณร่วมกับ Google Auth Library สำหรับภาษาที่คุณต้องการเพื่อดึงโทเค็นการเข้าถึง 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 หรือ JWT สำหรับข้อมูลเพิ่มเติม โปรดดู โทเค็นเว็บ JSON

หลาม

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

ชวา

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

หลาม

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

ชวา

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

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

หากต้องการเปิดใช้งานการกำหนดเป้าหมายหลายแพลตฟอร์ม 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 โปรดดูต่อไปนี้: