Firebase is back at Google I/O on May 10! Register now

مواصفات بروتوكول https.onCall

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

مشغل https.onCall لوظائف السحابة هو مشغل HTTPS بتنسيق محدد للطلب والاستجابة. يوفر هذا القسم مواصفات لتنسيقات طلب واستجابة HTTPS المستخدمة بواسطة مجموعات تطوير البرامج (SDK) الخاصة بالعميل لتنفيذ واجهة برمجة التطبيقات. قد تكون هذه المعلومات مفيدة لك إذا كان يتعذر تلبية متطلباتك باستخدام أنظمة Android أو أنظمة Apple الأساسية أو حزم تطوير البرامج على الويب.

تنسيق الطلب: رؤوس

يجب أن يكون طلب HTTP لنقطة نهاية المشغل القابلة للاستدعاء POST مع الرؤوس التالية:

  • مطلوب: Content-Type: application/json
    • اختياري ; charset=utf-8 مسموح به.
  • اختياري: Authorization: Bearer <token>
    • رمز مميز لمعرف مستخدم Firebase Authentication للمستخدم الذي قام بتسجيل الدخول والذي يقوم بالطلب. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز المميز وتجعله متاحًا في context المعالج. إذا كان الرمز المميز غير صالح ، فسيتم رفض الطلب.
  • اختياري: Firebase-Instance-ID-Token: <iid>
    • رمز تسجيل FCM المميز من حزمة SDK لعميل Firebase. يجب أن يكون هذا سلسلة. هذا متاح في context المعالج. يتم استخدامه لاستهداف دفع الإخطارات.
  • اختياري: X-Firebase-AppCheck: <token>
    • رمز Firebase App Check المميز الذي يوفره تطبيق العميل الذي يقوم بالطلب. تتحقق الواجهة الخلفية تلقائيًا من هذا الرمز المميز وتقوم بفك تشفيره ، عن طريق حقن appId في context المعالج. إذا تعذر التحقق من الرمز المميز ، فسيتم رفض الطلب. (متاح لـ SDK> = 3.14.0)

إذا تم تضمين أي رؤوس أخرى ، فسيتم رفض الطلب ، كما هو موضح في وثائق الاستجابة أدناه.

ملاحظة: في عملاء JavaScript ، تؤدي هذه الطلبات إلى تشغيل اختبار CORS OPTIONS المبدئي ، للأسباب التالية:

  • application/json غير مسموح به. يجب أن يكون text/plain أو application/x-www-form-urlencoded .
  • رأس Authorization ليس رأس طلب CORS-آمنًا .
  • رؤوس أخرى بالمثل غير مسموح بها.

يقوم المشغل القابل للاستدعاء بمعالجة طلبات OPTIONS هذه تلقائيًا.

طلب الهيئة

يجب أن يكون نص طلب HTTP كائن JSON مع أي من الحقول التالية:

  • مطلوب: data - تم تمرير الوسيطة إلى الوظيفة. يمكن أن يكون هذا أي قيمة JSON صالحة. يتم فك تشفير هذا تلقائيًا إلى أنواع JavaScript أصلية وفقًا لتنسيق التسلسل الموضح أدناه.

إذا كان هناك أي حقول أخرى موجودة في الطلب ، فإن الواجهة الخلفية تعتبر الطلب مشوهًا ، ويتم رفضه.

تنسيق الاستجابة: رموز الحالة

هناك العديد من الحالات التي يمكن أن تؤدي إلى رموز حالة HTTP ورموز حالة سلسلة مختلفة لأخطاء في الاستجابة.

  1. في حالة حدوث خطأ HTTP قبل استدعاء مشغل client ، لا يتم التعامل مع الاستجابة كوظيفة عميل. على سبيل المثال ، إذا حاول أحد العملاء استدعاء دالة غير موجودة ، فإنه يتلقى استجابة 404 Not Found .

  2. إذا تم استدعاء مشغل العميل ، ولكن الطلب بتنسيق خاطئ ، مثل عدم وجود JSON ، أو وجود حقول غير صالحة ، أو فقد حقل data ، فسيتم رفض الطلب مع 400 Bad Request ، مع رمز خطأ INVALID_ARGUMENT .

  3. إذا كان رمز المصادقة المقدم في الطلب غير صالح ، فسيتم رفض الطلب مع 401 Unauthorized ، مع وجود رمز خطأ UNAUTHENTICATED .

  4. إذا كان رمز تسجيل FCM المقدم في الطلب غير صالح ، فسيكون السلوك غير محدد. لا يتم فحص الرمز المميز في كل طلب ، إلا عند استخدامه لإرسال إشعار دفع باستخدام FCM.

  5. إذا تم استدعاء المشغل القابل للاستدعاء ، لكنه فشل مع استثناء غير معالج أو أعاد وعدًا فاشلاً ، فسيتم رفض الطلب مع 500 Internal Server Error ، مع رمز خطأ INTERNAL . هذا يمنع أخطاء الترميز من التعرض عن طريق الخطأ للمستخدمين النهائيين.

  6. إذا تم استدعاء الاستدعاء وأرجع حالة خطأ صريحة باستخدام API المقدمة للوظائف القابلة للاستدعاء ، يفشل الطلب. يعتمد رمز حالة HTTP الذي تم إرجاعه على التعيين الرسمي لحالة الخطأ إلى حالة HTTP ، كما هو محدد في code.proto . تم ترميز رمز الخطأ المحدد والرسالة والتفاصيل التي تم إرجاعها في نص الاستجابة كما هو مفصل أدناه. هذا يعني أنه إذا قامت الدالة بإرجاع خطأ صريح بالحالة " OK ، فسيكون للاستجابة الحالة 200 OK ، ولكن يتم تعيين حقل error في الاستجابة.

  7. إذا كان مشغل العميل ناجحًا ، تكون حالة الاستجابة 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"
        }
    }
}