وظائف الاتصال من تطبيقك

الجيل الثاني الجيل الأول

تتيح لك حِزم تطوير البرامج (SDK) الخاصة بالعميل في Cloud Functions for Firebase استدعاء الدوال مباشرةً من تطبيق Firebase. ولاستدعاء دالة من تطبيقك بهذه الطريقة، عليك كتابة دالة HTTP قابلة للاستدعاء ونشرها في Cloud Functions، ثم إضافة منطق العميل لاستدعاء الدالة من تطبيقك.

من المهم أن تضع في اعتبارك أنّ الدوال القابلة للاستدعاء عبر HTTP تتشابه مع دوال HTTP ولكنها ليست متطابقة. لاستخدام الدوال القابلة للاستدعاء عبر HTTP، يجب استخدام حزمة تطوير البرامج (SDK) الخاصة بالعميل لمنصتك مع واجهة برمجة التطبيقات الخلفية (أو تنفيذ البروتوكول). تختلف الدوال القابلة للاستدعاء عن دوال HTTP في ما يلي:

• عند توفّر الرموز المميزة Firebase Authentication وFCM وApp Check، يتم تضمينها تلقائيًا في الطلبات مع العناصر القابلة للاستدعاء.
• يعمل المشغّل تلقائيًا على إلغاء تسلسل نص الطلب والتحقّق من صحة رموز المصادقة.

تتفاعل حزمة تطوير البرامج (SDK) Firebase للإصدار Cloud Functions من الجيل الثاني والإصدارات الأحدث مع الحد الأدنى من إصدارات حزمة تطوير البرامج (SDK) لعميل Firebase التالية من أجل إتاحة استخدام وظائف HTTPS Callable:

• ‫Firebase حزمة تطوير البرامج (SDK) لمنصات Apple‏ 11.15.0
• Firebase حزمة SDK للإصدار 21.2.1 من Android
• الإصدار 9.7.0 من حزمة تطوير البرامج (SDK) على الويب المعيارية من Firebase

إذا أردت إضافة وظائف مشابهة إلى تطبيق تم إنشاؤه على منصة غير متوافقة، يمكنك الاطّلاع على مواصفات البروتوكول الخاصة بـ https.onCall. تقدّم بقية هذا الدليل تعليمات حول كيفية كتابة دالة قابلة للاستدعاء عبر HTTP ونشرها واستدعائها على منصات Apple وAndroid والويب وC++ وUnity.

كتابة الدالة القابلة للاستدعاء ونشرها

تستند أمثلة الرموز البرمجية في هذا القسم إلى نموذج التشغيل السريع الكامل الذي يوضّح كيفية إرسال الطلبات إلى دالة من جهة الخادم وتلقّي رد باستخدام إحدى حِزم تطوير البرامج (SDK) من جهة العميل. للبدء، استورِد الوحدات المطلوبة:

Node.js

// Dependencies for callable functions.
const {onCall, HttpsError} = require("firebase-functions/v2/https");
const {logger} = require("firebase-functions/v2");

// Dependencies for the addMessage function.
const {getDatabase} = require("firebase-admin/database");
const sanitizer = require("./sanitizer");
index.js

Python

# Dependencies for callable functions.
from firebase_functions import https_fn, options

# Dependencies for writing to Realtime Database.
from firebase_admin import db, initialize_app
main.py

استخدِم معالج الطلبات الخاص بمنصتك (functions.https.onCall) أو on_call) لإنشاء دالة قابلة للاستدعاء عبر HTTPS. تتلقّى هذه الطريقة مَعلمة طلب:

Node.js

// Saves a message to the Firebase Realtime Database but sanitizes the
// text by removing swearwords.
exports.addmessage = onCall((request) => {
  // ...
});
index.js

Python

@https_fn.on_call()
def addmessage(req: https_fn.CallableRequest) -> Any:
    """Saves a message to the Firebase Realtime Database but sanitizes the text
    by removing swear words."""
main.py

تحتوي المَعلمة request على البيانات التي يتمّ تمريرها من تطبيق العميل بالإضافة إلى سياق إضافي مثل حالة المصادقة. بالنسبة إلى دالة قابلة للاستدعاء تحفظ رسالة نصية في Realtime Database، على سبيل المثال، يمكن أن يحتوي data على نص الرسالة، بالإضافة إلى معلومات المصادقة في auth:

Node.js

// Message text passed from the client.
const text = request.data.text;
// Authentication / user information is automatically added to the request.
const uid = request.auth.uid;
const name = request.auth.token.name || null;
const picture = request.auth.token.picture || null;
const email = request.auth.token.email || null;
index.js

Python

# Message text passed from the client.
text = req.data["text"]
main.py
# Authentication / user information is automatically added to the request.
uid = req.auth.uid
name = req.auth.token.get("name", "")
picture = req.auth.token.get("picture", "")
email = req.auth.token.get("email", "")
main.py

يمكن أن تؤدي المسافة بين موقع الدالة القابلة للاستدعاء وموقع العميل الذي يستدعيها إلى حدوث تأخير في الشبكة. لتحسين الأداء، ننصحك بتحديد موقع الدالة عند الاقتضاء، والتأكّد من تطابق موقع الدالة القابلة للاستدعاء مع الموقع الجغرافي الذي تم ضبطه عند إعداد حزمة تطوير البرامج (SDK) من جهة العميل.

يمكنك اختياريًا إرفاق App Check شهادة تصديق للمساعدة في حماية موارد الخلفية من إساءة الاستخدام، مثل الاحتيال في الفوترة أو التصيّد الاحتيالي. اطّلِع على تفعيل تنفيذ App Check في Cloud Functions.

ملاحظة: استخدِم فقط واجهات برمجة التطبيقات الخلفية functions.https أو firebase_functions.https_fn لكتابة دوال قابلة للاستدعاء. إنّ واجهة برمجة التطبيقات التي يتم تشغيلها عبر HTTP منفصلة تمامًا ولا يمكن تشغيلها بشكل متوافق مع الدوال القابلة للاستدعاء.

إرجاع النتيجة

لإرسال البيانات مرة أخرى إلى العميل، عليك إرجاع بيانات يمكن ترميزها بتنسيق JSON. على سبيل المثال، لعرض نتيجة عملية جمع:

Node.js

// returning result.
return {
  firstNumber: firstNumber,
  secondNumber: secondNumber,
  operator: "+",
  operationResult: firstNumber + secondNumber,
};
index.js

Python

return {
    "firstNumber": first_number,
    "secondNumber": second_number,
    "operator": "+",
    "operationResult": first_number + second_number
}
main.py

يتم إرجاع النص الذي تمت إزالة المعلومات الحساسة منه من مثال نص الرسالة إلى كل من العميل وRealtime Database. في Node.js، يمكن إجراء ذلك بشكل غير متزامن باستخدام وعد JavaScript:

Node.js

// Saving the new message to the Realtime Database.
const sanitizedMessage = sanitizer.sanitizeText(text); // Sanitize message.

return getDatabase().ref("/messages").push({
  text: sanitizedMessage,
  author: {uid, name, picture, email},
}).then(() => {
  logger.info("New Message written");
  // Returning the sanitized message to the client.
  return {text: sanitizedMessage};
})
index.js

Python

# Saving the new message to the Realtime Database.
sanitized_message = sanitize_text(text)  # Sanitize message.
db.reference("/messages").push({  # type: ignore
    "text": sanitized_message,
    "author": {
        "uid": uid,
        "name": name,
        "picture": picture,
        "email": email
    }
})
print("New message written")

# Returning the sanitized message to the client.
return {"text": sanitized_message}
main.py

إرسال نتائج البث المباشر وتلقّيها

تتضمّن الدوال القابلة للاستدعاء آليات للتعامل مع نتائج البث. إذا كان لديك حالة استخدام تتطلّب البث، يمكنك ضبط البث في الطلب القابل للاستدعاء، ثم استخدام الطريقة المناسبة من حزمة تطوير البرامج (SDK) الخاصة بالعميل لاستدعاء الدالة.

إرسال نتائج البث

للبث بكفاءة للنتائج التي يتم إنشاؤها بمرور الوقت، مثلاً من عدد من طلبات البيانات المنفصلة من واجهة برمجة التطبيقات أو من واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي، تحقَّق من السمة acceptsStreaming في طلبك القابل للاستدعاء. عند ضبط هذه السمة على true، يمكنك بث النتائج إلى العميل باستخدام response.sendChunk().

على سبيل المثال، إذا كان أحد التطبيقات بحاجة إلى استرداد بيانات توقعات الطقس لعدة مواقع جغرافية، يمكن للدالة القابلة للاستدعاء إرسال توقعات كل موقع جغرافي بشكل منفصل إلى العملاء الذين طلبوا استجابة متدفقة، بدلاً من الانتظار إلى أن يتم حل جميع طلبات التوقعات:

exports.getForecast = onCall(async (request, response) => {
  if (request.data?.locations?.length < 1) {
    throw new HttpsError("invalid-argument", "Missing locations to forecast");
  }

  // fetch forecast data for all requested locations
  const allRequests = request.data.locations.map(
      async ({latitude, longitude}) => {
        const forecast = await weatherForecastApi(latitude, longitude);
        const result = {latitude, longitude, forecast};

        // clients that support streaming will have each
        // forecast streamed to them as they complete
        if (request.acceptsStreaming) {
          response.sendChunk(result);
        }

        return result;
      },
  );

  // Return the full set of data to all clients
  return Promise.all(allRequests);
});
index.js

يُرجى العِلم أنّ طريقة عمل response.sendChunk() تعتمد على تفاصيل معيّنة من طلب العميل:

1. إذا طلب العميل استجابة بث مباشر: response.sendChunk(data) يتم إرسال جزء البيانات على الفور.

2. إذا لم يطلب العميل استجابة البث: response.sendChunk() لا يتم اتّخاذ أي إجراء بشأن هذه المكالمة. يتم إرسال الرد الكامل بعد أن تصبح جميع البيانات جاهزة.

لتحديد ما إذا كان العميل يطلب عرض الردود تدريجيًا، تحقَّق من السمة request.acceptsStreaming. على سبيل المثال، إذا كانت قيمة request.acceptsStreaming هي false، يمكنك اختيار تخطّي أي عمل يتطلّب موارد مكثّفة، خاصةً إذا كان مرتبطًا بإعداد أو إرسال أجزاء فردية، لأنّ العميل لا يتوقّع تسليمًا تدريجيًا.

تلقّي نتائج البث

في سيناريو نموذجي، يطلب العميل البث باستخدام طريقة .stream ثم يكرّر النتائج:

Swift

func listenToWeatherForecast() async throws {
    isLoading = true
    defer { isLoading = false }

    Functions
      .functions(region: "us-central1")
    let getForecast: Callable<WeatherRequest, StreamResponse<WeatherResponse, [WeatherResponse]>> = Functions.functions().httpsCallable("getForecast")

    let request = WeatherRequest(locations: locations)
    let stream = try getForecast.stream(request)

    for try await response in stream {
      switch response {
      case .message(let singleResponse):
        weatherData["\(singleResponse.latitude),\(singleResponse.longitude)"] = singleResponse
      case .result(let arrayOfResponses):
        for response in arrayOfResponses {
          weatherData["\(response.latitude),\(response.longitude)"] = response
        }
        print("Stream ended.")
        return
      }
    }
  }

Web

// Get the callable by passing an initialized functions SDK.
const getForecast = httpsCallable(functions, "getForecast");

// Call the function with the `.stream()` method to start streaming.
const { stream, data } = await getForecast.stream({
  locations: favoriteLocations,
});

// The `stream` async iterable returned by `.stream()`
// will yield a new value every time the callable
// function calls `sendChunk()`.
for await (const forecastDataChunk of stream) {
  // update the UI every time a new chunk is received
  // from the callable function
  updateUi(forecastDataChunk);
}

// The `data` promise resolves when the callable
// function completes.
const allWeatherForecasts = await data;
finalizeUi(allWeatherForecasts);
index.html

كرِّر stream async iterable كما هو موضّح. يشير انتظار data الوعد إلى العميل بأنّ الطلب قد اكتمل

Kotlin

// Get the callable by passing an initialized functions SDK.
val getForecast = functions.getHttpsCallable("getForecast");

// Call the function with the `.stream()` method and convert it to a flow
getForecast.stream(
  mapOf("locations" to favoriteLocations)
).asFlow().collect { response ->
  when (response) {
    is StreamResponse.Message -> {
      // The flow will emit a [StreamResponse.Message] value every time the
      // callable function calls `sendChunk()`.
      val forecastDataChunk = response.message.data as Map<String, Any>
      // Update the UI every time a new chunk is received
      // from the callable function
      updateUI(
        forecastDataChunk["latitude"] as Double,
        forecastDataChunk["longitude"] as Double,
        forecastDataChunk["forecast"] as Double,
      )
    }
    is StreamResponse.Result -> {
      // The flow will emit a [StreamResponse.Result] value when the
      // callable function completes.
      val allWeatherForecasts = response.result.data as List<Map<String, Any>>
      finalizeUI(allWeatherForecasts)
    }
  }
}
MainActivity.kt

لاستخدام وظيفة إضافة asFlow()، أضِف مكتبة org.jetbrains.kotlinx:kotlinx-coroutines-reactive كعنصر تابع إلى ملف build.gradle(.kts) الخاص بالتطبيق.

Java

// Get the callable by passing an initialized functions SDK.
HttpsCallableReference getForecast = mFunctions.getHttpsCallable("getForecast");
getForecast.stream(
  new HashMap<String, Object>() {{
    put("locations", favoriteLocations);
  }}
).subscribe(new Subscriber<StreamResponse>() {
  @Override
  public void onSubscribe(Subscription subscription) {
    subscription.request(Long.MAX_VALUE);
  }

  @Override
  public void onNext(StreamResponse streamResponse) {
    if (streamResponse instanceof StreamResponse.Message) {
      // The flow will emit a [StreamResponse.Message] value every time the
      // callable function calls `sendChunk()`.
      StreamResponse.Message response = (StreamResponse.Message) streamResponse;
      Map<String, Object> forecastDataChunk =
        (Map<String, Object>) response.getMessage().getData();
      // Update the UI every time a new chunk is received
      // from the callable function
      updateUI(
        (double) forecastDataChunk.get("latitude"),
        (double) forecastDataChunk.get("longitude"),
        (double) forecastDataChunk.get("forecast")
      );
    } else if(streamResponse instanceof StreamResponse.Result) {
      // The flow will emit a [StreamResponse.Result] value when the
      // callable function completes.
      StreamResponse.Result response = (StreamResponse.Result) streamResponse;
      List<Map<String, Object>> allWeatherForecasts =
        (List<Map<String, Object>>) response.getResult().getData();
      finalizeUI();
    }
  }

  @Override
  public void onError(Throwable throwable) {
    // an error occurred in the function
  }

  @Override
  public void onComplete() {

  }
});
MainActivity.java

ضبط سياسة مشاركة الموارد المتعدّدة المصادر (CORS)

استخدِم الخيار cors للتحكّم في المصادر التي يمكنها الوصول إلى وظيفتك.

تتضمّن الدوال القابلة للاستدعاء إعدادات CORS تلقائية للسماح بالطلبات من جميع المصادر. للسماح ببعض الطلبات الواردة من مصادر متعددة، وليس كلها، مرِّر قائمة بالنطاقات المحددة أو التعبيرات العادية التي يجب السماح بها. على سبيل المثال:

Node.js

const { onCall } = require("firebase-functions/v2/https");

exports.getGreeting = onCall(
  { cors: [/firebase\.com$/, "https://flutter.com"] },
  (request) => {
    return "Hello, world!";
  }
);

لحظر الطلبات من مصادر خارجية، اضبط سياسة cors على false.

معالجة الأخطاء

لضمان حصول العميل على تفاصيل مفيدة عن الخطأ، يجب عرض الأخطاء من دالة قابلة للاستدعاء من خلال طرح (أو عرض Promise مرفوض مع) مثيل functions.https.HttpsError أو https_fn.HttpsError في Node.js. يحتوي الخطأ على السمة code التي يمكن أن تكون إحدى القيم المدرَجة في رموز الحالة في gRPC. تحتوي الأخطاء أيضًا على السلسلة message، والتي تكون تلقائيًا سلسلة فارغة. يمكن أن تتضمّن أيضًا حقل details اختياريًا بقيمة عشوائية. إذا تم عرض خطأ آخر غير خطأ HTTPS من دوالك، سيتلقّى العميل بدلاً من ذلك خطأً مع الرسالة INTERNAL والرمز internal.

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

Node.js

// Checking attribute.
if (!(typeof text === "string") || text.length === 0) {
  // Throwing an HttpsError so that the client gets the error details.
  throw new HttpsError("invalid-argument", "The function must be called " +
          "with one arguments \"text\" containing the message text to add.");
}
// Checking that the user is authenticated.
if (!request.auth) {
  // Throwing an HttpsError so that the client gets the error details.
  throw new HttpsError("failed-precondition", "The function must be " +
          "called while authenticated.");
}
index.js

Python

# Checking attribute.
if not isinstance(text, str) or len(text) < 1:
    # Throwing an HttpsError so that the client gets the error details.
    raise https_fn.HttpsError(code=https_fn.FunctionsErrorCode.INVALID_ARGUMENT,
                              message=('The function must be called with one argument, "text",'
                                       " containing the message text to add."))

# Checking that the user is authenticated.
if req.auth is None:
    # Throwing an HttpsError so that the client gets the error details.
    raise https_fn.HttpsError(code=https_fn.FunctionsErrorCode.FAILED_PRECONDITION,
                              message="The function must be called while authenticated.")
main.py

نشر الدالة القابلة للاستدعاء

بعد حفظ دالة قابلة للاستدعاء مكتملة ضمن index.js، يتم نشرها مع جميع الدوال الأخرى عند تنفيذ firebase deploy. لنشر الوظيفة القابلة للاستدعاء فقط، استخدِم الوسيطة --only كما هو موضّح لتنفيذ عمليات نشر جزئية:

firebase deploy --only functions:addMessage

إذا واجهت أخطاء في الأذونات عند نشر الدوال، تأكَّد من أنّ أدوار إدارة الهوية وإمكانية الوصول (IAM) المناسبة ممنوحة للمستخدم الذي ينفّذ أوامر النشر.

إعداد بيئة تطوير البرنامج

تأكَّد من استيفاء أي متطلبات أساسية، ثم أضِف التبعيات ومكتبات البرامج المطلوبة إلى تطبيقك.

iOS+‎

اتّبِع التعليمات لإضافة Firebase إلى تطبيق Apple.

استخدِم أداة Swift Package Manager لتثبيت الموارد الاعتمادية في Firebase وإدارتها.

يمكنك الانتقال إلى دليل التثبيت للتعرّف على الطرق المختلفة التي يمكنك من خلالها إضافة حِزم تطوير البرامج (SDK) من Firebase إلى مشروعك على Apple، بما في ذلك استيراد الأُطر مباشرةً واستخدام CocoaPods.

1. في Xcode، بعد فتح مشروع تطبيقك، انتقِل إلى ملف > إضافة حِزم.
2. عندما يُطلب منك ذلك، أضِف مستودع حزمة تطوير البرامج (SDK) لمنصة Firebase على أجهزة Apple:

  https://github.com/firebase/firebase-ios-sdk.git

ملاحظة: يجب أن تستخدم المشاريع الجديدة إصدار حزمة SDK التلقائي (الأحدث)، ولكن يمكنك اختيار إصدار أقدم إذا لزم الأمر.
3. اختَر مكتبة Cloud Functions.
4. أضِف العلامة -ObjC إلى قسم علامات الربط الأخرى في إعدادات الإصدار الخاص بالكائن المستهدَف.
5. بعد الانتهاء، سيبدأ Xcode تلقائيًا في حلّ التبعيات وتنزيلها في الخلفية.

Web

1. اتّبِع التعليمات لإضافة Firebase إلى تطبيق الويب. احرص على تنفيذ الأمر التالي من نافذة الأوامر:

   npm install firebase@11.10.0 --save

2. يجب طلب كلّ من Firebase Core وCloud Functions يدويًا:

    import { initializeApp } from 'firebase/app';
    import { getFunctions } from 'firebase/functions';
   
    const app = initializeApp({
        projectId: '### CLOUD FUNCTIONS PROJECT ID ###',
        apiKey: '### FIREBASE API KEY ###',
        authDomain: '### FIREBASE AUTH DOMAIN ###',
      });
    const functions = getFunctions(app);

Android

1. اتّبِع التعليمات لإضافة Firebase إلى تطبيق Android.

2. في ملف Gradle للوحدة (على مستوى التطبيق) (عادةً <project>/<app-module>/build.gradle.kts أو <project>/<app-module>/build.gradle)، أضِف الاعتمادية لمكتبة Cloud Functions لنظام التشغيل Android. ننصحك باستخدام Firebase Android BoM للتحكّم في إصدارات المكتبة.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:33.16.0"))
   
       // Add the dependency for the Cloud Functions library
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-functions")
   }

   باستخدام Firebase Android BoM، سيستخدم تطبيقك دائمًا إصدارات متوافقة من مكتبات Firebase Android.

   (بديل)  أضِف تبعيات مكتبة Firebase بدون استخدام BoM

   إذا اخترت عدم استخدام Firebase BoM، عليك تحديد إصدار كل مكتبة من مكتبات Firebase في سطر التبعية الخاص بها.

   يُرجى العِلم أنّه في حال استخدام مكتبات Firebase BoMمتعدّدة في تطبيقك، ننصحك بشدة باستخدام BoM لإدارة إصدارات المكتبات، ما يضمن توافق جميع الإصدارات.

   dependencies {
       // Add the dependency for the Cloud Functions library
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-functions:21.2.1")
   }

   هل تبحث عن وحدة مكتبة خاصة بلغة Kotlin؟ اعتبارًا من أكتوبر 2023 (Firebase BoM 32.5.0)، يمكن لمطوّري Kotlin وJava الاستفادة من وحدة المكتبة الرئيسية (للحصول على التفاصيل، يُرجى الاطّلاع على الأسئلة الشائعة حول هذه المبادرة).

إعداد حزمة تطوير البرامج (SDK) الخاصة بالعميل

إعداد مثيل من Cloud Functions:

Swift

lazy var functions = Functions.functions()
CloudAddCell.swift

Objective-C

@property(strong, nonatomic) FIRFunctions *functions;
// ...
self.functions = [FIRFunctions functions];
CloudAddCell.m

Web

const app = initializeApp({
  projectId: '### CLOUD FUNCTIONS PROJECT ID ###',
  apiKey: '### FIREBASE API KEY ###',
  authDomain: '### FIREBASE AUTH DOMAIN ###',
});
const functions = getFunctions(app);

Kotlin

private lateinit var functions: FirebaseFunctions
// ...
functions = Firebase.functions
MainActivity.kt

Java

private FirebaseFunctions mFunctions;
// ...
mFunctions = FirebaseFunctions.getInstance();
MainActivity.java

ملاحظة: لاستدعاء دالة تعمل في أي موقع جغرافي غير الموقع الجغرافي التلقائي us-central1، يجب ضبط القيمة المناسبة عند التهيئة. على سبيل المثال، في نظام التشغيل Android، عليك ضبط القيمة الأولية على getInstance(FirebaseApp app, String region).

استدعاء الدالة

Swift

functions.httpsCallable("addMessage").call(["text": inputField.text]) { result, error in
  if let error = error as NSError? {
    if error.domain == FunctionsErrorDomain {
      let code = FunctionsErrorCode(rawValue: error.code)
      let message = error.localizedDescription
      let details = error.userInfo[FunctionsErrorDetailsKey]
    }
    // ...
  }
  if let data = result?.data as? [String: Any], let text = data["text"] as? String {
    self.resultField.text = text
  }
}
CommentCell.swift

Objective-C

[[_functions HTTPSCallableWithName:@"addMessage"] callWithObject:@{@"text": _inputField.text}
                                                      completion:^(FIRHTTPSCallableResult * _Nullable result, NSError * _Nullable error) {
  if (error) {
    if ([error.domain isEqual:@"com.firebase.functions"]) {
      FIRFunctionsErrorCode code = error.code;
      NSString *message = error.localizedDescription;
      NSObject *details = error.userInfo[@"details"];
    }
    // ...
  }
  self->_resultField.text = result.data[@"text"];
}];

Web

var addMessage = firebase.functions().httpsCallable('addMessage');
addMessage({ text: messageText })
  .then((result) => {
    // Read result of the Cloud Function.
    var sanitizedMessage = result.data.text;
  });
callable.js

Web

import { getFunctions, httpsCallable } from "firebase/functions";

const functions = getFunctions();
const addMessage = httpsCallable(functions, 'addMessage');
addMessage({ text: messageText })
  .then((result) => {
    // Read result of the Cloud Function.
    /** @type {any} */
    const data = result.data;
    const sanitizedMessage = data.text;
  });
fb_functions_call_add_message.js

Kotlin

private fun addMessage(text: String): Task<String> {
    // Create the arguments to the callable function.
    val data = hashMapOf(
        "text" to text,
        "push" to true,
    )

    return functions
        .getHttpsCallable("addMessage")
        .call(data)
        .continueWith { task ->
            // This continuation runs on either success or failure, but if the task
            // has failed then result will throw an Exception which will be
            // propagated down.
            val result = task.result?.data as String
            result
        }
}
MainActivity.kt

Java

private Task<String> addMessage(String text) {
    // Create the arguments to the callable function.
    Map<String, Object> data = new HashMap<>();
    data.put("text", text);
    data.put("push", true);

    return mFunctions
            .getHttpsCallable("addMessage")
            .call(data)
            .continueWith(new Continuation<HttpsCallableResult, String>() {
                @Override
                public String then(@NonNull Task<HttpsCallableResult> task) throws Exception {
                    // This continuation runs on either success or failure, but if the task
                    // has failed then getResult() will throw an Exception which will be
                    // propagated down.
                    String result = (String) task.getResult().getData();
                    return result;
                }
            });
}
MainActivity.java

Dart

    final result = await FirebaseFunctions.instance.httpsCallable('addMessage').call(
      {
        "text": text,
        "push": true,
      },
    );
    _response = result.data as String;

C++‎

firebase::Future<firebase::functions::HttpsCallableResult> AddMessage(
    const std::string& text) {
  // Create the arguments to the callable function.
  firebase::Variant data = firebase::Variant::EmptyMap();
  data.map()["text"] = firebase::Variant(text);
  data.map()["push"] = true;

  // Call the function and add a callback for the result.
  firebase::functions::HttpsCallableReference doSomething =
      functions->GetHttpsCallable("addMessage");
  return doSomething.Call(data);
}

Unity

private Task<string> addMessage(string text) {
  // Create the arguments to the callable function.
  var data = new Dictionary<string, object>();
  data["text"] = text;
  data["push"] = true;

  // Call the function and extract the operation from the result.
  var function = functions.GetHttpsCallable("addMessage");
  return function.CallAsync(data).ContinueWith((task) => {
    return (string) task.Result.Data;
  });
}

التعامل مع الأخطاء على الجهاز العميل

يتلقّى العميل رسالة خطأ إذا أرسل الخادم رسالة خطأ أو إذا تم رفض الوعد الناتج.

إذا كان الخطأ الذي تعرضه الدالة من النوع function.https.HttpsError، سيتلقّى العميل الخطأ code وmessage وdetails من خطأ الخادم. بخلاف ذلك، يحتوي الخطأ على الرسالة INTERNAL والرمز INTERNAL. اطّلِع على الإرشادات حول كيفية التعامل مع الأخطاء في الدالة القابلة للاستدعاء.

Swift

if let error = error as NSError? {
  if error.domain == FunctionsErrorDomain {
    let code = FunctionsErrorCode(rawValue: error.code)
    let message = error.localizedDescription
    let details = error.userInfo[FunctionsErrorDetailsKey]
  }
  // ...
}
CloudAddCell.swift

Objective-C

if (error) {
  if ([error.domain isEqual:@"com.firebase.functions"]) {
    FIRFunctionsErrorCode code = error.code;
    NSString *message = error.localizedDescription;
    NSObject *details = error.userInfo[@"details"];
  }
  // ...
}
CloudAddCell.m

Web

var addMessage = firebase.functions().httpsCallable('addMessage');
addMessage({ text: messageText })
  .then((result) => {
    // Read result of the Cloud Function.
    var sanitizedMessage = result.data.text;
  })
  .catch((error) => {
    // Getting the Error details.
    var code = error.code;
    var message = error.message;
    var details = error.details;
    // ...
  });
callable.js

Web

import { getFunctions, httpsCallable } from "firebase/functions";

const functions = getFunctions();
const addMessage = httpsCallable(functions, 'addMessage');
addMessage({ text: messageText })
  .then((result) => {
    // Read result of the Cloud Function.
    /** @type {any} */
    const data = result.data;
    const sanitizedMessage = data.text;
  })
  .catch((error) => {
    // Getting the Error details.
    const code = error.code;
    const message = error.message;
    const details = error.details;
    // ...
  });
fb_functions_call_add_message_error.js

Kotlin

addMessage(inputMessage)
    .addOnCompleteListener { task ->
        if (!task.isSuccessful) {
            val e = task.exception
            if (e is FirebaseFunctionsException) {
                val code = e.code
                val details = e.details
            }
        }
    }
MainActivity.kt

Java

addMessage(inputMessage)
  .addOnCompleteListener(new OnCompleteListener<String>() {
    @Override
    public void onComplete(@NonNull Task<String> task) {
      if (!task.isSuccessful()) {
        Exception e = task.getException();
        if (e instanceof FirebaseFunctionsException) {
          FirebaseFunctionsException ffe = (FirebaseFunctionsException) e;
          FirebaseFunctionsException.Code code = ffe.getCode();
          Object details = ffe.getDetails();
        }
      }
    }
  });
MainActivity.java

Dart

try {
  final result =
      await FirebaseFunctions.instance.httpsCallable('addMessage').call();
} on FirebaseFunctionsException catch (error) {
  print(error.code);
  print(error.details);
  print(error.message);
}

C++‎

void OnAddMessageCallback(
    const firebase::Future<firebase::functions::HttpsCallableResult>& future) {
  if (future.error() != firebase::functions::kErrorNone) {
    // Function error code, will be kErrorInternal if the failure was not
    // handled properly in the function call.
    auto code = static_cast<firebase::functions::Error>(future.error());

    // Display the error in the UI.
    DisplayError(code, future.error_message());
    return;
  }

  const firebase::functions::HttpsCallableResult* result = future.result();
  firebase::Variant data = result->data();
  // This will assert if the result returned from the function wasn't a string.
  std::string message = data.string_value();
  // Display the result in the UI.
  DisplayResult(message);
}

// ...

// ...
  auto future = AddMessage(message);
  future.OnCompletion(OnAddMessageCallback);
  // ...

Unity

 addMessage(text).ContinueWith((task) => {
  if (task.IsFaulted) {
    foreach (var inner in task.Exception.InnerExceptions) {
      if (inner is FunctionsException) {
        var e = (FunctionsException) inner;
        // Function error code, will be INTERNAL if the failure
        // was not handled properly in the function call.
        var code = e.ErrorCode;
        var message = e.ErrorMessage;
      }
    }
  } else {
    string result = task.Result;
  }
});

اقتراح: منع إساءة الاستخدام باستخدام App Check

قبل تشغيل تطبيقك، عليك تفعيل App Check للمساعدة في ضمان أنّ تطبيقاتك فقط هي التي يمكنها الوصول إلى نقاط نهاية الدوال القابلة للاستدعاء.