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

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

Một https.onCall kích hoạt cho Cloud Chức năng là một kích hoạt HTTPS với một định dạng cụ thể cho các request và response. Phần này cung cấp thông số 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 đề

Các yêu cầu HTTP đến một endpoint kích hoạt callable 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 cho 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. Các phụ trợ tự động xác minh này token và làm cho nó có sẵn trong của handler context . 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. Đây là có sẵn trong của handler context . 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. Các phụ trợ tự động xác minh này token và giải mã nó, tiêm appId trong của handler context . 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 ý: khách hàng Trong JavaScript, những yêu cầu kích hoạt một CORS OPTIONS preflight, bởi vì:

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

Cò callable tự động xử lý những OPTIONS yêu cầu.

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:

  • Yêu cầu: data - Đối số 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 mã trạng thái HTTP khác nhau và mã trạng thái chuỗi cho lỗi trong các phản ứng.

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

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

  3. Nếu auth thẻ được cung cấp trong yêu cầu là không hợp lệ, yêu cầu bị từ chối với 401 Unauthorized , với một mã lỗi của 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ệ, hành vi không được 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 cò callable được gọi, nhưng không thành công với một ngoại lệ unhandled hoặc trả về một lời hứa thất bại, yêu cầu bị từ chối với 500 Internal Server Error , với một mã lỗi của 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ề đ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. Các mã trạng thái HTTP trả về dựa trên các bản đồ chính thức của trạng thái lỗi HTTP status, theo quy định tại 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 rằng nếu hàm trả về một lỗi rõ ràng với tình trạng OK , sau đó phản ứng có tư cách 200 OK , nhưng error lĩnh vực được đặt trong các phản ứng.

  7. Nếu kích hoạt khách hàng là thành công, tình trạng phản ứng 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 cho 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. Tối thiểu nó có chứa một trong hai result hoặc error , cùng với bất kỳ lĩnh vực bắt buộc. Nếu câu trả lời không phải là một đối tượng JSON, hoặc không chứa data hoặc error , SDK khách hàng nên đối xử với các yêu cầu như thất bại với mã lỗi Google INTERNAL (13) .

  • error - Nếu lĩnh vực này là hiện nay, sau đó yêu cầu được coi là thất bại, không phụ thuộc vào mã trạng thái HTTP hay data cũng có mặt. Giá trị của trường này sẽ là một đối tượng JSON trong tiêu chuẩn Google Cloud HTTP Mapping định dạng cho các lỗi, với các lĩnh vực cho status , message , và (tùy chọn) details . Các code lĩnh vực sẽ không được đưa vào. Nếu status lĩnh vực là unset, hoặc là một giá trị không hợp lệ, khách hàng nên đối xử với các tình trạng như INTERNAL , phù hợp với code.proto . Nếu details là hiện nay, nó được bao gồm trong bất kỳ thông tin người dùng gắn liền với các lỗi trong SDK của khách hàng, nếu có.
    Lưu ý: Các details lĩnh vực đây là một giá trị do người dùng cung cấp. Nó không nhất thiết phải là một danh sách các giá trị keyed theo loại proto như trong Google Status định dạng.
  • result - Giá trị 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.

Đối với nền tảng thống nhất, đây là những mã hóa trong JSON như thể họ là những giá trị của một Any lĩnh vực trong một bộ đệm giao thức proto3, bằng cách sử dụng bản đồ JSON tiêu chuẩn . Giá trị của các loại đơn giản như null , int , double , hoặc string được mã hóa trực tiếp, và không bao gồm loại rõ ràng của họ. Vì vậy, một floatdouble được mã hóa theo cùng một cách, và bạn có thể không biết là đã nhận được ở đầ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, xem tài liệu hướng dẫn cho bất kỳ mã hóa JSON .

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

  • null - null
  • int (ký kết hoặc unsigned, lên đến 32 bit) - ví dụ như 3 hoặc -30 .
  • phao - ví dụ 3.14
  • đôi - ví dụ 3.14
  • boolean - true hay false
  • chuỗi - ví dụ như "hello world"
  • bản đồ - ví dụ như {"x": 3}
  • danh sách - ví dụ như [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]

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

Lưu ý rằng long là một loại đặc biệt thường không được cho phép trong JSON, nhưng được bao phủ bởi các đặc điểm kỹ thuậ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'
}

Nhìn chung, @type then chốt cần được xem xét dành riêng, và không được sử dụng cho các bản đồ thông qua 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 trôi qua trong trở thành một double . Một short trở thành một int , và vân vân. Trong Android, cả hai ListJSONArray được hỗ trợ cho giá trị danh sách. Trong những trường hợp, đi qua trong một JSONArray sẽ mang lại một List .

Nếu một bản đồ với một không rõ @type trường được deserialized, nó là trái như một 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
  • Một phản hồi thất bại 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"
        }
    }
}