مشخصات پروتکل برای https.onCall

یک راه‌انداز https.onCall برای توابع ابری یک راه‌انداز HTTPS با فرمت خاصی برای درخواست و پاسخ است. این بخش مشخصاتی را برای فرمت های درخواست و پاسخ HTTPS که توسط SDK های مشتری برای پیاده سازی API استفاده می شود، ارائه می دهد. این اطلاعات ممکن است برای شما مفید باشد اگر نیازهای شما با استفاده از پلتفرم‌های Android، Apple یا وب 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 کنترل کننده موجود است. برای هدف قرار دادن اعلان های فشار استفاده می شود.
  • اختیاری: X-Firebase-AppCheck: <token>
    • نشانه بررسی برنامه Firebase که توسط برنامه مشتری درخواست کننده ارائه شده است. Backend به طور خودکار این نشانه را تأیید می کند و آن را رمزگشایی می کند و appId در context کنترل کننده تزریق می کند. اگر رمز قابل تأیید نباشد، درخواست رد می شود. (در دسترس برای SDK >=3.14.0)

اگر سرصفحه دیگری گنجانده شود، درخواست رد می شود، همانطور که در مستندات پاسخ زیر توضیح داده شده است.

توجه: در کلاینت‌های جاوا اسکریپت، این درخواست‌ها پیش از پرواز CORS OPTIONS را راه‌اندازی می‌کنند، زیرا:

ماشه قابل فراخوانی به طور خودکار این درخواست های OPTIONS را مدیریت می کند.

درخواست بدن

بدنه درخواست HTTP باید یک شی JSON با هر یک از فیلدهای زیر باشد:

  • مورد نیاز: data - آرگومان ارسال شده به تابع. این می تواند هر مقدار JSON معتبر باشد. این به طور خودکار به انواع جاوا اسکریپت بومی با توجه به فرمت سریال‌سازی شرح داده شده در زیر رمزگشایی می‌شود.

اگر فیلدهای دیگری در درخواست وجود داشته باشد، باطن درخواست را نادرست می‌داند و رد می‌شود.

قالب پاسخ: کدهای وضعیت

چندین مورد وجود دارد که می تواند منجر به کدهای وضعیت 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 تنظیم نشده باشد یا یک مقدار نامعتبر باشد، مشتری باید وضعیت را مطابق با code.proto به عنوان INTERNAL تلقی کند. اگر details وجود داشته باشد، در صورت وجود، در هر اطلاعات کاربری پیوست شده به خطا در SDK کلاینت گنجانده می شود.
    توجه: فیلد details در اینجا یک مقدار ارائه شده توسط کاربر است. این لزوماً فهرستی از مقادیر کلید شده بر اساس نوع پروتو مانند قالب Google Status نیست.
  • result - مقدار بازگشتی توسط تابع. این می تواند هر مقدار JSON معتبر باشد. Firebase-functions SDK به طور خودکار مقدار بازگردانده شده توسط کاربر را در قالب JSON رمزگذاری می کند. SDK های مشتری به طور خودکار این پارامترها را به انواع بومی با توجه به فرمت سریال سازی که در زیر توضیح داده شده است رمزگشایی می کنند.

در صورت وجود فیلدهای دیگر، باید آنها را نادیده گرفت.

سریال سازی

فرمت سریال سازی برای بارهای داده دلخواه هم برای درخواست و هم برای پاسخ یکسان است.

برای سازگاری پلتفرم، اینها در JSON به گونه‌ای کدگذاری می‌شوند که گویی مقدار یک فیلد Any در بافر پروتکل پروتکل ۳ هستند، با استفاده از نگاشت استاندارد 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 تبدیل می شود و غیره. در اندروید، هر دو List و JSONArray برای مقادیر لیست پشتیبانی می شوند. در این موارد، عبور از JSONArray یک List به دست می دهد.

اگر نقشه ای با یک فیلد @type ناشناخته از سریال خارج شود، به عنوان نقشه باقی می ماند. این به توسعه دهندگان اجازه می دهد تا فیلدهایی را با انواع جدید به مقادیر بازگشتی خود بدون شکستن مشتریان قدیمی اضافه کنند.

نمونه کد

نمونه های موجود در این بخش نحوه رمزگذاری موارد زیر را نشان می دهند:

  • یک مثال callable.call در سوئیفت
  • پاسخ موفقیت آمیز برای تماس
  • پاسخ ناموفق برای تماس

مثال Callable.call در سوئیفت برای رمزگذاری 

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"
        }
    }
}