Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Đặc tả giao thức cho https.onCall

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Trình kích hoạt https.onCall cho Chức năng đám mây là trình kích hoạt HTTPS có định dạng cụ thể cho yêu cầu và phản hồi. Phần này cung cấp đặc điểm kỹ thuật cho các định dạng phản hồi và yêu cầu HTTPS được sử dụng bởi SDK ứng dụng khách để triển khai API. Thông tin này có thể hữu ích cho bạn nếu không thể đáp ứng các yêu cầu của bạn bằng cách sử dụng các nền tảng Android, Apple hoặc SDK web.

Định dạng yêu cầu: tiêu đề

Yêu cầu HTTP tới một điểm cuối của trình kích hoạt có thể gọi phải là một POST với các tiêu đề sau:

  • Yêu cầu: Content-Type: application/json
    • Một tùy chọn ; charset=utf-8 được phép.
  • Tùy chọn: Authorization: Bearer <token>
    • Mã thông báo ID người dùng Xác thực Firebase cho người dùng đã đăng nhập thực hiện yêu cầu. Phần phụ trợ tự động xác minh mã thông báo này và làm cho nó có sẵn trong context của trình xử lý. Nếu mã thông báo không hợp lệ, yêu cầu sẽ bị từ chối.
  • Tùy chọn: Firebase-Instance-ID-Token: <iid>
    • Mã thông báo đăng ký FCM từ SDK ứng dụng khách Firebase. Đây phải là một chuỗi. Điều này có sẵn trong context của trình xử lý. Nó được sử dụng để nhắm mục tiêu các thông báo đẩy.
  • Tùy chọn: X-Firebase-AppCheck: <token>
    • Mã thông báo Kiểm tra ứng dụng Firebase được cung cấp bởi ứng dụng khách thực hiện yêu cầu. Phần phụ trợ tự động xác minh mã thông báo này và giải mã nó, đưa appId vào context của trình xử lý. Nếu không thể xác minh mã thông báo, yêu cầu sẽ bị từ chối. (Có sẵn cho SDK> = 3.14.0)

Nếu bất kỳ tiêu đề nào khác được bao gồm, yêu cầu sẽ bị từ chối, như được mô tả trong tài liệu phản hồi bên dưới.

Lưu ý: Trong các ứng dụng khách JavaScript, những yêu cầu này kích hoạt CORS OPTIONS xuất hiện trước, bởi vì:

  • application/json không được phép. Nó phải là text/plain hoặc application/x-www-form-urlencoded .
  • Tiêu đề Authorization không phải là tiêu đề yêu cầu được CORS bảo mật .
  • Các tiêu đề khác tương tự không được phép.

Trình kích hoạt có thể gọi tự động xử lý các yêu cầu OPTIONS này.

Nội dung yêu cầu

Nội dung của yêu cầu HTTP phải là một đối tượng JSON với bất kỳ trường nào sau đây:

  • Bắt buộc: data - Đối số được truyền cho hàm. Đây có thể là bất kỳ giá trị JSON hợp lệ nào. Điều này được tự động giải mã thành các loại JavaScript gốc theo định dạng tuần tự hóa được mô tả bên dưới.

Nếu có bất kỳ trường nào khác xuất hiện trong yêu cầu, chương trình phụ trợ sẽ coi yêu cầu không đúng định dạng và nó bị từ chối.

Định dạng phản hồi: mã trạng thái

Có một số trường hợp có thể dẫn đến các mã trạng thái HTTP khác nhau và mã trạng thái chuỗi gây ra lỗi trong phản hồi.

  1. Trong trường hợp xảy ra lỗi HTTP trước khi kích hoạt client được gọi, phản hồi không được xử lý như một chức năng ứng dụng khách. Ví dụ: nếu một ứng dụng khách cố gắng gọi một hàm không tồn tại, nó sẽ nhận được phản hồi 404 Not Found .

  2. Nếu trình kích hoạt ứng dụng được gọi, nhưng yêu cầu ở định dạng sai, chẳng hạn như không phải là JSON, có trường không hợp lệ hoặc thiếu trường data , thì yêu cầu sẽ bị từ chối với 400 Bad Request không hợp lệ, với mã lỗi là INVALID_ARGUMENT .

  3. Nếu mã thông báo xác thực được cung cấp trong yêu cầu không hợp lệ, yêu cầu sẽ bị từ chối với 401 Unauthorized , với mã lỗi là UNAUTHENTICATED .

  4. Nếu mã thông báo đăng ký FCM được cung cấp trong yêu cầu không hợp lệ, thì hành vi đó là không xác định. Mã thông báo không được kiểm tra trong mọi yêu cầu, ngoại trừ khi nó được sử dụng để gửi thông báo đẩy với FCM.

  5. Nếu trình kích hoạt có thể gọi được gọi, nhưng không thành công với một ngoại lệ chưa được xử lý hoặc trả về một lời hứa không thành công, yêu cầu sẽ bị từ chối với 500 Internal Server Error , với mã lỗi INTERNAL . Điều này ngăn các lỗi mã hóa vô tình bị phơi bày cho người dùng cuối.

  6. Nếu hàm có thể gọi được gọi và trả về một điều kiện lỗi rõ ràng bằng cách sử dụng API được cung cấp cho các hàm có thể gọi, thì yêu cầu không thành công. Mã trạng thái HTTP được trả về dựa trên ánh xạ chính thức của trạng thái lỗi sang trạng thái HTTP, như được định nghĩa trong code.proto . Mã lỗi cụ thể, thông báo và chi tiết trả về được mã hóa trong phần nội dung phản hồi như chi tiết bên dưới. Điều này có nghĩa là nếu hàm trả về một lỗi rõ ràng với trạng thái OK , thì phản hồi có trạng thái 200 OK , nhưng trường error được đặt trong phản hồi.

  7. Nếu kích hoạt ứng dụng khách thành công, trạng thái phản hồi là 200 OK .

Định dạng phản hồi: tiêu đề

Phản hồi có các tiêu đề sau:

  • Content-Type: application/json
  • Một tùy chọn ; charset=utf-8 được phép.

Cơ quan phản hồi

Phản hồi từ điểm cuối máy khách luôn là một đối tượng JSON. Ở mức tối thiểu, nó chứa result hoặc error , cùng với bất kỳ trường tùy chọn nào. Nếu phản hồi không phải là đối tượng JSON hoặc không chứa data hoặc error , SDK ứng dụng khách sẽ coi yêu cầu là không thành công với mã lỗi INTERNAL (13) của Google.

  • error - Nếu trường này xuất hiện, thì yêu cầu được coi là không thành công, bất kể mã trạng thái HTTP hoặc data có hiện diện hay không. Giá trị của trường này phải là một đối tượng JSON ở định dạng Google Cloud HTTP Mapping chuẩn đối với các lỗi, với các trường cho status , messagedetails (tùy chọn). Trường code sẽ không được bao gồm. Nếu trường status không được đặt hoặc là một giá trị không hợp lệ, ứng dụng khách phải coi trạng thái là INTERNAL , theo code.proto . Nếu có thông details , thông tin này sẽ được bao gồm trong bất kỳ thông tin người dùng nào được đính kèm với lỗi trong SDK ứng dụng khách, nếu có.
    Lưu ý: Trường details ở đây là giá trị do người dùng cung cấp. Nó không nhất thiết phải là danh sách các giá trị được nhập theo loại proto như ở định dạng Status Google.
  • result - Giá trị được trả về bởi hàm. Đây có thể là bất kỳ giá trị JSON hợp lệ nào. SDK firebase-functions tự động mã hóa giá trị do người dùng trả về thành định dạng JSON này. Các SDK ứng dụng khách tự động giải mã các tham số này thành các kiểu gốc theo định dạng tuần tự hóa được mô tả bên dưới.

Nếu các trường khác có mặt, chúng nên được bỏ qua.

Serialization

Định dạng tuần tự hóa cho các trọng tải dữ liệu tùy ý là giống nhau cho cả yêu cầu và phản hồi.

Để có tính nhất quán của nền tảng, chúng được mã hóa bằng JSON như thể chúng là giá trị của trường Any trong bộ đệm giao thức proto3, sử dụng ánh xạ JSON tiêu chuẩn . Giá trị của các kiểu đơn giản như null , int , double hoặc string được mã hóa trực tiếp và không bao gồm kiểu rõ ràng của chúng. Vì vậy, floatdouble được mã hóa theo cùng một cách, và bạn có thể không biết cái nào được nhận ở đầu bên kia của cuộc gọi. Đối với các loại không có nguồn gốc JSON, mã hóa proto3 đã nhập cho giá trị được sử dụng. Để biết thêm thông tin, hãy xem tài liệu về Bất kỳ mã hóa JSON nào .

Các loại sau được phép:

  • null - null
  • int (có dấu hoặc không dấu, tối đa 32 bit) - ví dụ: 3 hoặc -30 .
  • float - ví dụ: 3.14
  • gấp đôi - ví dụ: 3.14
  • boolean - true hay false
  • string - ví dụ: "hello world"
  • bản đồ - ví dụ: {"x": 3}
  • danh sách - ví dụ: [1, 2, 3]
  • dài (có dấu hoặc không dấu, tối đa 64 bit) - [xem bên dưới để biết chi tiết]

Các giá trị NaNInfinity cho floatdouble không được hỗ trợ.

Lưu ý rằng long là một kiểu đặc biệt thường không được phép trong JSON, nhưng được bao hàm bởi đặc tả proto3. Ví dụ: chúng được mã hóa thành:

Dài

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

không ký lâu

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

Nói chung, khóa @type nên được coi là dành riêng và không được sử dụng cho các bản đồ được chuyển vào.

Bởi vì kiểu không được chỉ định cho các kiểu đơn giản, một số giá trị sẽ thay đổi kiểu sau khi truyền qua dây. Một float được truyền vào sẽ trở thành một double . Một short trở thành một int , v.v. Trong Android, cả ListJSONArray đều được hỗ trợ cho các giá trị danh sách. Trong những trường hợp đó, chuyển trong JSONArray sẽ mang lại một List .

Nếu một bản đồ có trường @type không xác định được giải hóa, nó sẽ được giữ nguyên dưới dạng bản đồ. Điều này cho phép các nhà phát triển thêm các trường có kiểu mới vào giá trị trả về của chúng mà không làm hỏng các máy khách cũ hơn.

Mẫu mã

Các mẫu trong phần này minh họa cách mã hóa như sau:

  • Một ví dụ callable.call trong Swift
  • Một phản hồi thành công cho cuộc gọi
  • Phản hồi không thành công cho cuộc gọi

Ví dụ callable.call trong Swift để mã hóa

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

Tiêu đề yêu cầu:

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

Nội dung yêu cầu:

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

Phản hồi mã hóa

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

Tiêu đề phản hồi thành công:

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

Cơ quan phản hồi thành công:

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

Không thể phản hồi mã hóa

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

Tiêu đề phản hồi không thành công:

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

Nội dung phản hồi không thành công:

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