مشغّل https.onCall
في Cloud Functions هو مشغّل HTTPS بتنسيق
محدّد للطلب والاستجابة. يقدم هذا القسم
مواصفات طلب HTTPS وتنسيقات الاستجابة التي تستخدمها حِزم تطوير البرامج (SDK) للعميل
لتطبيق واجهة برمجة التطبيقات. قد تكون هذه المعلومات مفيدة لك إذا كانت متطلباتك
باستخدام منصة Android أو Apple أو حزم تطوير البرامج (SDK) على الويب.
تنسيق الطلب: عناوين
يجب أن يكون طلب HTTP إلى نقطة نهاية مشغِّل قابلة للاستدعاء هو POST
مع
العناوين التالية:
- البيانات المطلوبة:
Content-Type: application/json
- يُسمح باستخدام
; charset=utf-8
اختياري.
- يُسمح باستخدام
- اختياري:
Authorization: Bearer <token>
- رمز مميّز لمعرّف المستخدم Firebase Authentication للمستخدم المسجّل الدخول الذي قدّم الطلب تحقّق الخلفية تلقائيًا من هذا الرمز المميّز وتوفّره في
context
للمعالج. إذا لم يكن الرمز المميّز صالحًا، يتم رفض الطلب.
- رمز مميّز لمعرّف المستخدم Firebase Authentication للمستخدم المسجّل الدخول الذي قدّم الطلب تحقّق الخلفية تلقائيًا من هذا الرمز المميّز وتوفّره في
- اختياري:
Firebase-Instance-ID-Token: <iid>
- رمز تسجيل "المراسلة عبر السحابة الإلكترونية من Firebase" من حزمة تطوير البرامج (SDK) لعميل Firebase يجب أن تكون سلسلة. يتوفّر هذا الإجراء في
context
للاسم المعرِّف. ويُستخدَم لاستهداف الإشعارات الفورية.
- رمز تسجيل "المراسلة عبر السحابة الإلكترونية من Firebase" من حزمة تطوير البرامج (SDK) لعميل Firebase يجب أن تكون سلسلة. يتوفّر هذا الإجراء في
- اختياري:
X-Firebase-AppCheck: <token>
- رمز فحص التطبيق من Firebase الذي يوفره التطبيق العميل الذي يُنشئ
طلبك. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز وتفككه،
إدخال
appId
فيcontext
للمعالج. إذا تعذّر تغيير الرمز المميّز تم التحقق منه، فسيتم رفض الطلب. (متاح لحِزم SDK التي تزيد عن أو تساوي 3.14.0)
- رمز فحص التطبيق من Firebase الذي يوفره التطبيق العميل الذي يُنشئ
طلبك. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز وتفككه،
إدخال
وفي حال تضمين أيّ رؤوس أخرى، سيتم رفض الطلب كما هو موضّح في مستندات الاستجابة أدناه.
ملاحظة: في برامج 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
.وإذا كان الرمز المميّز للتسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" المقدَّم في الطلب غير صالح، يصبح السلوك غير معروف. لا يتم التحقّق من الرمز المميّز في كل طلب، إلا عند استخدامه لإرسال إشعار فوري باستخدام ميزة "المراسلة من خلال السحابة الإلكترونية من Firebase".
إذا تمّ استدعاء عامل التشغيل القابل للاستدعاء، ولكن تعذّر إكماله بسبب استثناء لم تتم معالجته أو إذا تمّ إرجاع وعد تعذّر إكماله، يتم رفض الطلب باستخدام
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
، يجب أن يتعامل IDE
للعميل مع الطلب على أنّه تعذّر
برمز الخطأ INTERNAL (13)
من Google.
error
: في حال توفّر هذا الحقل، سيتم اعتبار الطلب غير صحيح، بغض النظر عن رمز حالة HTTP أو ما إذا كانdata
متوفّرًا أيضًا. يجب أن تكون قيمة هذا الحقل عنصرًا في تنسيق 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 المكتوب للقيمة. لمزيد من المعلومات، اطّلِع على مستندات ترميز Any JSON.
يُسمح بالأنواع التالية:
- قيمة فارغة -
null
- int (موقَّت أو غير موقَّت، بسعة تصل إلى 32 بت) - مثل
3
أو-30
- عدد عائم - على سبيل المثال
3.14
- مزدوج - على سبيل المثال:
3.14
- قيمة منطقية -
true
أوfalse
- سلسلة - على سبيل المثال
"hello world"
- خريطة<string, any=""> - مثال:
{"x": 3}
</string,> - قائمة
- على سبيل المثال [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"
}
}
}