با استفاده از 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 اجرا می شود (از جمله Cloud Functions for Firebase )، از اعتبارنامه پیش فرض برنامه (ADC) استفاده کنید. ADC از حساب سرویس پیش‌فرض موجود شما برای دریافت اعتبار برای تأیید درخواست‌ها استفاده می‌کند و ADC آزمایش محلی انعطاف‌پذیر را از طریق متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS فعال می‌کند. برای اتوماسیون کامل جریان مجوز، از ADC همراه با کتابخانه های سرور Admin 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)
}
init.go

سی شارپ 

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

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

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

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

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

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

  2. روی Generate New Private Key کلیک کنید، سپس با کلیک روی Generate Key تأیید کنید.

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

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

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

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

لینوکس یا 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 استفاده کنید، که مجوز را به طور خودکار کنترل می کند، باید رمز دسترسی را برش دهید و آن را برای ارسال درخواست ها اضافه کنید.

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

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

در این مثال، کتابخانه سرویس گیرنده 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
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> اضافه کنید:

node.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. Enable API: مطمئن شوید که Firebase Cloud Messaging API در پروژه فرستنده فعال است.
  2. ایجاد حساب سرویس: در پروژه فرستنده یک حساب سرویس ایجاد کنید.
  3. Grant Permissions: در پروژه هدف، به آدرس ایمیل حساب سرویس، نقش مدیریت API پیام ابری Firebase را در صفحه IAM اعطا کنید. این به حساب سرویس از پروژه دیگر اجازه می دهد تا پیام هایی را به پروژه مورد نظر ارسال کند.
  4. Obtain Token: یک نشانه دسترسی OAuth 2.0 برای حساب سرویس در پروژه فرستنده ایجاد کنید . شما می توانید این کار را با یکی از موارد زیر انجام دهید:
    • دانلود و استفاده از فایل JSON کلید حساب سرویس.
    • یا اگر سرویس شما در Google Cloud اجرا می‌شود، از Workload Identity استفاده کنید.
  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"
    }

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

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

URL درخواست 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"
    }
  }
}

اجرا کنید

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