از APIهای FCM قدیمی به HTTP v1 مهاجرت کنید

برنامه‌هایی که از APIهای قدیمی FCM برای HTTP و XMPP استفاده می‌کنند باید در اولین فرصت به API HTTP v1 منتقل شوند. ارسال پیام‌ها (از جمله پیام‌های بالادست) با آن APIها در 20 ژوئن 2023 منسوخ شد و خاموش شدن در 22 ژوئیه 2024 آغاز می‌شود .

درباره ویژگی های خاصی که تحت تأثیر قرار می گیرند بیشتر بیاموزید.

علاوه بر پشتیبانی مداوم و ویژگی‌های جدید، API HTTP v1 دارای مزایای زیر نسبت به APIهای قدیمی است:

• امنیت بهتر از طریق نشانه‌های دسترسی HTTP v1 API از نشانه‌های دسترسی کوتاه مدت مطابق با مدل امنیتی OAuth2 استفاده می‌کند. در صورتی که یک توکن دسترسی عمومی شود، فقط یک ساعت یا بیشتر قبل از منقضی شدن می‌توان از آن به طور مخرب استفاده کرد. توکن‌های Refresh به اندازه کلیدهای امنیتی مورد استفاده در API قدیمی منتقل نمی‌شوند، بنابراین احتمال ضبط شدن آنها بسیار کمتر است.

• سفارشی‌سازی کارآمدتر پیام‌ها در سراسر پلتفرم‌ها برای بدنه پیام، HTTP v1 API دارای کلیدهای مشترکی است که به همه نمونه‌های هدف می‌روند، به‌علاوه کلیدهای مخصوص پلتفرم که به شما امکان می‌دهند پیام را در همه پلتفرم‌ها سفارشی کنید. این به شما اجازه می‌دهد تا "نسخه‌هایی" ایجاد کنید که در یک پیام، بارهای کمی متفاوت را به پلتفرم‌های مشتری مختلف ارسال می‌کنند.

• برای نسخه‌های جدید پلت‌فرم کلاینت قابل توسعه‌تر و مقاوم‌تر است. HTTP v1 API به طور کامل از گزینه‌های پیام‌رسانی موجود در پلتفرم‌های اپل، اندروید و وب پشتیبانی می‌کند. از آنجایی که هر پلتفرم بلوک تعریف شده خود را در بار JSON دارد، FCM می‌تواند API را به نسخه‌های جدید و پلتفرم‌های جدید در صورت نیاز گسترش دهد.

نقطه پایانی سرور را به روز کنید

نشانی وب نقطه پایانی برای HTTP v1 API با نقطه پایانی قدیمی به این صورت متفاوت است:

• این نسخه نسخه شده است، با /v1 در مسیر.
• مسیر شامل شناسه پروژه پروژه Firebase برای برنامه شما با قالب /projects/myproject-ID/ است. این شناسه در تب تنظیمات پروژه عمومی کنسول Firebase موجود است.
• به صراحت روش send را به صورت :send مشخص می کند.

برای به‌روزرسانی نقطه پایانی سرور برای HTTP v1، این عناصر را به نقطه پایانی در هدر درخواست‌های ارسال خود اضافه کنید.

درخواست HTTP قبل

POST https://fcm.googleapis.com/fcm/send

درخواست های XMPP قبلا

پیام‌های قدیمی XMPP از طریق یک اتصال به نقطه پایانی زیر ارسال می‌شوند:

fcm-xmpp.googleapis.com:5235

بعد از

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

مجوز درخواست های ارسال را به روز کنید

به جای رشته کلید سرور مورد استفاده در درخواست‌های قدیمی، درخواست‌های ارسال HTTP v1 به نشانه دسترسی OAuth 2.0 نیاز دارند. اگر از Admin SDK برای ارسال پیام استفاده می‌کنید، کتابخانه رمز را برای شما مدیریت می‌کند. اگر از پروتکل eeef raw استفاده می‌کنید، توکن را همانطور که در این بخش توضیح داده شده است دریافت کنید و آن را به عنوان Authorization: Bearer <valid Oauth 2.0 token> به سربرگ اضافه کنید.

قبل از

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

بعد از

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

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

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

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

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

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

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

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

 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

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> اضافه کنید:

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

حجم بار درخواست های ارسال را به روز کنید

FCM HTTP v1 یک تغییر قابل توجه در ساختار بار پیام JSON ایجاد می کند. در درجه اول، این تغییرات تضمین می کند که پیام ها هنگام دریافت در پلتفرم های مختلف مشتری به درستی مدیریت می شوند. علاوه بر این، تغییرات به شما انعطاف‌پذیری بیشتری برای سفارشی‌سازی یا «لغو» فیلدهای پیام در هر پلتفرم می‌دهد.

علاوه بر بررسی مثال‌های موجود در این بخش، سفارشی کردن یک پیام در پلتفرم‌ها را ببینید و مرجع API را مرور کنید تا با HTTP v1 آشنا شوید.

مثال: پیام اعلان ساده

در اینجا مقایسه یک بار اعلان بسیار ساده است - که فقط شامل title ، body و فیلدهای data است - که تفاوت های اساسی در بارهای قدیمی و HTTP v1 را نشان می دهد.

قبل از

{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available."
  },
  "data": {
    "story_id": "story_12345"
  }
}

بعد از

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    }
  }
}

مثال: داده‌های JSON تو در تو

برخلاف API پیام‌رسان قدیمی، API HTTP v1 از مقادیر JSON تودرتو در فیلد data پشتیبانی نمی‌کند. تبدیل از JSON به رشته مورد نیاز است.

قبل از

{
  ...
  "data": {
    "keysandvalues": {"key1": "value1", "key2": 123}
  }
}

بعد از

{
  "message": {
   ...
    "data": {
      "keysandvalues": "{\"key1\": \"value1\", \"key2\": 123}"
    }
  }
}

مثال: هدف قرار دادن چندین پلتفرم

برای فعال کردن هدف‌یابی چند پلتفرمی، API قدیمی در backend لغو اعمال کرد. در مقابل، HTTP v1 بلوک‌های کلیدی خاص پلتفرم را ارائه می‌کند که هر گونه تفاوت بین پلتفرم‌ها را برای توسعه‌دهنده واضح و قابل مشاهده می‌سازد. این به شما امکان می دهد تا همیشه با یک درخواست، چندین پلتفرم را هدف قرار دهید، همانطور که در نمونه زیر نشان داده شده است.

قبل از

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

بعد از

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

مثال: سفارشی کردن با لغو پلت فرم

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

قبل از

// Android
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "Check out the Top Story.",
    "click_action": "TOP_STORY_ACTIVITY"
  },
  "data": {
    "story_id": "story_12345"
  }
}
// Apple
{
  "to": "/topics/news",
  "notification": {
    "title": "Breaking News",
    "body": "New news story available.",
    "click_action": "HANDLE_BREAKING_NEWS"
  },
  "data": {
    "story_id": "story_12345"
  }
}

بعد از

{
  "message": {
    "topic": "news",
    "notification": {
      "title": "Breaking News",
      "body": "New news story available."
    },
    "data": {
      "story_id": "story_12345"
    },
    "android": {
      "notification": {
        "click_action": "TOP_STORY_ACTIVITY",
        "body": "Check out the Top Story"
      }
    },
    "apns": {
      "payload": {
        "aps": {
          "category" : "NEW_MESSAGE_CATEGORY"
        }
      }
    }
  }
}

مثال: هدف قرار دادن دستگاه های خاص

برای هدف قرار دادن دستگاه‌های خاص با HTTP v1 API، رمز ثبت فعلی دستگاه را به جای کلید to در کلید token ارائه کنید.

قبل از

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

بعد از

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

برای نمونه ها و اطلاعات بیشتر در مورد FCM HTTP v1 API، به موارد زیر مراجعه کنید:

• راهنمایی در مورد نحوه ساخت سرور برنامه برای ارسال درخواست با HTTP v1 API. همه قطعه‌های «REST» از API v1 استفاده می‌کنند، مگر اینکه به طور خاص ذکر شده باشد.

• وبلاگ Firebase