مشغل https.onCall
للوظائف السحابية هو مشغل HTTPS بتنسيق محدد للطلب والاستجابة. يوفر هذا القسم مواصفات لطلب HTTPS وتنسيقات الاستجابة التي يستخدمها العميل SDKs لتنفيذ واجهة برمجة التطبيقات (API). قد تكون هذه المعلومات مفيدة لك إذا تعذر تلبية متطلباتك باستخدام أنظمة Android أو Apple أو مجموعات SDK للويب.
تنسيق الطلب: الرؤوس
يجب أن يكون طلب HTTP إلى نقطة نهاية المشغل القابلة للاستدعاء عبارة عن POST
بالرؤوس التالية:
- مطلوب:
Content-Type: application/json
- اختياري
; charset=utf-8
مسموح بها.
- اختياري
- اختياري:
Authorization: Bearer <token>
- رمز معرف مستخدم مصادقة Firebase للمستخدم الذي قام بتسجيل الدخول والذي يقدم الطلب. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز المميز وتجعله متاحًا في
context
المعالج. إذا كان الرمز غير صالح، فسيتم رفض الطلب.
- رمز معرف مستخدم مصادقة Firebase للمستخدم الذي قام بتسجيل الدخول والذي يقدم الطلب. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز المميز وتجعله متاحًا في
- اختياري:
Firebase-Instance-ID-Token: <iid>
- رمز تسجيل FCM من حزمة SDK لعميل Firebase. يجب أن يكون هذا سلسلة. هذا متاح في
context
المعالج. يتم استخدامه لاستهداف إشعارات الدفع.
- رمز تسجيل FCM من حزمة SDK لعميل Firebase. يجب أن يكون هذا سلسلة. هذا متاح في
- اختياري:
X-Firebase-AppCheck: <token>
- رمز Firebase App Check المميز الذي يقدمه تطبيق العميل الذي يقدم الطلب. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز المميز وتفك تشفيره، عن طريق إدخال
appId
فيcontext
المعالج. إذا تعذر التحقق من الرمز المميز، فسيتم رفض الطلب. (متوفر لـ SDK >=3.14.0)
- رمز Firebase App Check المميز الذي يقدمه تطبيق العميل الذي يقدم الطلب. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز المميز وتفك تشفيره، عن طريق إدخال
إذا تم تضمين أي رؤوس أخرى، فسيتم رفض الطلب، كما هو موضح في وثائق الاستجابة أدناه.
ملاحظة: في عملاء JavaScript، تؤدي هذه الطلبات إلى تشغيل الاختبار المبدئي لـ CORS OPTIONS
، للأسباب التالية:
-
application/json
غير مسموح به. يجب أن يكونtext/plain
أوapplication/x-www-form-urlencoded
. - رأس
Authorization
ليس رأس طلب مدرج في القائمة الآمنة لـ CORS . - الرؤوس الأخرى غير مسموح بها بالمثل.
يعالج المشغل القابل للاستدعاء طلبات OPTIONS
هذه تلقائيًا.
هيئة الطلب
يجب أن يكون نص طلب HTTP عبارة عن كائن JSON يحتوي على أي من الحقول التالية:
- مطلوب:
data
- الوسيطة التي تم تمريرها إلى الوظيفة. يمكن أن تكون هذه أي قيمة JSON صالحة. يتم فك تشفير هذا تلقائيًا إلى أنواع JavaScript أصلية وفقًا لتنسيق التسلسل الموضح أدناه.
إذا كانت هناك أي حقول أخرى موجودة في الطلب، فإن الواجهة الخلفية تعتبر الطلب غير صحيح، ويتم رفضه.
تنسيق الاستجابة: رموز الحالة
هناك العديد من الحالات التي قد تؤدي إلى رموز حالة HTTP مختلفة ورموز حالة سلسلة للأخطاء في الاستجابة.
في حالة حدوث خطأ HTTP قبل استدعاء مشغل
client
، لا تتم معالجة الاستجابة كوظيفة عميل. على سبيل المثال، إذا حاول العميل استدعاء وظيفة غير موجودة، فإنه يتلقى استجابة404 Not Found
.إذا تم استدعاء مشغل العميل، ولكن الطلب بتنسيق خاطئ، مثل أنه ليس JSON، أو يحتوي على حقول غير صالحة، أو يفتقد حقل
data
، فسيتم رفض الطلب بـ400 Bad Request
، مع رمز خطأINVALID_ARGUMENT
.إذا كان رمز المصادقة المقدم في الطلب غير صالح، فسيتم رفض الطلب باستخدام
401 Unauthorized
، مع رمز خطأUNAUTHENTICATED
.إذا كان رمز تسجيل FCM المقدم في الطلب غير صالح، فهذا يعني أن السلوك غير محدد. لا يتم التحقق من الرمز المميز في كل طلب، إلا عندما يتم استخدامه لإرسال إشعار دفع مع FCM.
إذا تم استدعاء المشغل القابل للاستدعاء، ولكنه فشل مع استثناء غير معالج أو قام بإرجاع وعد فاشل، فسيتم رفض الطلب مع وجود
500 Internal Server Error
الخادم، مع رمز خطأINTERNAL
. وهذا يمنع تعرض المستخدمين النهائيين لأخطاء الترميز عن طريق الخطأ.إذا تم استدعاء الكائن القابل للاستدعاء وإرجاع حالة خطأ صريحة باستخدام واجهة برمجة التطبيقات المتوفرة للوظائف القابلة للاستدعاء، فسيفشل الطلب. يعتمد رمز حالة HTTP الذي تم إرجاعه على التعيين الرسمي لحالة الخطأ إلى حالة HTTP، كما هو محدد في code.proto . يتم ترميز رمز الخطأ والرسالة والتفاصيل المحددة التي تم إرجاعها في نص الاستجابة كما هو مفصل أدناه. هذا يعني أنه إذا قامت الدالة بإرجاع خطأ صريح بالحالة
OK
، فستكون الاستجابة بالحالة200 OK
، ولكن تم تعيين حقلerror
في الاستجابة.إذا نجح مشغل العميل، فإن حالة الاستجابة هي
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 Mapping القياسي للأخطاء، مع حقولstatus
message
details
(اختياريًا). لا ينبغي تضمين حقلcode
. إذا كان حقلstatus
غير محدد، أو كان قيمة غير صالحة، فيجب على العميل التعامل مع الحالة على أنهاINTERNAL
، وفقًا لـ code.proto . إذا كانتdetails
موجودة، فسيتم تضمينها في أي معلومات مستخدم مرفقة بالخطأ في SDK للعميل، إن أمكن.
ملاحظة: حقلdetails
هنا عبارة عن قيمة مقدمة من المستخدم. إنها ليست بالضرورة قائمة من القيم التي يتم مفتاحها حسب النوع الأولي كما هو الحال في تنسيقStatus
Google. -
result
- القيمة التي يتم إرجاعها بواسطة الدالة. يمكن أن تكون هذه أي قيمة JSON صالحة. تقوم حزمة SDK لوظائف firebase تلقائيًا بتشفير القيمة التي أرجعها المستخدم إلى تنسيق JSON هذا. تقوم حزم SDK للعميل تلقائيًا بفك تشفير هذه المعلمات إلى أنواع أصلية وفقًا لتنسيق التسلسل الموضح أدناه.
في حالة وجود حقول أخرى، يجب تجاهلها.
التسلسل
تنسيق التسلسل لحمولات البيانات العشوائية هو نفسه لكل من الطلب والاستجابة.
من أجل تناسق النظام الأساسي، يتم ترميزها في JSON كما لو كانت قيمة Any
حقل في المخزن المؤقت لبروتوكول proto3، باستخدام تعيين JSON القياسي . يتم ترميز قيم الأنواع البسيطة مثل null
أو int
أو double
أو string
مباشرةً، ولا تتضمن نوعها الصريح. لذا، يتم تشفير float
double
بنفس الطريقة، وقد لا تعرف أيهما يتم استقباله على الطرف الآخر من المكالمة. بالنسبة للأنواع التي ليست أصلية في JSON، يتم استخدام تشفير proto3 المكتوب للقيمة. لمزيد من المعلومات، راجع الوثائق الخاصة بأي ترميز JSON .
يُسمح بالأنواع التالية:
- فارغة -
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
غير معروف، فسيتم تركها كخريطة. يتيح ذلك للمطورين إضافة حقول بأنواع جديدة إلى قيم الإرجاع الخاصة بهم دون فصل العملاء الأقدم.
عينات التعليمات البرمجية
توضح العينات الموجودة في هذا القسم كيفية تشفير ما يلي:
- مثال callable.call في سويفت
- استجابة ناجحة للدعوة
- فشل الاستجابة للمكالمة
مثال 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"
}
}
}