ข้อกำหนดโปรโตคอลสำหรับ 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 ของไคลเอ็นต์ควรถือว่าคำขอล้มเหลว ที่มีรหัสข้อผิดพลาดของ Google INTERNAL (13)

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

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

การเรียงอันดับ

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

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

เราอนุญาตประเภทต่อไปนี้

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

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

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

ยาว

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