Điều kiện kích hoạt https.onCall
cho Cloud Functions là một điều kiện 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
quy cách cho các định dạng phản hồi và yêu cầu HTTPS mà SDK ứng dụng sử dụng
để triển khai API. Thông tin này có thể hữu ích cho bạn nếu yêu cầu của bạn
không thể được đáp ứng bằng cách sử dụng nền tảng Android, Apple hoặc SDK web.
Định dạng yêu cầu: tiêu đề
Yêu cầu HTTP đến điểm cuối của điều kiện kích hoạt có thể gọi phải là POST
có phần tử
các tiêu đề sau:
- Bắt buộc:
Content-Type: application/json
- Bạn được phép sử dụng
; charset=utf-8
(không bắt buộc).
- Bạn được phép sử dụng
- Không bắt buộc:
Authorization: Bearer <token>
- Mã thông báo mã nhận dạng 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ợ sẽ tự động xác minh mã thông báo này và cung cấp mã 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.
- Mã thông báo mã nhận dạng 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ợ sẽ tự động xác minh mã thông báo này và cung cấp mã trong
- Không bắt buộc:
Firebase-Instance-ID-Token: <iid>
- Mã thông báo đăng ký FCM từ SDK ứng dụng Firebase. Đây phải là một chuỗi. Dữ liệu này có trong
context
của trình xử lý. Trường này được dùng để nhắm mục tiêu thông báo đẩy.
- Mã thông báo đăng ký FCM từ SDK ứng dụng Firebase. Đây phải là một chuỗi. Dữ liệu này có trong
- Không bắt buộc:
X-Firebase-AppCheck: <token>
- Mã thông báo Kiểm tra ứng dụng Firebase do ứng dụng khách cung cấp, giúp thực hiện
của bạn. Máy chủ phụ trợ tự động xác minh và giải mã mã thông báo này,
chèn
appId
vàocontext
của trình xử lý. Nếu mã thông báo không thể nên yêu cầu sẽ bị từ chối. (Có sẵn cho SDK >=3.14.0)
- Mã thông báo Kiểm tra ứng dụng Firebase do ứng dụng khách cung cấp, giúp thực hiện
của bạn. Máy chủ phụ trợ tự động xác minh và giải mã mã thông báo này,
chèn
Nếu có bất kỳ tiêu đề nào khác được đưa vào, thì 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 JavaScript, những yêu cầu này sẽ kích hoạt quy trình kiểm tra CORS OPTIONS
, vì:
application/json
là không được phép. Giá trị này phải làtext/plain
hoặcapplication/x-www-form-urlencoded
.- Tiêu đề
Authorization
không phải là tiêu đề của yêu cầu được đưa vào danh sách an toàn của CORS. - Tương tự, các tiêu đề khác cũng không được cho phép.
Điều kiện kích hoạt có thể gọi sẽ tự động xử lý các yêu cầu OPTIONS
này.
Nội dung yêu cầu
Phần nội dung của yêu cầu HTTP phải là đối tượng JSON có bất kỳ trường nào sau đây:
- Bắt buộc:
data
– Đối số được truyền vào hàm. Đây có thể là giá trị JSON hợp lệ bất kỳ. Hệ thống sẽ tự động giải mã này thành các loại JavaScript gốc theo định dạng chuyển đổi tuần tự được mô tả bên dưới.
Nếu có bất kỳ trường nào khác trong yêu cầu, phần phụ trợ sẽ coi yêu cầu đó là không đúng định dạng và sẽ 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 để tìm lỗi trong câu trả lời.
Trong trường hợp lỗi HTTP trước khi gọi điều kiện kích hoạt
client
, thì phản hồi sẽ không được xử lý như một hàm ứng dụng khách. Ví dụ: nếu ứng dụng cố gắng gọi một hàm không tồn tại, thì ứng dụng đó sẽ nhận được phản hồi404 Not Found
.Nếu trình kích hoạt ứng dụng được gọi nhưng yêu cầu ở định dạng không chính xác, 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 bằng400 Bad Request
, với mã lỗiINVALID_ARGUMENT
.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ệ, thì yêu cầu sẽ bị từ chối bằng
401 Unauthorized
với mã lỗiUNAUTHENTICATED
.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 sẽ không được xác định. Mã thông báo này không được kiểm tra trong mọi yêu cầu, trừ phi mã này được dùng để gửi thông báo đẩy bằng FCM.
Nếu điều kiện kích hoạt có thể gọi được gọi nhưng không thành công do trường hợp ngoại lệ chưa được xử lý hoặc trả về hứa hẹn không thành công, thì yêu cầu sẽ bị từ chối bằng
500 Internal Server Error
với mã lỗiINTERNAL
. Nhờ đó, người dùng cuối sẽ không vô tình nhìn thấy lỗi lập trình.Nếu đối tượng 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 sẽ không thành công. Mã trạng thái HTTP được trả về dựa trên mối liên kết chính thức giữa trạng thái lỗi với trạng thái HTTP, như định nghĩa trong code.proto. Mã lỗi cụ thể, thông báo và thông tin chi tiết được trả về được mã hoá trong nội dung phản hồi như trình bày chi tiết dưới đây. Tức là nếu hàm trả về một lỗi rõ ràng có trạng thái
OK
, thì phản hồi sẽ có trạng thái200 OK
, nhưng trườngerror
được đặt trong phản hồi.Nếu trình kích hoạt ứng dụng thành công, trạng thái phản hồi sẽ 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
- Bạn được phép sử dụng
; charset=utf-8
(không bắt buộc).
Nội dung phản hồi
Phản hồi của điểm cuối ứng dụng luôn là đối tượng JSON. Ở mức tối thiểu,
chứa result
hoặc error
, cùng với bất kỳ trường tuỳ 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 sẽ coi yêu cầu này là không thành công
bằng mã lỗi của Google INTERNAL (13)
.
error
– Nếu có trường này thì yêu cầu sẽ được coi là không thành công, bất kể có mã trạng thái HTTP hay không hoặc códata
hay không. Giá trị của trường này phải là đối tượng JSON ở định dạng Google Cloud HTTP Mapping tiêu chuẩn đối với các lỗi, với các trường chostatus
,message
vàdetails
(không bắt buộc)details
. Trườngcode
sẽ không được đưa vào. Nếu trườngstatus
chưa được đặt hoặc là một giá trị không hợp lệ, thì ứng dụng sẽ coi trạng thái làINTERNAL
theo code.proto. Nếu códetails
, thông tin này sẽ được đưa vào mọi thông tin người dùng đính kèm với lỗi trong SDK ứng dụng (nếu có).
Lưu ý: Trườngdetails
ở đây là giá trị do người dùng cung cấp. Đây không nhất thiết là danh sách các giá trị được khoá theo loại proto như ở định dạngStatus
của Google.result
– Giá trị được hàm trả về. Đây có thể là giá trị JSON hợp lệ bất kỳ. SDK hàm firebase tự động mã hoá giá trị do người dùng trả về thành định dạng JSON này. SDK ứng dụng tự động giải mã các thông số này thành kiểu gốc theo định dạng chuyển đổi tuần tự được mô tả bên dưới.
Nếu có các trường khác, bạn nên bỏ qua các trường đó.
Chuyển đổi tuần tự
Định dạng chuyển đổi tuần tự cho các tải trọng dữ liệu tuỳ ý là giống nhau đối với cả yêu cầu và phản hồi.
Để đảm bảo tính nhất quán của nền tảng, các mã này được mã hoá theo định dạng JSON như thể chúng là giá trị của trường Any
trong vùng đệm giao thức proto3 bằng cách sử dụng ánh xạ JSON tiêu chuẩn. Giá trị thuộc kiểu đơn giản như null
, int
, double
hoặc string
được mã hoá trực tiếp và không có loại rõ ràng. Vì vậy, float
và double
được mã hoá theo cùng một cách và có thể bạn không biết người nhận được nhận nội dung nào ở đầu bên kia của cuộc gọi. Đối với các loại không phải là mã gốc của JSON, phương thức mã hoá proto3 đã nhập cho giá trị sẽ được sử dụng. Để biết thêm thông tin, hãy xem tài liệu về mọi phương thức mã hoá JSON.
Các loại sau được cho phép:
- rỗng –
null
- int (đã ký hoặc chưa ký, tối đa 32 bit) - ví dụ:
3
hoặc-30
. - số thực có độ chính xác đơn, ví dụ:
3.14
- gấp đôi - ví dụ:
3.14
- boolean –
true
hoặcfalse
- string - ví dụ:
"hello world"
- ánh xạ<string, any=""> - ví dụ:
{"x": 3}
</string,> - danh sách
- ví dụ: [1, 2, 3]
- long (đã ký hoặc chưa ký, tối đa 64 bit) - [xem bên dưới để biết chi tiết]
Các giá trị NaN
và Infinity
cho float
và double
không được hỗ trợ.
Lưu ý long
là một loại đặc biệt thường không được phép trong JSON, nhưng được đề cập trong quy cách proto3. Ví dụ: các mã này được mã hoá như sau:
dài
{
'@type': 'type.googleapis.com/google.protobuf.Int64Value',
'value': '-123456789123456'
}
dài không dấu
{
'@type': 'type.googleapis.com/google.protobuf.UInt64Value',
'value': '123456789123456'
}
Nói chung, khoá @type
phải được coi là dành riêng và không được dùng cho những tệp ánh xạ được truyền vào.
Do kiểu dữ liệ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. float
được truyền vào sẽ trở thành double
. short
trở thành int
, và cứ tiếp tục như vậy. Trong Android, cả List
và JSONArray
đều được hỗ trợ cho các giá trị danh sách. Trong những trường hợp đó, việc truyền vào một JSONArray sẽ tạo ra List
.
Nếu bản đồ có trường @type
không xác định được giải tuần tự, thì bản đồ đó sẽ được để lại dưới dạng bản đồ. Điều này cho phép nhà phát triển thêm các trường chứa kiểu mới vào giá trị trả về mà không làm hỏng các ứng dụng cũ.
Mã mẫu
Các mẫu trong phần này minh hoạ cách mã hoá những nội dung sau:
- Ví dụ về callable.call trong Swift
- 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ụ về Callable.call trong Swift để mã hoá
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 với bộ mã hoá
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
Nội dung phản hồi thành công:
{
"response": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
}
}
Không phản hồi khi mã hoá
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"
}
}
}