Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

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

مشغل https.onCall السحابة هو مشغل HTTPS بتنسيق محدد للطلب والاستجابة. يوفر هذا القسم مواصفات لتنسيقات طلب واستجابة HTTPS المستخدمة بواسطة مجموعات SDK للعميل لتنفيذ واجهة برمجة التطبيقات. قد تكون هذه المعلومات مفيدة لك إذا كان لا يمكن تلبية متطلباتك باستخدام Android أو iOS أو Web SDK.

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

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

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

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

ملاحظة: في عملاء 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. إذا كان رمز المصادقة المقدم في الطلب غير صالح ، UNAUTHENTICATED رفض الطلب مع 401 Unauthorized ، مع وجود رمز خطأ 401 Unauthorized .

  4. إذا كان رمز معرف المثيل المقدم في الطلب غير صالح ، فسيكون السلوك غير محدد. لا يتم التحقق من رمز معرف المثيل في كل طلب ، إلا في حالة استخدامه لإرسال إشعار دفع باستخدام 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. كحد أدنى يحتوي إما على data أو 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.
  • data - القيمة التي تُرجعها الوظيفة. يمكن أن يكون هذا أي قيمة 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 غير معروف ، @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

هيئة الاستجابة الناجحة:

{
    "data": {
        "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"
        }
    }
}