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

แอปที่ใช้ API เดิมของ FCM ที่เลิกใช้งานแล้วสำหรับ HTTP และ XMPP ควรย้ายไปยัง HTTP v1 API โดยเร็วที่สุด นอกเหนือจากการสนับสนุนอย่างต่อเนื่องและฟีเจอร์ใหม่ๆ แล้ว 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)
}

ค#

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);
    });
  });
}

ในตัวอย่างนี้ ไลบรารีไคลเอ็นต์ 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

ชวา

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
}

หลาม

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

ชวา

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 โปรดดูต่อไปนี้: