Join us in person and online for Firebase Summit on October 18, 2022. Learn how Firebase can help you accelerate app development, release your app with confidence, and scale with ease. Register now

ย้ายจาก HTTP เดิมเป็น HTTP v1

จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

แอปที่ใช้ HTTP API รุ่นเก่าของ FCM ควรพิจารณาย้ายข้อมูลไปยัง 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 ให้เพิ่มองค์ประกอบเหล่านี้ไปยังปลายทางในส่วนหัวของคำขอส่งของคุณ

ก่อน

POST https://fcm.googleapis.com/fcm/send

หลังจาก

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

อัพเดทการอนุญาตการส่งคำขอ

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

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

ให้ข้อมูลประจำตัวโดยใช้ ADC

Google Application Default Credentials (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()

ไป

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

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"

หลังจากที่คุณทำตามขั้นตอนข้างต้นเสร็จสิ้นแล้ว 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

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

Java

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  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 " + getAccessToken());
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 โปรดดู ที่บล็อก Firebase