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

แอปที่ใช้ FCM API เดิมซึ่งเลิกใช้งานแล้วสําหรับ 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

หมายเหตุ: ในเส้นทางการย้ายข้อมูลทั่วไป ระบบควรเปิดใช้ FCM v1 API โดยค่าเริ่มต้น หากพบข้อผิดพลาดในการติดต่อปลายทาง ให้ตรวจสอบอีกครั้งว่าได้เปิดใช้ "Firebase Cloud Messaging API" ในรายการ API และบริการในคอนโซล Google Cloud

อัปเดตการให้สิทธิ์ของคำขอส่ง

HTTP v1 ต้องใช้โทเค็นการเข้าถึง OAuth 2.0 แทนสตริงคีย์เซิร์ฟเวอร์ที่ใช้ในคำขอเดิม หากคุณใช้ Admin SDK เพื่อส่งข้อความ ไลบรารีจะจัดการโทเค็นให้คุณ หากคุณใช้โปรโตคอลแบบไฟล์บันทึกข้อความ ให้รับโทเค็นตามที่อธิบายไว้ในส่วนนี้ แล้วเพิ่มลงในส่วนหัวเป็น Authorization: Bearer <valid Oauth 2.0 token>

ข้อควรระวัง: เช่นเดียวกับ API เดิม ข้อความ HTTP v1 ต้องส่งผ่านสภาพแวดล้อมที่เชื่อถือได้ เช่น เซิร์ฟเวอร์แอปหรือ Cloud Functions สำหรับ Firebase โดยใช้โปรโตคอล HTTP หรือ Admin SDK เพื่อสร้างคําขอข้อความ การส่งจากตรรกะแอปไคลเอ็นต์โดยตรงมีความเสี่ยงด้านความปลอดภัยสูงและระบบไม่รองรับ

ก่อน

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

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 ที่มีคีย์บัญชีบริการ ตัวแปรนี้มีผลกับเซสชันเชลล์ปัจจุบันเท่านั้น ดังนั้นหากคุณเปิดเซสชันใหม่ ให้ตั้งค่าตัวแปรอีกครั้ง

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 Auth สำหรับภาษาที่ต้องการเพื่อเรียกข้อมูลโทเค็นการเข้าถึง 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

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
messaging.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 ที่ฝังอยู่

HTTP v1 API ไม่รองรับค่า JSON ที่ฝังอยู่ในช่อง data ซึ่งแตกต่างจาก API การรับส่งข้อความเดิม ต้องมีการแปลงจาก JSON เป็นสตริง

ก่อน

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

หลัง

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

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

หากต้องการเปิดใช้การกำหนดเป้าหมายหลายแพลตฟอร์ม 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!",
      "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" ทั้งหมดใช้ API v1 เว้นแต่จะระบุไว้เป็นอย่างอื่น

• บล็อก Firebase