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

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

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

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

صدور مجوز برای ارسال درخواست‌های HTTP نسخه ۱

بسته به جزئیات محیط سرور، از ترکیبی از این استراتژی‌ها برای مجاز کردن درخواست‌های سرور به سرویس‌های 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 به‌همراه کتابخانه‌های سرور «کیت توسعه نرم‌افزار سرپرست» استفاده کنید.

اگر برنامه شما در محیط سرور غیر 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 نتواند از هیچ‌یک از اطلاعات اعتباری بالا استفاده کند، سیستم خطا می‌دهد.

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

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. در پروژه مقصد، نقش سرپرست API پیام‌رسانی ابریِ Firebase را به نشانی ایمیل حساب سرویس اختصاص دهید. این کار را در صفحه IAM و سرپرست > IAM کنسول Google Cloud انجام می‌دهید. این نقش به حساب سرویس از پروژه فرستنده اجازه می‌دهد به پروژه مقصد پیام ارسال کند.

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

    • درحال بارگیری و استفاده از فایل JSON کلید حساب سرویس.
    • استفاده از هویت بار کاری اگر سرویس شما در 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

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

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

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

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

نشانی وب درخواست HTTP

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

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

نمونه JSON درخواست کامل HTTP

در اینجا یک مثال کامل نشان داده شده است که چگونه یک اعلان را در یک درخواست 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، روی اجرا کردن کلیک کنید.