ارسال پیام بااستفاده از FCM HTTP v1 API

بااستفاده از FCM HTTP v1 API، می‌توانید درخواست‌های پیام را بسازید و آن‌ها را به این نوع هدف‌ها ارسال کنید:

  • نام موضوع
  • وضعیت
  • کد ثبت دستگاه
  • نام گروه دستگاه (منسوخ‌شده، در ۲۹ سپتامبر ۲۰۲۷ برداشته خواهد شد)

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

مجاز کردن درخواست‌های ارسال HTTP v1

بسته به جزئیات محیط سرور شما، از ترکیبی از این استراتژی‌ها برای مجوز دادن به درخواست‌های سرور به سرویس‌های Firebase استفاده کنید:

  • اعتبارنامه‌های پیش‌فرض برنامه Google‏ (ADC)
  • فایل JSON حساب سرویس
  • کد دسترسی OAuth 2.0 کوتاه‌مدت که از حساب سرویس مشتق شده است

اگر برنامه‌تان در Compute Engine، Google Kubernetes Engine، App Engine، یا Cloud Functions (ازجمله Cloud Functions for Firebase) اجرا می‌شود، از «اعتبارنامه‌های پیش‌فرض برنامه» (ADC) استفاده کنید. ADC از حساب سرویس پیش‌فرض موجود شما برای دریافت اطلاعات کاربری جهت صدور مجوز درخواست‌ها استفاده می‌کند و ADC آزمایش محلی انعطاف‌پذیر را ازطریق متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS فعال می‌کند. برای خودکارسازی کامل جریان مجوزدهی، از ADC به‌همراه کتابخانه‌های سرور «سرپرست SDK» استفاده کنید.

اگر برنامه‌تان در محیط سرور غیرGoogle اجرا می‌شود، باید فایل JSON حساب سرویس را از پروژه Firebase خود بارگیری کنید. تا زمانی که به سیستم فایلی که حاوی فایل کلید خصوصی است دسترسی داشته باشید، می‌توانید از متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS برای مجاز کردن درخواست‌ها با این اطلاعات کاربری که به‌صورت دستی دریافت شده‌اند استفاده کنید. اگر چنین دسترسی‌ای به فایل ندارید، باید در کدتان به فایل حساب سرویس ارجاع دهید— که به‌دلیل خطر افشای اطلاعات اعتباری‌تان باید با دقت بسیار انجام شود.

ارائه اطلاعات کاربری بااستفاده از ADC

«اعتبارنامه‌های پیش‌فرض برنامه Google»‏ (ADC) اعتبارنامه‌های شما را به‌ترتیب زیر بررسی می‌کند:

  1. ADC بررسی می‌کند که آیا متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS تنظیم شده است یا نه. اگر متغیر تنظیم شده باشد، ADC از فایل حساب سرویسی که متغیر به آن اشاره می‌کند استفاده می‌کند.

  2. اگر متغیر محیطی تنظیم نشده باشد، ADC از حساب سرویس پیش‌فرضی استفاده می‌کند که Compute Engine،‏ Google Kubernetes Engine،‏ App Engine، و Cloud Functions برای برنامه‌هایی که در آن سرویس‌ها اجرا می‌شوند ارائه می‌دهند.

  3. اگر ADC نتواند از هیچ‌کدام از اعتبارنامه‌های بالا استفاده کند، سیستم خطا می‌دهد.

نمونه کد Admin SDK زیر این استراتژی را نشان می‌دهد. این نمونه به‌طور صریح اطلاعات اعتباری برنامه را مشخص نمی‌کند. بااین‌حال، ADC می‌تواند اعتبارنامه‌ها را به‌طور ضمنی پیدا کند، به‌شرطی که متغیر محیط تنظیم شده باشد، یا برنامه در Compute Engine، Google Kubernetes Engine، App Engine، یا Cloud Functions درحال اجرا باشد.

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

جاوا

FirebaseOptions options = FirebaseOptions.builder()
    .setCredentials(GoogleCredentials.getApplicationDefault())
    .setDatabaseUrl("https://<DATABASE_NAME>.firebaseio.com/")
    .build();

FirebaseApp.initializeApp(options);

پایتون

default_app = firebase_admin.initialize_app()

رفتن

app, err := firebase.NewApp(context.Background(), nil)
if err != nil {
	log.Fatalf("error initializing app: %v\n", err)
}

سی شارپ

FirebaseApp.Create(new AppOptions()
{
    Credential = GoogleCredential.GetApplicationDefault(),
});

ارائه اعتبارنامه‌ها به‌صورت دستی

پروژه‌های Firebase از حساب‌های سرویس Google پشتیبانی می‌کنند که می‌توانید از آن‌ها برای فراخوانی میاناهای برنامه‌سازی کاربردی سرور Firebase از سرور برنامه یا محیط مورداعتماد استفاده کنید. اگر کد را به‌صورت محلی توسعه می‌دهید یا برنامه‌تان را در محل مستقر می‌کنید، می‌توانید از اطلاعات اعتباری به‌دست‌آمده بااستفاده از این حساب خدماتی برای مجاز کردن درخواست‌های سرور استفاده کنید.

می‌توانید همه حساب‌های سرویس پروژه Firebase خود را در تنظیمات > حساب‌های سرویس برگه مشاهده کنید.

برای اصالت‌سنجی حساب خدمات و صدور مجوز برای آن جهت دسترسی به سرویس‌های Firebase، باید فایل کلید خصوصی را در قالب JSON تولید کنید.

برای ایجاد فایل کلید خصوصی برای حساب سرویس خود:

  1. در کنسول Firebase، به تنظیمات > زبانه حساب‌های سرویس بروید.

  2. روی تولید کلید خصوصی جدید کلیک کنید، سپس با کلیک کردن روی تولید کلید تأیید کنید.

  3. فایل JSON حاوی کلید را به‌طور ایمن ذخیره کنید.

هنگام صدور مجوز ازطریق حساب سرویس، دو گزینه برای ارائه اعتبارنامه به برنامه‌تان دارید. می‌توانید متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید یا می‌توانید مسیر کلید حساب سرویس را به‌طور صریح در کد ارسال کنید. گزینه اول ایمن‌تر است و اکیداً توصیه می‌شود.

برای تنظیم متغیر محیطی:

متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل JSON که حاوی کلید حساب سرویس شما است تنظیم کنید. این متغیر فقط برای جلسه پوسته فعلی شما اعمال می‌شود، بنابراین اگر جلسه جدیدی باز کردید، متغیر را دوباره تنظیم کنید.

Linux یا macOS

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

پنجره

با PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

پس‌از تکمیل مراحل بالا، «اعتبارنامه‌های پیش‌فرض برنامه» (ADC) می‌تواند به‌طور ضمنی اعتبارنامه‌های شما را تعیین کند و به شما اجازه دهد هنگام آزمایش یا اجرا در محیط‌های غیرGoogle، از اعتبارنامه‌های حساب سرویس استفاده کنید.

استفاده از اطلاعات کاربری برای ایجاد کد دسترسی

مگر اینکه از Firebase Admin SDK استفاده کنید که مجوزدهی را به‌طور خودکار انجام می‌دهد، باید کد دسترسی را ایجاد کنید و آن را به درخواست‌های ارسال اضافه کنید.

از اطلاعات اعتباری Firebase خود به‌همراه کتابخانه Google Auth برای زبان موردنظرتان استفاده کنید تا کد دسترسی OAuth 2.0 کوتاه‌مدت را بازیابی کنید:

node.js

 function getAccessToken() {
  return new Promise(function(resolve, reject) {
    const key = require('../placeholders/service-account.json');
    const jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

در این مثال، کتابخانه کارخواه Google API درخواست را با یک شناسه وب JSON یا JWT اصالت‌سنجی می‌کند. برای اطلاعات بیشتر، نشانه‌های وب JSON را ببینید.

پایتون

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = service_account.Credentials.from_service_account_file(
    'service-account.json', scopes=SCOPES)
  request = google.auth.transport.requests.Request()
  credentials.refresh(request)
  return credentials.token

جاوا

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refresh();
  return googleCredentials.getAccessToken().getTokenValue();
}

پس‌از منقضی شدن کد دسترسی، روش بازآوری کد به‌طور خودکار فراخوانی می‌شود تا کد دسترسی به‌روزشده بازیابی شود.

برای مجاز کردن دسترسی به FCM، دامنه https://www.googleapis.com/auth/firebase.messaging را درخواست کنید.

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

توکن را به‌عنوان مقدار سرصفحه Authorization در قالب Authorization: Bearer <access_token> اضافه کنید:

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

پایتون

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}

جاوا

URL url = new URL(BASE_URL + FCM_SEND_ENDPOINT);
HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();
httpURLConnection.setRequestProperty("Authorization", "Bearer " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;

مجاز کردن حساب سرویس از پروژه‌ای دیگر

می‌توانید برای یک پروژه، «پروژه هدف»، پیام ارسال کنید، درحالی‌که از یک توکن OAuth 2.0 تولیدشده از یک حساب سرویس در پروژه دیگری ، «پروژه فرستنده»، استفاده می‌کنید. این کار به شما امکان می‌دهد مدیریت حساب سرویس را در یک پروژه متمرکز کنید و درعین‌حال ازطرف دیگران پیام ارسال کنید. برای آشنایی با نحوه انجام این کار، مراحل زیر را دنبال کنید:

  1. در پروژه فرستنده، مطمئن شوید Firebase Cloud Messaging API فعال باشد. با رفتن به تنظیمات > موارد کلی در کنسول Firebase، بررسی کنید که فعال شده باشد. سپس، روی زبانه پیام‌رسانی ابری کلیک کنید.

  2. در پروژه فرستنده، حساب خدمات ایجاد کنید.

  3. در پروژه هدف، نقش سرپرست Firebase Cloud Messaging API را به نشانی ایمیل حساب سرویس اختصاص دهید. این کار را در صفحه IAM و سرپرست > IAM در کنسول Google Cloud انجام می‌دهید. این نقش به حساب سرویس از پروژه فرستنده اجازه می‌دهد پیام‌ها را به پروژه هدف ارسال کند.

  4. یک کد دسترسی OAuth 2.0 برای حساب سرویس در پروژه فرستنده ایجاد کنید. می‌توانید این کار را بااستفاده از یکی از گزینه‌های زیر انجام دهید:

    • بارگیری و استفاده از فایل JSON کلید حساب سرویس.
    • استفاده از Workload Identity اگر سرویس شما در Google Cloud اجرا می‌شود.

  5. از کد دسترسی به‌دست‌آمده در سرصفحه Authorization درخواست ارسال خود استفاده کنید. درخواست باید به نقطه پایان HTTP v1 برای پروژه هدف ارسال شود:

      POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

ارسال پیام به دستگاه‌های خاص

برای ارسال به یک دستگاه خاص، کد ثبت دستگاه را همان‌طور که نشان داده شده است ارسال کنید.

REST (انتقال بازنمودی وضعیت)

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

{
   "message":{
      "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
      "notification":{
        "body":"This is an FCM notification message!",
        "title":"FCM Message"
      }
   }
}

فرمان cURL:

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA" -H "Content-Type: application/json" -d '{
"message":{
   "notification":{
     "title":"FCM Message",
     "body":"This is an FCM Message"
   },
   "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
}}' https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send

درصورت موفقیت، پاسخ HTTP v1 API یک شیء JSON حاوی شناسه پیام است:

    {
      "name":"projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c96"
    }

ارسال کردن پیام اعلان آزمایشی بااستفاده از FCM HTTP v1 API

این بخش نحوه ارسال پیام اعلان آزمایشی بااستفاده از FCM HTTP v1 API را شرح می‌دهد.

نشانی وب درخواست اچ‌تی‌تی‌پی

درخواست شامل یک HTTP POST به هدف مشخص‌شده (یک نشانه ثبت، موضوع یا شرط) در نشانی وب زیر است:

POST https://fcm.googleapis.com/v1/projectId/messages:send

نمونه JSON درخواست اچ‌تی‌تی‌پی کامل

در اینجا نمونه کاملی آورده شده است که نحوه پست کردن اعلان در درخواست HTTP POST را نشان می‌دهد:

{
  "message": {
    "token": REGISTRATION_TOKEN,
    "notification": {
      "title": "FCM API test",
      "body": "This is the body of the notification.",
      "image": "https://firebase.google.com/static/images/products/cloud-messaging/cloud-messaging-hero_1x.png"
    }
  }
}

اجرا

روی اجرا کلیک کنید تا نمونه را در API Explorer امتحان کنید.