Catch up on everthing we announced at this year's Firebase Summit. Learn more

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

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

รูปแบบคำขอ: headers

การร้องขอ HTTP ไปยังปลายทางไก callable จะต้องเป็น POST ที่มีส่วนหัวต่อไปนี้:

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

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

หมายเหตุ: ลูกค้าใน JavaScript, คำขอเหล่านี้เรียกล ธ OPTIONS preflight เพราะ:

  • application/json ไม่ได้รับอนุญาต มันจะต้องเป็น text/plain หรือ application/x-www-form-urlencoded
  • Authorization หัวไม่ได้เป็น ล ธ -safelisted request-header
  • ไม่อนุญาตให้ใช้ส่วนหัวอื่นๆ ในทำนองเดียวกัน

ทริกเกอร์ callable โดยอัตโนมัติจัดการเหล่านี้ 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 ที่ให้มาในคำขอไม่ถูกต้อง ลักษณะการทำงานจะไม่ถูกกำหนด โทเค็นจะไม่ถูกตรวจสอบในทุกคำขอ ยกเว้นเมื่อมีการใช้เพื่อส่งการแจ้งเตือนแบบพุชกับ FCM

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

  6. หากเรียกใช้ callable และส่งคืนเงื่อนไขข้อผิดพลาดที่ชัดเจนโดยใช้ 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 ในมาตรฐาน ของ Google Cloud HTTP แมป รูปแบบสำหรับข้อผิดพลาดที่มีเขตข้อมูลสำหรับ status , message และ (ขยะ) details code ข้อมูลจะไม่ถูกรวมอยู่ หาก status ฟิลด์ล้างหรือเป็นค่าที่ไม่ถูกต้องลูกค้าควรรักษาสถานะเป็น INTERNAL ให้สอดคล้องกับ code.proto หาก details เป็นปัจจุบันมันจะรวมอยู่ในข้อมูลผู้ใช้ที่แนบมากับข้อผิดพลาดใน SDK ลูกค้าถ้ามีการใช้
    หมายเหตุ: details ข้อมูลที่นี่เป็นค่าที่ผู้ใช้จัด มันไม่จำเป็นต้องเป็นรายการของค่าคีย์ตามประเภทโปรโตในขณะที่ Google Status รูปแบบ
  • result - ค่าส่งกลับโดยฟังก์ชัน ค่านี้สามารถเป็นค่า JSON ที่ถูกต้องใดๆ ก็ได้ SDK ของฟังก์ชัน firebase จะเข้ารหัสค่าที่ผู้ใช้ส่งคืนโดยอัตโนมัติในรูปแบบ JSON นี้ SDK ของไคลเอ็นต์จะถอดรหัสพารามิเตอร์เหล่านี้เป็นประเภทเนทีฟโดยอัตโนมัติตามรูปแบบการทำให้เป็นอนุกรมที่อธิบายด้านล่าง

หากมีฟิลด์อื่นอยู่ ควรละเว้นฟิลด์เหล่านั้น

การทำให้เป็นอนุกรม

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

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

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

  • null - null
  • int (ลงนามหรือไม่ได้ลงนามถึง 32 บิต) - เช่น 3 หรือ -30
  • ลอย - เช่น 3.14
  • คู่ - เช่น 3.14
  • บูล - true หรือ false
  • สตริง - เช่น "hello world"
  • แผนที่ - เช่น {"x": 3}
  • รายการ - เช่น [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 ฟิลด์ deserialized มันเป็นซ้ายเป็นแผนที่ ซึ่งช่วยให้นักพัฒนาสามารถเพิ่มฟิลด์ที่มีประเภทใหม่ให้กับค่าที่ส่งคืนได้โดยไม่ทำลายไคลเอ็นต์รุ่นเก่า

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

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

  • ตัวอย่าง 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"
        }
    }
}