توابع تماس از برنامه شما (نسل اول)

Cloud Functions for Firebase به شما امکان می‌دهند توابع را مستقیماً از یک برنامه فایربیس فراخوانی کنید. برای فراخوانی یک تابع از برنامه خود به این روش، یک تابع قابل فراخوانی HTTP را در Cloud Functions بنویسید و مستقر کنید، و سپس منطق کلاینت را برای فراخوانی تابع از برنامه خود اضافه کنید.

مهم است که به خاطر داشته باشید که توابع قابل فراخوانی HTTP مشابه توابع HTTP هستند اما دقیقاً یکسان نیستند . برای استفاده از توابع قابل فراخوانی HTTP، باید از SDK کلاینت برای پلتفرم خود به همراه API بک‌اند (یا پیاده‌سازی پروتکل) استفاده کنید. توابع قابل فراخوانی این تفاوت‌های کلیدی را با توابع HTTP دارند:

  • با استفاده از موارد قابل فراخوانی، توکن‌های Firebase Authentication ، توکن‌های FCM و توکن‌های App Check ، در صورت وجود، به طور خودکار در درخواست‌ها گنجانده می‌شوند.
  • تریگر به طور خودکار بدنه درخواست را deserialize کرده و توکن‌های احراز هویت را اعتبارسنجی می‌کند.

کیت توسعه نرم‌افزار Firebase برای Cloud Functions نسل دوم و بالاتر با حداقل نسخه‌های SDK کلاینت فایربیس زیر برای پشتیبانی از توابع قابل فراخوانی HTTPS همکاری می‌کند:

  • کیت توسعه نرم‌افزار Firebase برای پلتفرم‌های Apple ۱۲.۴.۰
  • کیت توسعه نرم‌افزار Firebase برای Android ۲۲.۰.۱
  • کیت توسعه نرم‌افزار وب ماژولار فایربیس نسخه ۹.۷.۰

اگر می‌خواهید قابلیت‌های مشابهی را به برنامه‌ای که روی یک پلتفرم پشتیبانی نشده ساخته شده است اضافه کنید، به مشخصات پروتکل https.onCall مراجعه کنید. بقیه این راهنما دستورالعمل‌هایی در مورد نحوه نوشتن، استقرار و فراخوانی یک تابع قابل فراخوانی HTTP برای پلتفرم‌های اپل، اندروید، وب، C++ و Unity ارائه می‌دهد.

تابع قابل فراخوانی را بنویسید و مستقر کنید

از functions.https.onCall برای ایجاد یک تابع قابل فراخوانی HTTPS استفاده کنید. این متد دو پارامتر می‌گیرد: data و optional context :

  // Saves a message to the Firebase Realtime Database but sanitizes the
  // text by removing swearwords.
  exports.addMessage = functions.https.onCall((data, context) => {
    // ...
  });
  

برای مثال، برای یک تابع قابل فراخوانی که یک پیام متنی را در Realtime Database ذخیره می‌کند، data می‌توانند شامل متن پیام باشند، در حالی که پارامترهای context نشان‌دهنده اطلاعات احراز هویت کاربر هستند:

// 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;

فاصله بین محل تابع فراخوانی شونده و محل کلاینت فراخوانی کننده می‌تواند باعث تأخیر شبکه شود. برای بهینه‌سازی عملکرد، در صورت لزوم، مکان تابع را مشخص کنید و مطمئن شوید که هنگام مقداردهی اولیه SDK در سمت کلاینت، مکان تابع فراخوانی شونده را با مکان تنظیم شده هم‌تراز می‌کنید.

در صورت تمایل، می‌توانید یک گواهی App Check ضمیمه کنید تا از منابع پشتیبان خود در برابر سوءاستفاده، مانند کلاهبرداری در صورتحساب یا فیشینگ، محافظت کنید. برای Cloud Functions به بخش «فعال کردن اجرای App Check مراجعه کنید.

ارسال مجدد نتیجه

برای ارسال داده‌ها به کلاینت، داده‌هایی را برگردانید که می‌توانند به صورت JSON کدگذاری شوند. برای مثال، برای برگرداندن نتیجه یک عملیات جمع:

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

برای بازگرداندن داده‌ها پس از یک عملیات ناهمزمان، یک promise را برگردانید. داده‌های برگردانده شده توسط promise به کلاینت ارسال می‌شوند. برای مثال، می‌توانید متن sanitized شده‌ای را که تابع فراخوانی شده در Realtime Database نوشته است، برگردانید:

// 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};
})

مدیریت خطاها

برای اطمینان از اینکه کلاینت جزئیات خطای مفیدی را دریافت می‌کند، با پرتاب کردن (یا بازگرداندن یک Promise رد شده با) یک نمونه از functions.https.HttpsError ، خطاها را از یک تابع قابل فراخوانی برگردانید. خطا دارای یک ویژگی code است که می‌تواند یکی از مقادیر ذکر شده در functions.https.HttpsError باشد. خطاها همچنین دارای یک message رشته‌ای هستند که به طور پیش‌فرض یک رشته خالی است. آنها همچنین می‌توانند یک فیلد details اختیاری با مقدار دلخواه داشته باشند. اگر خطایی غیر از HttpsError از توابع شما پرتاب شود، کلاینت شما به جای آن خطایی با پیام INTERNAL و کد internal دریافت می‌کند.

برای مثال، یک تابع می‌تواند خطاهای اعتبارسنجی داده‌ها و احراز هویت را به همراه پیام‌های خطا به کلاینت فراخواننده ارسال کند:

// 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 ذخیره کردید، هنگام اجرای firebase deploy این تابع به همراه تمام توابع دیگر مستقر می‌شود. برای استقرار فقط تابع فراخوانی‌شده، از آرگومان --only همانطور که نشان داده شده است برای انجام استقرارهای جزئی استفاده کنید:

firebase deploy --only functions:addMessage

اگر هنگام استقرار توابع با خطاهای مجوز مواجه شدید، مطمئن شوید که نقش‌های IAM مناسب به کاربری که دستورات استقرار را اجرا می‌کند، اختصاص داده شده است.

محیط توسعه کلاینت خود را تنظیم کنید

مطمئن شوید که پیش‌نیازها را رعایت می‌کنید، سپس وابستگی‌ها و کتابخانه‌های کلاینت مورد نیاز را به برنامه خود اضافه کنید.

آی‌او‌اس+

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

برای نصب و مدیریت وابستگی‌های Firebase از Swift Package Manager استفاده کنید.

  1. در Xcode، با باز کردن پروژه برنامه خود، به File > Add Packages بروید.
  2. وقتی از شما خواسته شد، مخزن SDK پلتفرم‌های اپل فایربیس را اضافه کنید:
  3.   https://github.com/firebase/firebase-ios-sdk.git
  4. کتابخانه Cloud Functions انتخاب کنید.
  5. پرچم -ObjC را به بخش Other Linker Flags در تنظیمات ساخت هدف خود اضافه کنید.
  6. پس از اتمام، Xcode به طور خودکار شروع به حل و دانلود وابستگی‌های شما در پس‌زمینه می‌کند.

Web

  1. برای افزودن Firebase به برنامه وب خود، دستورالعمل‌ها را دنبال کنید. حتماً دستور زیر را از ترمینال خود اجرا کنید:
    npm install firebase@12.4.0 --save
  2. به صورت دستی به هر دو هسته Firebase و 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);

Web

  1. برای افزودن Firebase به برنامه وب خود، دستورالعمل‌ها را دنبال کنید.
  2. کتابخانه‌های کلاینت Firebase core و Cloud Functions را به برنامه خود اضافه کنید:
    <script src="https://www.gstatic.com/firebasejs/8.10.1/firebase.js"></script>
    <script src="https://www.gstatic.com/firebasejs/8.10.1/firebase-functions.js"></script>

SDK Cloud Functions SDK) نیز به عنوان یک بسته npm در دسترس است.

  1. دستور زیر را از ترمینال خود اجرا کنید:
    npm install firebase@8.10.1 --save
  2. به صورت دستی به هر دو هسته Firebase و Cloud Functions نیاز دارید:
    const firebase = require("firebase");
    // Required for side-effects
    require("firebase/functions");

Kotlin

  1. برای افزودن Firebase به برنامه اندروید خود، دستورالعمل‌ها را دنبال کنید.

  2. در فایل Gradle ماژول (سطح برنامه) خود (معمولاً <project>/<app-module>/build.gradle.kts یا <project>/<app-module>/build.gradle )، وابستگی مربوط به کتابخانه Cloud Functions برای اندروید را اضافه کنید. توصیه می‌کنیم برای کنترل نسخه‌بندی کتابخانه Firebase Android BoM استفاده کنید.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:34.4.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 استفاده خواهد کرد.

    (جایگزین) اضافه کردن وابستگی‌های کتابخانه Firebase بدون استفاده از BoM

    اگر تصمیم به استفاده از Firebase BoM ندارید، باید هر نسخه از کتابخانه Firebase را در خط وابستگی آن مشخص کنید.

    توجه داشته باشید که اگر از چندین کتابخانه Firebase در برنامه خود استفاده می‌کنید، اکیداً توصیه می‌کنیم از 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:22.0.1")
    }

Java

  1. برای افزودن Firebase به برنامه اندروید خود، دستورالعمل‌ها را دنبال کنید.

  2. در فایل Gradle ماژول (سطح برنامه) خود (معمولاً <project>/<app-module>/build.gradle.kts یا <project>/<app-module>/build.gradle )، وابستگی مربوط به کتابخانه Cloud Functions برای اندروید را اضافه کنید. توصیه می‌کنیم برای کنترل نسخه‌بندی کتابخانه Firebase Android BoM استفاده کنید.

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:34.4.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 استفاده خواهد کرد.

    (جایگزین) اضافه کردن وابستگی‌های کتابخانه Firebase بدون استفاده از BoM

    اگر تصمیم به استفاده از Firebase BoM ندارید، باید هر نسخه از کتابخانه Firebase را در خط وابستگی آن مشخص کنید.

    توجه داشته باشید که اگر از چندین کتابخانه Firebase در برنامه خود استفاده می‌کنید، اکیداً توصیه می‌کنیم از 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:22.0.1")
    }

Dart

  1. برای افزودن Firebase به برنامه Flutter خود، دستورالعمل‌ها را دنبال کنید.

  2. از ریشه پروژه Flutter خود، دستور زیر را برای نصب افزونه اجرا کنید:

    flutter pub add cloud_functions
    
  3. پس از اتمام، برنامه Flutter خود را بازسازی کنید:

    flutter run
    
  4. پس از نصب، می‌توانید با وارد کردن افزونه cloud_functions در کد Dart خود، به آن دسترسی پیدا کنید:

    import 'package:cloud_functions/cloud_functions.dart';
    

سی++

برای C++ با اندروید :

  1. برای اضافه کردن Firebase به پروژه ++C خود، دستورالعمل‌ها را دنبال کنید.
  2. کتابخانه firebase_functions به فایل CMakeLists.txt خود اضافه کنید.

برای ++C با پلتفرم‌های اپل :

  1. برای اضافه کردن Firebase به پروژه ++C خود، دستورالعمل‌ها را دنبال کنید.
  2. پاد Cloud Functions به Podfile خود اضافه کنید:
    pod 'Firebase/Functions'
  3. فایل را ذخیره کنید، سپس اجرا کنید:
    pod install
  4. چارچوب‌های هسته فایربیس و Cloud Functions را از کیت توسعه نرم‌افزاری C++ Firebase به پروژه Xcode خود اضافه کنید.
    • firebase.framework
    • firebase_functions.framework

وحدت

  1. برای اضافه کردن Firebase به پروژه Unity خود، دستورالعمل‌ها را دنبال کنید.
  2. بسته‌ی FirebaseFunctions.unitypackage از Firebase Unity SDK به پروژه‌ی Unity خود اضافه کنید.

مقداردهی اولیه SDK کلاینت

مقداردهی اولیه یک نمونه از Cloud Functions :

سویفت

lazy var functions = Functions.functions()

هدف-سی

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

Web

firebase.initializeApp({
  apiKey: '### FIREBASE API KEY ###',
  authDomain: '### FIREBASE AUTH DOMAIN ###',
  projectId: '### CLOUD FUNCTIONS PROJECT ID ###'
  databaseURL: 'https://### YOUR DATABASE NAME ###.firebaseio.com',
});

// Initialize Cloud Functions through Firebase
var functions = firebase.functions();

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

Java

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

Dart

final functions = FirebaseFunctions.instance;

سی++

firebase::functions::Functions* functions;
// ...
functions = firebase::functions::Functions::GetInstance(app);

وحدت

functions = Firebase.Functions.DefaultInstance;

تابع را فراخوانی کنید

سویفت

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

هدف-سی

[[_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;
  });

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;
  });

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

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;
                }
            });
}

Dart

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

سی++

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);
}

وحدت

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;
  });
}

مدیریت خطاها در کلاینت

اگر سرور خطایی ارسال کند یا اگر promise حاصل رد شود، کلاینت خطایی دریافت می‌کند.

اگر خطایی که توسط تابع برگردانده می‌شود از نوع function.https.HttpsError باشد، آنگاه کلاینت code خطا، message و details را از خطای سرور دریافت می‌کند. در غیر این صورت، خطا شامل پیام INTERNAL و کد INTERNAL است. برای نحوه مدیریت خطاها در تابع قابل فراخوانی خود، به راهنمایی مراجعه کنید.

سویفت

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 (error) {
  if ([error.domain isEqual:@"com.firebase.functions"]) {
    FIRFunctionsErrorCode code = error.code;
    NSString *message = error.localizedDescription;
    NSObject *details = error.userInfo[@"details"];
  }
  // ...
}

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;
    // ...
  });

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;
    // ...
  });

Kotlin

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

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();
        }
      }
    }
  });

Dart

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

سی++

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);
  // ...

وحدت

 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 فعال کنید تا مطمئن شوید که فقط برنامه‌های شما می‌توانند به نقاط پایانی تابع قابل فراخوانی شما دسترسی داشته باشند.