ข้อกำหนดโปรโตคอลสำหรับ 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 จาก Firebase Client SDK ต้องเป็นสตริง ซึ่งอยู่ใน context ของแฮนเดิล ซึ่งใช้เพื่อกําหนดเป้าหมายข้อความ Push
• ไม่บังคับ: X-Firebase-AppCheck: <token>
  • โทเค็น Firebase App Check ที่ระบุโดยแอปไคลเอ็นต์ที่ส่งคำขอ แบ็กเอนด์จะยืนยันและถอดรหัสโทเค็นนี้โดยอัตโนมัติ โดยแทรก appId ใน context ของตัวแฮนเดิล หากยืนยันโทเค็นไม่ได้ ระบบจะปฏิเสธคำขอ (ใช้ได้กับ SDK ที่ใช้เวอร์ชันตั้งแต่ 3.14.0 ขึ้นไป)

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

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

• ไม่อนุญาต 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.proto หากมี details แสดงว่ารวมอยู่ในข้อมูลผู้ใช้ที่แนบมากับข้อผิดพลาดใน SDK ของไคลเอ็นต์ หากมี
  หมายเหตุ: ช่อง details ที่นี่คือค่าที่ผู้ใช้ระบุ โดยไม่จำเป็นต้องเป็นรายการค่าที่คีย์ตามโปรโตไทป์เหมือนในรูปแบบ Status ของ Google
• result - ค่าที่ฟังก์ชันแสดงผล ค่านี้อาจเป็นค่า JSON ที่ถูกต้องใดก็ได้ firebase-functions SDK จะเข้ารหัสค่าที่ผู้ใช้แสดงผลเป็นรูปแบบ JSON นี้โดยอัตโนมัติ SDK ของไคลเอ็นต์จะถอดรหัสพารามิเตอร์เหล่านี้เป็นประเภทเนทีฟโดยอัตโนมัติตามรูปแบบการทำให้เป็นอนุกรมที่อธิบายไว้ด้านล่าง

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

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

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

ระบบจะเข้ารหัสข้อมูลเหล่านี้เป็น JSON ราวกับว่าเป็นค่าของช่อง Any ในบัฟเฟอร์โปรโตคอล proto3 โดยใช้การแมป 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"
• map<string, any=""> - เช่น {"x": 3}</string,>
• list - เช่น [1, 2, 3]
• long (signed or unsigned, up to 64 bits) - [ดูรายละเอียดด้านล่าง]

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

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

ยาว

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

unsigned long

{
    '@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"
        }
    }
}