مشغل https.onCall
لوظائف السحابة هو مشغل HTTPS بتنسيق محدد للطلب والاستجابة. يوفر هذا القسم مواصفات لتنسيقات طلب واستجابة HTTPS المستخدمة بواسطة مجموعات تطوير البرامج (SDK) الخاصة بالعميل لتنفيذ واجهة برمجة التطبيقات. قد تكون هذه المعلومات مفيدة لك إذا كان يتعذر تلبية متطلباتك باستخدام أنظمة Android أو أنظمة Apple الأساسية أو حزم تطوير البرامج على الويب.
تنسيق الطلب: رؤوس
يجب أن يكون طلب HTTP لنقطة نهاية المشغل القابلة للاستدعاء POST
مع الرؤوس التالية:
- مطلوب:
Content-Type: application/json
- اختياري
; charset=utf-8
مسموح به.
- اختياري
- اختياري:
Authorization: Bearer <token>
- رمز مميز لمعرف مستخدم Firebase Authentication للمستخدم الذي قام بتسجيل الدخول والذي يقوم بالطلب. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز المميز وتجعله متاحًا في
context
المعالج. إذا كان الرمز المميز غير صالح ، فسيتم رفض الطلب.
- رمز مميز لمعرف مستخدم Firebase Authentication للمستخدم الذي قام بتسجيل الدخول والذي يقوم بالطلب. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز المميز وتجعله متاحًا في
- اختياري:
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
. هذا يمنع أخطاء الترميز من التعرض عن طريق الخطأ للمستخدمين النهائيين.إذا تم استدعاء الاستدعاء وأرجع حالة خطأ صريحة باستخدام API المقدمة للوظائف القابلة للاستدعاء ، يفشل الطلب. يعتمد رمز حالة 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 -
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 في Swift
- استجابة ناجحة للمكالمة
- استجابة فشل للمكالمة
مثال 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"
}
}
}