ข้อกำหนดโปรโตคอลสำหรับ https.onCall

ทริกเกอร์ https.onCall สำหรับ Cloud Functions คือทริกเกอร์ HTTPS ที่มีรูปแบบเฉพาะสำหรับคำขอและการตอบกลับ ส่วนนี้จะอธิบายเกี่ยวกับ ข้อกำหนดสำหรับรูปแบบคำขอ HTTPS และการตอบกลับที่ไคลเอ็นต์ SDK ใช้ เพื่อนำ API ไปใช้ ข้อมูลนี้อาจเป็นประโยชน์สำหรับคุณหากข้อกำหนดของคุณไม่สามารถทำได้โดยใช้แพลตฟอร์ม Android, Apple หรือ SDK บนเว็บ

หมายเหตุ: หากคุณมีสิทธิ์ใช้ SDK ของ Android, Apple หรือเว็บ เราขอแนะนำให้ใช้แทนการติดตั้งใช้งานโปรโตคอลนี้โดยตรง SDK มี ที่จะช่วยประหยัดเวลาและลดแรงงาน ตามรายละเอียดใน ฟังก์ชันการโทรจากแอปของคุณ

รูปแบบคำขอ: ส่วนหัว

คำขอ HTTP ไปยังปลายทางทริกเกอร์ที่เรียกใช้ได้ต้องเป็น POST ที่มีพารามิเตอร์ ส่วนหัวต่อไปนี้:

• ต้องระบุ: Content-Type: application/json
  • อนุญาตให้ใช้ ; charset=utf-8 (ไม่บังคับ)
• ไม่บังคับ: Authorization: Bearer <token>
  • โทเค็นรหัสผู้ใช้ Firebase Authentication สำหรับผู้ใช้ที่เข้าสู่ระบบซึ่งส่งคำขอ แบ็กเอนด์จะยืนยันโทเค็นนี้โดยอัตโนมัติและทำให้พร้อมใช้งานใน context ของเครื่องจัดการ หากโทเค็นไม่ถูกต้อง คำขอจะถูกปฏิเสธ
• ไม่บังคับ: Firebase-Instance-ID-Token: <iid>
  • โทเค็นการลงทะเบียน FCM จาก SDK ของไคลเอ็นต์ Firebase ค่านี้ต้องเป็นสตริง ซึ่งอยู่ใน context ของแฮนเดิล ใช้สำหรับการกำหนดเป้าหมายข้อความ Push
• ไม่บังคับ: X-Firebase-AppCheck: <token>
  • โทเค็น Firebase App Check ที่ระบุโดยแอปไคลเอ็นต์ที่ส่งคำขอ แบ็กเอนด์จะยืนยันและถอดรหัสโทเค็นนี้โดยอัตโนมัติ โดยแทรก appId ใน context ของตัวแฮนเดิล หากโทเค็นไม่สามารถ ได้รับการยืนยันแล้ว คำขอจะถูกปฏิเสธ (พร้อมใช้งานสำหรับ SDK >=3.14.0)

หากมีส่วนหัวอื่นๆ รวมอยู่ด้วย คำขอจะถูกปฏิเสธ ตามที่อธิบายไว้ในเอกสารคำตอบด้านล่าง

หมายเหตุ: ในไคลเอ็นต์ JavaScript คำขอเหล่านี้จะทริกเกอร์การตรวจสอบ CORS OPTIONS ล่วงหน้าเนื่องจากสาเหตุต่อไปนี้

• ไม่อนุญาต application/json โดยต้องเป็น text/plain หรือ application/x-www-form-urlencoded
• ส่วนหัว Authorization ไม่ใช่ส่วนหัวของคำขอที่อยู่ในรายการที่ปลอดภัยของ CORS
• ส่วนส่วนหัวอื่นๆ ไม่อนุญาตให้ใช้เหมือนกัน

ทริกเกอร์ที่เรียกใช้ได้จะจัดการคำขอ OPTIONS เหล่านี้โดยอัตโนมัติ

เนื้อความของคำขอ

เนื้อหาของคำขอ HTTP ควรเป็นออบเจ็กต์ JSON ที่มีช่องต่อไปนี้

• ต้องระบุ: data - อาร์กิวเมนต์ที่ส่งไปยังฟังก์ชัน ซึ่งอาจเป็นค่า JSON ที่ถูกต้องรายการใดก็ได้ ระบบจะถอดรหัสโดยอัตโนมัติเป็นประเภท JavaScript แบบเนทีฟตามรูปแบบการเรียงอันดับที่อธิบายไว้ด้านล่าง

หากมีช่องอื่นๆ ในคำขอ แบ็กเอนด์จะถือว่าคำขอมีรูปแบบไม่ถูกต้องและปฏิเสธคำขอ

รูปแบบการตอบกลับ: รหัสสถานะ

มีหลายกรณีที่อาจทำให้เกิดรหัสสถานะ HTTP และ รหัสสถานะสตริงสำหรับข้อผิดพลาด ในการตอบกลับ

1. ในกรณีที่เกิดข้อผิดพลาด HTTP ก่อนที่จะเรียกทริกเกอร์ client ระบบจะไม่จัดการการตอบกลับเป็นฟังก์ชันไคลเอ็นต์ ตัวอย่างเช่น หากไคลเอ็นต์พยายามเรียกใช้ฟังก์ชันที่ไม่มีอยู่ ระบบจะตอบกลับด้วย 404 Not Found

2. หากทริกเกอร์ไคลเอ็นต์ถูกเรียกใช้ แต่คำขออยู่ในรูปแบบที่ไม่ถูกต้อง เช่น ไม่เป็น JSON, มีช่องไม่ถูกต้อง หรือไม่มีช่อง data คำขอจะถูกปฏิเสธด้วย 400 Bad Request โดยมีรหัสข้อผิดพลาด INVALID_ARGUMENT

3. หากโทเค็นการตรวจสอบสิทธิ์ที่ระบุในคำขอไม่ถูกต้อง คำขอจะถูกปฏิเสธโดยมี 401 Unauthorized พร้อมรหัสข้อผิดพลาด UNAUTHENTICATED

4. หากโทเค็นการจดทะเบียน FCM ที่ระบุในคำขอไม่ถูกต้อง ระบบจะไม่กำหนดลักษณะการทำงาน ระบบจะไม่ตรวจสอบโทเค็นในคําขอทุกรายการ ยกเว้นในกรณีที่ใช้โทเค็นเพื่อส่งข้อความ Push ด้วย FCM

5. หากมีการเรียกทริกเกอร์ที่เรียกใช้ได้ แต่ดำเนินการไม่สำเร็จโดยมีข้อยกเว้นที่ควบคุมไม่ได้หรือแสดงผลไม่สำเร็จ คำขอจะถูกปฏิเสธด้วย 500 Internal Server Error โดยมีรหัสข้อผิดพลาด INTERNAL วิธีนี้จะช่วยป้องกันไม่ให้ข้อผิดพลาดในการเขียนโค้ดแสดงต่อผู้ใช้ปลายทางโดยไม่ตั้งใจ

6. หากมีการเรียกใช้ฟังก์ชันที่เรียกใช้ได้และแสดงผลเงื่อนไขข้อผิดพลาดอย่างชัดเจนโดยใช้ API ที่ระบุไว้สำหรับฟังก์ชันที่เรียกใช้ได้ คำขอก็จะดำเนินการไม่สำเร็จ รหัสสถานะ HTTP ที่แสดงจะอิงตามการแมปอย่างเป็นทางการของสถานะข้อผิดพลาดกับสถานะ HTTP ตามที่ระบุไว้ใน code.proto รหัสข้อผิดพลาด ข้อความ และรายละเอียดเฉพาะที่แสดงจะได้รับการเข้ารหัสในเนื้อหาการตอบกลับตามรายละเอียดด้านล่าง ซึ่งหมายความว่าถ้าฟังก์ชันแสดงผลข้อผิดพลาดที่ชัดเจนซึ่งมีสถานะ OK การตอบกลับจะมีสถานะ 200 OK แต่มีการตั้งค่าช่อง error ในการตอบกลับ

7. หากทริกเกอร์ไคลเอ็นต์ดำเนินการสำเร็จ สถานะการตอบกลับจะเป็น 200 OK

รูปแบบการตอบกลับ: ส่วนหัว

คำตอบมีส่วนหัวต่อไปนี้

• Content-Type: application/json
• อนุญาตให้ใช้ ; charset=utf-8 (ไม่บังคับ)

เนื้อหาการตอบกลับ

การตอบสนองจากปลายทางไคลเอ็นต์จะเป็นออบเจ็กต์ JSON เสมอ อย่างน้อยก็ มี result หรือ error พร้อมด้วยช่องที่ไม่บังคับ หากคําตอบไม่ใช่ออบเจ็กต์ JSON หรือไม่มี data หรือ error SDK ของไคลเอ็นต์ควรถือว่าคําขอไม่สําเร็จพร้อมรหัสข้อผิดพลาด INTERNAL (13) ของ Google

• error - หากมีช่องนี้ ระบบจะถือว่าคําขอไม่สําเร็จ ไม่ว่ารหัสสถานะ HTTP จะเป็นอะไรหรือมี data อยู่ด้วยหรือไม่ก็ตาม ค่าของช่องนี้ควรเป็นออบเจ็กต์ JSON ในรูปแบบการแมป HTTP ของ Google Cloud มาตรฐานสำหรับข้อผิดพลาด โดยมีช่องสำหรับ status, message และ details (ไม่บังคับ) โดยไม่รวมฟิลด์ code หากไม่ได้ตั้งค่าช่อง status หรือเป็นค่าที่ไม่ถูกต้อง ไคลเอ็นต์ควรถือว่าสถานะเป็น INTERNAL ตาม code.protocol หากมี details อยู่ details จะรวมอยู่ในข้อมูลผู้ใช้ที่แนบมากับข้อผิดพลาดใน SDK ของไคลเอ็นต์ (หากมี)
  หมายเหตุ: ช่อง details นี้คือค่าที่ผู้ใช้ระบุ ไม่จำเป็นต้องเป็นรายการค่าที่รวมตามประเภท Proto เหมือนในรูปแบบ Status ของ Google
• result - ค่าที่ฟังก์ชันแสดงผล ซึ่งอาจเป็นค่า JSON ที่ถูกต้องรายการใดก็ได้ SDK ฟังก์ชัน Firebase จะเข้ารหัสค่าที่ผู้ใช้ส่งคืนเป็นรูปแบบ JSON นี้โดยอัตโนมัติ SDK ของไคลเอ็นต์จะถอดรหัสพารามิเตอร์เหล่านี้เป็นประเภทเนทีฟโดยอัตโนมัติตามรูปแบบการเรียงอันดับที่อธิบายไว้ด้านล่าง

หากมีช่องอื่นๆ อยู่ ระบบจะไม่สนใจช่องเหล่านั้น

การจัดรูปแบบข้อมูล

รูปแบบการจัดรูปแบบข้อมูลสำหรับเพย์โหลดข้อมูลแบบกำหนดเองจะเหมือนกันทั้งสำหรับคำขอและการตอบกลับ

เพื่อความสอดคล้องของแพลตฟอร์ม รูปแบบเหล่านี้จะเข้ารหัสเป็น JSON เสมือนว่าเป็นค่าของช่อง Any ในบัฟเฟอร์โปรโตคอล Pro3 โดยใช้การแมป JSON มาตรฐาน ค่าของประเภทแบบง่าย เช่น null, int, double หรือ string จะเข้ารหัสโดยตรงและไม่รวมประเภทที่ชัดเจน ดังนั้น float และ double จะได้รับการเข้ารหัสด้วยวิธีเดียวกัน และคุณอาจไม่ทราบว่าระบบจะได้รับรหัสใดเมื่อสิ้นสุดการโทร สําหรับประเภทที่ไม่ใช่ JSON จะใช้การเข้ารหัส proto3 ที่มีประเภทสําหรับค่า ดูข้อมูลเพิ่มเติมได้ที่เอกสารประกอบสำหรับการเข้ารหัส JSON ใดก็ได้

โดยอนุญาตให้ใช้ประเภทต่อไปนี้

• null - null
• int (signed or unsigned, up to 32 bit) - เช่น 3 หรือ -30
• ตัวเลขทศนิยม เช่น 3.14
• คู่ - เช่น 3.14
• บูลีน - true หรือ false
• สตริง เช่น "hello world"
• แผนที่<string, any=""> - เช่น {"x": 3}</string>
• list - เช่น [1, 2, 3]
• ยาว (แบบมีลายเซ็นหรือไม่ได้ลงชื่อเข้าใช้ ไม่เกิน 64 บิต) - [ดูรายละเอียดด้านล่าง]

ไม่รองรับค่า NaN และ Infinity สำหรับ float และ double

โปรดทราบว่า long เป็นประเภทพิเศษที่ปกติแล้วไม่อนุญาตใน JSON แต่อยู่ในข้อกำหนดของ proto3 ตัวอย่างเช่น การเข้ารหัสข้อมูลเหล่านี้จะเข้ารหัสดังนี้

ยาว

{
    '@type': 'type.googleapis.com/google.protobuf.Int64Value',
    'value': '-123456789123456'
}

แบบยาวที่ไม่มีการรับรอง

{
    '@type': 'type.googleapis.com/google.protobuf.UInt64Value',
    'value': '123456789123456'
}

โดยทั่วไปแล้ว ระบบควรถือว่าคีย์ @type เป็นคีย์ที่สงวนไว้ และไม่ควรใช้กับแผนที่ที่ส่งผ่านเข้ามา

เนื่องจากไม่ได้ระบุประเภทสำหรับแบบง่าย ค่าบางค่าจะมีการเปลี่ยนประเภทหลังจากผ่านสายไฟ float ที่ถูกข้ามจะกลายเป็น double short จะกลายเป็น int และอื่นๆ ใน Android ระบบรองรับทั้ง List และ JSONArray สำหรับค่ารายการ ในกรณีดังกล่าว การส่ง JSONArray จะทำให้เกิด List

หากแผนที่ที่มีช่อง @type ที่ไม่รู้จักถูกดีซีเรียลไลซ์ แผนที่จะทิ้งไว้เป็นแผนที่ ซึ่งช่วยให้นักพัฒนาแอปเพิ่มช่องที่มีประเภทใหม่ลงในค่าที่แสดงผลได้โดยไม่ทำให้ไคลเอ็นต์เวอร์ชันเก่าใช้งานไม่ได้

ตัวอย่างโค้ด

ตัวอย่างในส่วนนี้จะแสดงวิธีเข้ารหัสข้อมูลต่อไปนี้

• ตัวอย่าง callable.call ใน Swift
• การตอบกลับสําเร็จสําหรับการเรียก
• การตอบกลับที่ไม่สําเร็จสําหรับการเรียก

ตัวอย่าง Callable.call ใน Swift เพื่อนําเข้ารหัส

callable.call([
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23,
    "aLong": -123456789123456 as Int64
])

ส่วนหัวของคำขอ:

Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token

เนื้อหาคำขอ:

{
    "data": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23,
        "aLong": {
            "@type": "type.googleapis.com/google.protobuf.Int64Value",
            "value": "-123456789123456"
        }
    }
}

การตอบสนองต่อการเข้ารหัส

return {
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23
};

ส่วนหัวการตอบกลับที่สำเร็จ:

200 OK
Content-Type: application/json; charset=utf-8

เนื้อหาการตอบกลับที่สำเร็จ

{
    "response": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23
    }
}

ตอบสนองต่อการเข้ารหัสไม่สำเร็จ

throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
  "some-key": "some-value"
});

ส่วนหัวการตอบกลับที่ไม่สำเร็จ:

401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8

เนื้อหาการตอบกลับที่ไม่สำเร็จ:

{
    "error": {
        "message": "Request had invalid credentials.",
        "status": "UNAUTHENTICATED",
        "details": {
            "some-key": "some-value"
        }
    }
}