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

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

  • نام موضوع
  • وضعیت
  • توکن ثبت دستگاه
  • نام گروه دستگاه (فقط پروتکل)

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

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

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

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

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

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

ارائه اعتبارنامه با استفاده از ADC

اعتبارنامه‌های پیش‌فرض برنامه گوگل (ADC) اعتبارنامه‌های شما را به ترتیب زیر بررسی می‌کند:

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

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

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

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

نود جی اس 

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)
}
init.go

سی شارپ 

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

ارائه مدارک به صورت دستی

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

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

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

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

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

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

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

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

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

لینوکس یا macOS 

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

ویندوز

با پاورشل:

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

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

استفاده از اعتبارنامه‌ها برای ایجاد توکن‌های دسترسی

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

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

گره.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);
    });
  });
}
index.js

در این مثال، کتابخانه کلاینت API گوگل، درخواست را با یک توکن وب JSON یا JWT احراز هویت می‌کند. برای اطلاعات بیشتر، به JSON web tokens مراجعه کنید.

پایتون 

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
messaging.py

جاوا 

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

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

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

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

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

گره.js 

headers: {
  'Authorization': 'Bearer ' + accessToken
}
index.js

پایتون 

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

جاوا 

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;
FirebaseMessagingSnippets.java

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

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

  1. فعال کردن API: اطمینان حاصل کنید که API پیام‌رسان ابری Firebase در پروژه فرستنده فعال شده است.
  2. ایجاد حساب سرویس: یک حساب سرویس در پروژه فرستنده ایجاد کنید.
  3. اعطای مجوزها: در پروژه هدف، در صفحه IAM، به آدرس ایمیل حساب سرویس، نقش مدیر Firebase Cloud Messaging API را اعطا کنید. این کار به حساب سرویس پروژه دیگر اجازه می‌دهد تا به پروژه هدف پیام ارسال کند.
  4. دریافت توکن: یک توکن دسترسی OAuth 2.0 برای حساب سرویس در پروژه فرستنده ایجاد کنید . می‌توانید این کار را به یکی از روش‌های زیر انجام دهید:
    • دانلود و استفاده از فایل JSON کلید حساب سرویس.
    • روش دیگر، استفاده از Workload Identity در صورتی است که سرویس شما روی Google Cloud اجرا می‌شود.
  5. ارسال درخواست: از توکن دسترسی دریافت شده در هدر Authorization درخواست ارسالی خود استفاده کنید. درخواست باید به نقطه پایانی HTTP v1 برای پروژه هدف ارسال شود: 
        POST https://fcm.googleapis.com/v1/TARGET_PROJECT_ID/messages:send

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

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

استراحت 

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

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

آدرس درخواست HTTP

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

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://cat.10515.net/1.jpg"
    }
  }
}

اجرا کنید

برای امتحان کردن نمونه در API Explorer، روی Run کلیک کنید.