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

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

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

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

درصورت موفقیت، پاسخ FCM 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

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