Trang này được dịch bởi Cloud Translation API.

Thông số kỹ thuật của giao thức cho https.onCall

Một trình kích hoạt https.onCall cho Cloud Functions là một 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 một quy cách cho các định dạng yêu cầu và phản hồi 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 các yêu cầu của bạn không thể đáp ứng bằng SDK Android, Apple hoặc web.

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

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

Bắt buộc: Content-Type: application/json
- Bạn có thể dùng ; charset=utf-8 (không bắt buộc).
Không bắt buộc: Authorization: Bearer <token>
- Mã thông báo mã nhận dạng người dùng Firebase Authentication cho người dùng đã đăng nhập đưa ra 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ã thông báo đó 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.
Không bắt buộc: Firebase-Instance-ID-Token: <iid>
- Mã thông báo đăng ký FCM từ Firebase Client SDK. Đây phải là một chuỗi. Thông tin này có trong context của trình xử lý. Mã này được dùng để nhắm mục tiêu thông báo đẩy.
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 đưa ra khi gửi yêu cầu. Phần phụ trợ sẽ tự động xác minh mã thông báo này và giải mã mã thông báo đó, chèn appId vào context của trình xử lý. Nếu không xác minh được mã thông báo, yêu cầu sẽ bị từ chối. (Dành cho SDK >=3.14.0)

Nếu có bất kỳ tiêu đề nào khác, yêu cầu sẽ bị từ chối, như 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 một yêu cầu kiểm tra trước CORS OPTIONS, vì:

application/json là không được phép. Giá trị này 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 đưa vào danh sách an toàn của CORS.
Các tiêu đề khác cũng không được phép.

Trình 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

Nội dung của yêu cầu HTTP phải là một đố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à bất kỳ giá trị JSON hợp lệ nào. Thao tác này sẽ tự động giải mã thành các loại JavaScript gốc theo định dạng tuần tự hoá được mô tả bên dưới.

Nếu có bất kỳ trường nào khác trong yêu cầu, thì phần phụ trợ sẽ coi yêu cầu đó là không hợp lệ và yêu cầu đó 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 và mã trạng thái chuỗi khác nhau cho lỗi trong phản hồi.

Trong trường hợp xảy ra lỗi HTTP trước khi lệnh kích hoạt client được gọi, phản hồi sẽ không được xử lý dưới dạng một hàm ứng dụng. Ví dụ: nếu một ứ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ồi 404 Not Found.
Nếu lệnh kích hoạt ứng dụng được gọi nhưng yêu cầu có định dạng không chính xác (chẳng hạn như không phải là JSON, có cá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ằng 400 Bad Request, với mã lỗi là INVALID_ARGUMENT.
Nếu mã thông báo uỷ quyền đượ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ỗi là UNAUTHENTICATED.
Nếu mã thông báo đăng ký FCM được cung cấp trong yêu cầu là không hợp lệ, thì hành vi sẽ không xác định. Mã thông báo không được kiểm tra trên mọi yêu cầu, ngoại trừ khi được dùng để gửi thông báo đẩy bằng FCM.
Nếu phương thức kích hoạt có thể gọi được gọi nhưng không thành công do 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, thì yêu cầu sẽ bị từ chối bằng 500 Internal Server Error, với mã lỗi là INTERNAL. Điều này giúp ngăn chặn các lỗi mã hoá vô tình bị lộ cho người dùng cuối.
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 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à trạng thái HTTP, như được xác định trong code.proto. Mã lỗi, thông báo và thông tin chi tiết cụ thể được mã hoá trong nội dung phản hồi như mô 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 có trạng thái OK, thì phản hồi sẽ có trạng thái 200 OK, nhưng trường error được đặt trong phản hồi.
Nếu lệnh kích hoạt của ứ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ó thể dùng ; charset=utf-8 (không bắt buộc).

Nội dung phản hồi

Phản hồi từ một điểm cuối của ứng dụng 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 mọi trường không bắt buộc. Nếu phản hồi không phải là một đối tượng JSON hoặc không chứa data hoặc error, thì SDK ứng dụng nên 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 liệu data có xuất hiện hay không. Giá trị của trường này phải là một đối tượng JSON theo định dạng Google Cloud HTTP Mapping tiêu chuẩn cho các lỗi, có các trường cho status, message và (không bắt buộc) details. Bạn không được thêm trường code. Nếu trường status chưa được đặt hoặc là một giá trị không hợp lệ, thì ứng dụng nên coi trạng thái này là INTERNAL, theo code.proto. Nếu có details, thì mã này sẽ được đưa vào mọi thông tin người dùng được đính kèm với lỗi trong SDK ứng dụng (nếu có).
Lưu ý: Trường details ở đâ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 giao thức như trong định dạng Status của Google.
result – Giá trị do hàm trả về. Đây có thể là bất kỳ giá trị JSON hợp lệ nào. SDK firebase-functions tự động mã hoá giá trị mà người dùng trả về thành định dạng JSON này. Các SDK ứng dụng sẽ tự động giải mã những tham số này thành các loại gốc theo định dạng tuần tự hoá được mô tả bên dưới.

Nếu có các trường khác, bạn nên bỏ qua.

Tuần tự hoá

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

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

Bạn được phép sử dụng các loại sau:

null — null
int (có dấu hoặc không dấu, tối đa 32 bit) – ví dụ: 3 hoặc -30.
số thực có độ chính xác đơn – ví dụ: 3.14
double – ví dụ: 3.14
boolean – true hoặc false
chuỗi – ví dụ: "hello world"
map<string, any=""> – ví dụ: {"x": 3}</string,>
list – ví dụ: [1, 2, 3]
long (có dấu hoặc không dấu, tối đa 64 bit) – [xem bên dưới để biết thông tin chi tiết]

Không hỗ trợ các giá trị NaN và Infinity cho float và double.

Xin lưu ý rằng long là một loại đặc biệt thường không được phép dùng trong JSON, nhưng được quy định trong thông số kỹ thuật proto3. Ví dụ: các giá trị này được mã hoá như sau:

dài

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

unsigned long

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

Nhìn chung, bạn nên coi khoá @type là khoá dành riêng và không dùng cho các bản đồ được truyền vào.

Vì loại không được chỉ định cho các loại đơn giản, nên một số giá trị sẽ thay đổi loại sau khi truyền qua mạng. float được truyền vào sẽ trở thành double. short trở thành int, v.v. 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 một List.

Nếu một bản đồ có trường @type không xác định được chuyển đổi tuần tự, thì bản đồ đó sẽ vẫn là một bản đồ. Điều này cho phép nhà phát triển thêm các trường có 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 lệnh gọi
Phản hồi thất bại cho lệnh 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 cần 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 được yêu cầu 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"
        }
    }
}