این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

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

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

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

امنیت بهتر از طریق توکن‌های دسترسی API HTTP نسخه ۱ از توکن‌های دسترسی کوتاه‌مدت طبق مدل امنیتی OAuth2 استفاده می‌کند. در صورتی که یک توکن دسترسی عمومی شود، فقط می‌توان آن را به مدت یک ساعت یا بیشتر قبل از انقضا به صورت مخرب مورد استفاده قرار داد. توکن‌های به‌روزرسانی به اندازه کلیدهای امنیتی مورد استفاده در API قدیمی ارسال نمی‌شوند، بنابراین احتمال به دست گرفتن آنها بسیار کمتر است.
سفارشی‌سازی کارآمدتر پیام‌ها در پلتفرم‌های مختلف برای بدنه پیام، HTTP v1 API دارای کلیدهای مشترکی است که به همه نمونه‌های هدف متصل می‌شوند، به علاوه کلیدهای مخصوص پلتفرم که به شما امکان می‌دهند پیام را در پلتفرم‌های مختلف سفارشی کنید. این به شما امکان می‌دهد "overrides" ایجاد کنید که بارهای کمی متفاوت را در یک پیام واحد به پلتفرم‌های مختلف کلاینت ارسال می‌کنند.
قابلیت توسعه‌پذیری بیشتر و سازگاری بیشتر با آینده برای نسخه‌های جدید پلتفرم‌های کلاینت API HTTP v1 به طور کامل از گزینه‌های پیام‌رسانی موجود در پلتفرم‌های اپل، اندروید و وب پشتیبانی می‌کند. از آنجایی که هر پلتفرم بلوک تعریف‌شده‌ی خود را در JSON payload دارد، FCM می‌تواند API را در صورت نیاز به نسخه‌ها و پلتفرم‌های جدید گسترش دهد.

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

آدرس اینترنتی (URL) نقطه پایانی برای HTTP v1 API با نقطه پایانی قدیمی از این جهات متفاوت است:

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

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

درخواست‌های 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 نسخه ۱ به یک توکن دسترسی OAuth 2.0 نیاز دارند. اگر از Admin SDK برای ارسال پیام‌ها استفاده می‌کنید، کتابخانه توکن را برای شما مدیریت می‌کند. اگر از پروتکل خام استفاده می‌کنید، توکن را همانطور که در این بخش توضیح داده شده است، دریافت کنید و آن را به هدر با عنوان Authorization: Bearer <valid Oauth 2.0 token> اضافه کنید.

قبل از

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

بعد از

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

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

ADC بررسی می‌کند که آیا متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS تنظیم شده است یا خیر. اگر متغیر تنظیم شده باشد، ADC از فایل حساب سرویسی که متغیر به آن اشاره می‌کند استفاده می‌کند.
اگر متغیر محیطی تنظیم نشده باشد، ADC از حساب سرویس پیش‌فرضی که Compute Engine ، Google Kubernetes Engine ، App Engine و Cloud Functions برای برنامه‌هایی که روی آن سرویس‌ها اجرا می‌شوند، ارائه می‌دهند، استفاده می‌کند.
اگر 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 ایجاد کنید.

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

در کنسول Firebase ، تنظیمات > حساب‌های سرویس ( Settings > Service Accounts) را باز کنید.
روی «ایجاد کلید خصوصی جدید» کلیک کنید، سپس با کلیک روی «ایجاد کلید» تأیید کنید.
فایل 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 خود به همراه کتابخانه 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.tokenmessaging.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

به‌روزرسانی بار مفید درخواست‌های ارسالی

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

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

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

در اینجا مقایسه‌ای از یک payload اعلان بسیار ساده - که فقط شامل فیلدهای title ، body و data است - ارائه شده است که تفاوت‌های اساسی بین payloadهای قدیمی و 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 نسخه ۱ از مقادیر 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 نسخه ۱ انعطاف‌پذیری لازم برای سفارشی‌سازی پیام‌ها در هر پلتفرم را فراهم می‌کند.

قبل از

// 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"
        }
      }
    }
  }
}

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

برای هدف قرار دادن دستگاه‌های خاص با API HTTP v1، به جای کلید 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 استفاده می‌کنند، مگر اینکه به طور خاص ذکر شده باشد.
وبلاگ فایربیس .

از APIهای FCM قدیمی به HTTP v1 مهاجرت کنید با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

درخواست‌های HTTP قبل از

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

بعد از

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

قبل از

بعد از

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

نود جی اس

جاوا

پایتون

برو

سی شارپ

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

لینوکس یا macOS

ویندوز

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

گره.js

پایتون

جاوا

گره.js

پایتون

جاوا

به‌روزرسانی بار مفید درخواست‌های ارسالی

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

قبل از

بعد از

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

قبل از

بعد از

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

قبل از

بعد از

مثال: سفارشی‌سازی با لغو پلتفرم

قبل از

بعد از

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

قبل از

بعد از

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