درخواستهایی که از سرور برنامه یا محیط مورد اعتماد شما به FCM ارسال میشوند باید مجاز باشند. به این تفاوت های مهم بین API قدیمی HTTP قدیمی و مجوز API HTTP v1 توجه کنید:
- API FCM HTTP v1 درخواستها را با توکن دسترسی کوتاه مدت OAuth 2.0 تأیید میکند. برای برش این نشانه، میتوانید از اعتبارنامه پیشفرض برنامه Google (در محیطهای سرور Google) استفاده کنید و/یا بهطور دستی اعتبار مورد نیاز را از یک فایل کلید خصوصی JSON که برای یک حساب سرویس ایجاد شده است، دریافت کنید. اگر از Firebase Admin SDK برای ارسال پیام استفاده میکنید، کتابخانه توکن را برای شما مدیریت میکند.
- پروتکلهای قدیمی منسوخ فقط میتوانند از کلیدهای API با عمر طولانی که از کنسول Firebase به دست میآیند استفاده کنند.
درخواست های ارسال 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) اعتبار شما را به ترتیب زیر بررسی می کند:
ADC بررسی می کند که آیا متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS تنظیم شده است یا خیر. اگر متغیر تنظیم شده باشد، ADC از فایل حساب سرویس که متغیر به آن اشاره می کند استفاده می کند.
اگر متغیر محیط تنظیم نشده باشد، ADC از حساب سرویس پیشفرض استفاده میکند که Compute Engine ، Google Kubernetes Engine ، App Engine و Cloud Functions برای برنامههایی که روی آن سرویسها اجرا میشوند، ارائه میکنند.
اگر 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)
}
FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.GetApplicationDefault(),
});
مدارک را به صورت دستی ارائه دهید
پروژههای Firebase از حسابهای سرویس Google پشتیبانی میکنند که میتوانید از آنها برای فراخوانی APIهای سرور Firebase از سرور برنامه یا محیط مورد اعتماد خود استفاده کنید. اگر در حال توسعه کد به صورت محلی یا نصب برنامه خود در محل هستید، می توانید از اعتبارنامه های به دست آمده از طریق این حساب سرویس برای تأیید درخواست های سرور استفاده کنید.
برای احراز هویت یک حساب سرویس و اجازه دسترسی به خدمات Firebase، باید یک فایل کلید خصوصی با فرمت JSON ایجاد کنید.
برای ایجاد یک فایل کلید خصوصی برای حساب سرویس خود:
در کنسول Firebase ، تنظیمات > حسابهای سرویس را باز کنید.
روی Generate New Private Key کلیک کنید، سپس با کلیک روی Generate Key تأیید کنید.
فایل JSON حاوی کلید را ایمن ذخیره کنید.
هنگام مجوز دادن از طریق یک حساب سرویس، دو انتخاب برای ارائه اعتبارنامه به برنامه خود دارید. میتوانید متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید، یا میتوانید مسیر کلید حساب سرویس را به صورت واضح در کد ارسال کنید. گزینه اول امن تر است و به شدت توصیه می شود.
برای تنظیم متغیر محیطی:
متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل فایل JSON که حاوی کلید حساب سرویس شما است، تنظیم کنید. این متغیر فقط برای جلسه پوسته فعلی شما اعمال می شود، بنابراین اگر جلسه جدیدی را باز کردید، متغیر را دوباره تنظیم کنید.
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 استفاده کنید.
از اعتبارنامه ها برای برش توکن های دسترسی استفاده کنید
مگر اینکه از Admin SDK استفاده کنید، که مجوز را به طور خودکار مدیریت می کند، باید رمز دسترسی را برش داده و برای ارسال درخواست ها اضافه کنید.
برای بازیابی رمز دسترسی کوتاه مدت 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);
});
});
}
در این مثال، کتابخانه سرویس گیرنده 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>
اضافه کنید:
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;
مجوز ارسال درخواستهای پروتکل قدیمی
با پروتکل قدیمی HTTP، هر درخواست باید حاوی کلید سرور از برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase باشد. برای XMPP، باید از همان کلید سرور برای ایجاد یک اتصال استفاده کنید.
انتقال کلیدهای سرور قدیمی
از مارس 2020، FCM ایجاد کلیدهای سرور قدیمی را متوقف کرد. کلیدهای سرور قدیمی موجود به کار خود ادامه می دهند، اما توصیه می کنیم در عوض از نسخه جدید کلید با برچسب Server key در کنسول Firebase استفاده کنید.
اگر میخواهید یک کلید سرور قدیمی موجود را حذف کنید، میتوانید این کار را در کنسول Google Cloud انجام دهید.
درخواست های HTTP را مجاز کنید
درخواست پیام از دو بخش تشکیل شده است: هدر HTTP و بدنه HTTP. هدر HTTP باید شامل هدرهای زیر باشد:
-
Authorization
: key=YOUR_SERVER_KEY
مطمئن شوید که این کلید سرور است که مقدار آن در برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase موجود است. کلیدهای اندروید، پلتفرم اپل و مرورگر توسط FCM رد می شوند. -
Content-Type
:application/json
برای JSON.application/x-www-form-urlencoded;charset=UTF-8
برای متن ساده.
اگرContent-Type
حذف شده باشد، قالب به صورت متن ساده در نظر گرفته می شود.
به عنوان مثال:
Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA { "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data" : { ... }, }
برای جزئیات کامل در مورد ایجاد درخواست های ارسال، به ساخت درخواست های ارسال مراجعه کنید. مرجع پروتکل HTTP Legacy فهرستی از تمام پارامترهایی که پیام شما می تواند داشته باشد را ارائه می دهد.
بررسی اعتبار کلید سرور
اگر هنگام ارسال پیام ها خطاهای احراز هویت دریافت کردید، اعتبار کلید سرور خود را بررسی کنید. به عنوان مثال، در لینوکس، دستور زیر را اجرا کنید:
api_key=YOUR_SERVER_KEY curl --header "Authorization: key=$api_key" \ --header Content-Type:"application/json" \ https://fcm.googleapis.com/fcm/send \ -d "{\"registration_ids\":[\"ABC\"]}"
اگر کد وضعیت HTTP 401 را دریافت کردید، کلید سرور شما معتبر نیست.
مجوز اتصال XMPP
با XMPP، می توانید یک اتصال دائمی، ناهمزمان و دو طرفه به سرورهای FCM داشته باشید. از این اتصال می توان برای ارسال و دریافت پیام بین سرور و دستگاه های متصل به FCM کاربران استفاده کرد.
می توانید از اکثر کتابخانه های XMPP برای مدیریت یک اتصال طولانی مدت به FCM استفاده کنید. نقطه پایانی XMPP در fcm-xmpp.googleapis.com:5235
اجرا می شود. هنگام آزمایش عملکرد با کاربران غیر تولیدی، در عوض باید به سرور پیش از تولید در fcm-xmpp.googleapis.com:5236
متصل شوید (به درگاه مختلف توجه کنید).
آزمایش منظم در پیش تولید (محیط کوچکتر که در آن آخرین FCM اجرا می شود) برای جداسازی کاربران واقعی از کد آزمایشی مفید است. دستگاههای آزمایشی و کد آزمایشی متصل به fcm-xmpp.googleapis.com:5236
باید از شناسه فرستنده FCM متفاوتی استفاده کنند تا از خطرات ارسال پیامهای آزمایشی به کاربران تولیدی یا ارسال پیامهای بالادستی از ترافیک تولید از طریق اتصالات آزمایشی جلوگیری شود.
اتصال دو الزام مهم دارد:
- شما باید یک اتصال امنیت لایه حمل و نقل (TLS) را راه اندازی کنید. توجه داشته باشید که FCM در حال حاضر از برنامه افزودنی STARTTLS پشتیبانی نمی کند.
- FCM به مکانیزم احراز هویت SASL PLAIN با استفاده از
<your_ FCM _Sender_Id>@fcm.googleapis.com
( شناسه فرستنده FCM ) و کلید سرور به عنوان رمز عبور نیاز دارد. این مقادیر در برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase موجود است.
اگر در هر نقطه اتصال قطع شد، باید فوراً دوباره وصل شوید. پس از قطع ارتباطی که پس از احراز هویت اتفاق می افتد، نیازی به عقب نشینی نیست. برای هر شناسه فرستنده ، FCM اجازه 2500 اتصال را به صورت موازی می دهد.
قطعههای زیر نحوه انجام احراز هویت و مجوز برای اتصال XMPP به FCM را نشان میدهند.
سرور XMPP
سرور XMPP درخواست اتصال به FCM می کند
<stream:stream to="fcm.googleapis.com" version="1.0" xmlns="jabber:client" xmlns:stream="http://etherx.jabber.org/streams">
FCM
FCM اتصال را باز می کند و مکانیزم احراز هویت از جمله روش PLAIN
را درخواست می کند.
<stream:features> <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"> <mechanism>X-OAUTH2</mechanism> <mechanism>X-GOOGLE-TOKEN</mechanism> <mechanism>PLAIN</mechanism> </mechanisms> </stream:features>
سرور XMPP
سرور XMPP باید با استفاده از روش PLAIN
auth پاسخ دهد و کلید سرور را از برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase ارائه کند.
<auth mechanism="PLAIN" xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>
FCM
<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>
سرور XMPP
<stream:stream to="fcm.googleapis.com" version="1.0" xmlns="jabber:client" xmlns:stream="http://etherx.jabber.org/streams">
FCM
<stream:features> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/> <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/> </stream:features>
سرور XMPP
<iq type="set"> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"></bind> </iq>
FCM
<iq type="result"> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"> <jid>SENDER_ID@fcm.googleapis.com/RESOURCE</jid> </bind> </iq>
توجه: FCM هنگام مسیریابی پیام ها از منبع محدود استفاده نمی کند.
برای جزئیات کامل در مورد ایجاد درخواست های ارسال، به ساخت درخواست های ارسال مراجعه کنید. مرجع پروتکل XMPP Legacy فهرستی از تمام پارامترهایی که پیام شما می تواند داشته باشد را ارائه می دهد.
،درخواستهایی که از سرور برنامه یا محیط مورد اعتماد شما به FCM ارسال میشوند باید مجاز باشند. به این تفاوت های مهم بین API قدیمی HTTP قدیمی و مجوز API HTTP v1 توجه کنید:
- API FCM HTTP v1 درخواستها را با توکن دسترسی کوتاه مدت OAuth 2.0 تأیید میکند. برای برش این نشانه، میتوانید از اعتبارنامه پیشفرض برنامه Google (در محیطهای سرور Google) استفاده کنید و/یا بهطور دستی اعتبار مورد نیاز را از یک فایل کلید خصوصی JSON که برای یک حساب سرویس ایجاد شده است، دریافت کنید. اگر از Firebase Admin SDK برای ارسال پیام استفاده میکنید، کتابخانه توکن را برای شما مدیریت میکند.
- پروتکلهای قدیمی منسوخ فقط میتوانند از کلیدهای API با عمر طولانی که از کنسول Firebase به دست میآیند استفاده کنند.
درخواست های ارسال 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) اعتبار شما را به ترتیب زیر بررسی می کند:
ADC بررسی می کند که آیا متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS تنظیم شده است یا خیر. اگر متغیر تنظیم شده باشد، ADC از فایل حساب سرویس که متغیر به آن اشاره می کند استفاده می کند.
اگر متغیر محیط تنظیم نشده باشد، ADC از حساب سرویس پیشفرض استفاده میکند که Compute Engine ، Google Kubernetes Engine ، App Engine و Cloud Functions برای برنامههایی که روی آن سرویسها اجرا میشوند، ارائه میکنند.
اگر 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)
}
FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.GetApplicationDefault(),
});
مدارک را به صورت دستی ارائه دهید
پروژههای Firebase از حسابهای سرویس Google پشتیبانی میکنند که میتوانید از آنها برای فراخوانی APIهای سرور Firebase از سرور برنامه یا محیط مورد اعتماد خود استفاده کنید. اگر در حال توسعه کد به صورت محلی یا نصب برنامه خود در محل هستید، می توانید از اعتبارنامه های به دست آمده از طریق این حساب سرویس برای تأیید درخواست های سرور استفاده کنید.
برای احراز هویت یک حساب سرویس و اجازه دسترسی به خدمات Firebase، باید یک فایل کلید خصوصی با فرمت JSON ایجاد کنید.
برای ایجاد یک فایل کلید خصوصی برای حساب سرویس خود:
در کنسول Firebase ، تنظیمات > حسابهای سرویس را باز کنید.
روی Generate New Private Key کلیک کنید، سپس با کلیک روی Generate Key تأیید کنید.
فایل JSON حاوی کلید را ایمن ذخیره کنید.
هنگام مجوز دادن از طریق یک حساب سرویس، دو انتخاب برای ارائه اعتبارنامه به برنامه خود دارید. میتوانید متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید، یا میتوانید مسیر کلید حساب سرویس را به صورت واضح در کد ارسال کنید. گزینه اول امن تر است و به شدت توصیه می شود.
برای تنظیم متغیر محیطی:
متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل فایل JSON که حاوی کلید حساب سرویس شما است، تنظیم کنید. این متغیر فقط برای جلسه پوسته فعلی شما اعمال می شود، بنابراین اگر جلسه جدیدی را باز کردید، متغیر را دوباره تنظیم کنید.
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 استفاده کنید.
از اعتبارنامه ها برای برش توکن های دسترسی استفاده کنید
مگر اینکه از Admin SDK استفاده کنید، که مجوز را به طور خودکار مدیریت می کند، باید رمز دسترسی را برش داده و برای ارسال درخواست ها اضافه کنید.
برای بازیابی رمز دسترسی کوتاه مدت 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);
});
});
}
در این مثال، کتابخانه سرویس گیرنده 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>
اضافه کنید:
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;
مجوز ارسال درخواست های پروتکل قدیمی
با پروتکل قدیمی HTTP، هر درخواست باید حاوی کلید سرور از برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase باشد. برای XMPP، باید از همان کلید سرور برای ایجاد یک اتصال استفاده کنید.
انتقال کلیدهای سرور قدیمی
از مارس 2020، FCM ایجاد کلیدهای سرور قدیمی را متوقف کرد. کلیدهای سرور قدیمی موجود به کار خود ادامه می دهند، اما توصیه می کنیم در عوض از نسخه جدید کلید با برچسب Server key در کنسول Firebase استفاده کنید.
اگر میخواهید یک کلید سرور قدیمی موجود را حذف کنید، میتوانید این کار را در کنسول Google Cloud انجام دهید.
درخواست های HTTP را مجاز کنید
درخواست پیام از دو بخش تشکیل شده است: هدر HTTP و بدنه HTTP. هدر HTTP باید شامل هدرهای زیر باشد:
-
Authorization
: key=YOUR_SERVER_KEY
مطمئن شوید که این کلید سرور است که مقدار آن در برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase موجود است. کلیدهای اندروید، پلتفرم اپل و مرورگر توسط FCM رد می شوند. -
Content-Type
:application/json
برای JSON.application/x-www-form-urlencoded;charset=UTF-8
برای متن ساده.
اگرContent-Type
حذف شده باشد، قالب به صورت متن ساده در نظر گرفته می شود.
به عنوان مثال:
Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA { "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data" : { ... }, }
برای جزئیات کامل در مورد ایجاد درخواست های ارسال، به ساخت درخواست های ارسال مراجعه کنید. مرجع پروتکل HTTP Legacy فهرستی از تمام پارامترهایی که پیام شما می تواند داشته باشد را ارائه می دهد.
بررسی اعتبار کلید سرور
اگر هنگام ارسال پیام ها خطاهای احراز هویت دریافت کردید، اعتبار کلید سرور خود را بررسی کنید. به عنوان مثال، در لینوکس، دستور زیر را اجرا کنید:
api_key=YOUR_SERVER_KEY curl --header "Authorization: key=$api_key" \ --header Content-Type:"application/json" \ https://fcm.googleapis.com/fcm/send \ -d "{\"registration_ids\":[\"ABC\"]}"
اگر کد وضعیت HTTP 401 را دریافت کردید، کلید سرور شما معتبر نیست.
مجوز اتصال XMPP
با XMPP، می توانید یک اتصال دائمی، ناهمزمان و دو طرفه به سرورهای FCM داشته باشید. از این اتصال می توان برای ارسال و دریافت پیام بین سرور و دستگاه های متصل به FCM کاربران استفاده کرد.
می توانید از اکثر کتابخانه های XMPP برای مدیریت یک اتصال طولانی مدت به FCM استفاده کنید. نقطه پایانی XMPP در fcm-xmpp.googleapis.com:5235
اجرا می شود. هنگام آزمایش عملکرد با کاربران غیر تولیدی، در عوض باید به سرور پیش از تولید در fcm-xmpp.googleapis.com:5236
متصل شوید (به درگاه مختلف توجه کنید).
آزمایش منظم در پیش تولید (محیط کوچکتر که در آن آخرین FCM اجرا می شود) برای جداسازی کاربران واقعی از کد آزمایشی مفید است. دستگاههای آزمایشی و کد آزمایشی متصل به fcm-xmpp.googleapis.com:5236
باید از شناسه فرستنده FCM متفاوتی استفاده کنند تا از خطرات ارسال پیامهای آزمایشی به کاربران تولیدی یا ارسال پیامهای بالادستی از ترافیک تولید از طریق اتصالات آزمایشی جلوگیری شود.
اتصال دو الزام مهم دارد:
- شما باید یک اتصال امنیت لایه حمل و نقل (TLS) را راه اندازی کنید. توجه داشته باشید که FCM در حال حاضر از برنامه افزودنی STARTTLS پشتیبانی نمی کند.
- FCM به مکانیزم احراز هویت SASL PLAIN با استفاده از
<your_ FCM _Sender_Id>@fcm.googleapis.com
( شناسه فرستنده FCM ) و کلید سرور به عنوان رمز عبور نیاز دارد. این مقادیر در برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase موجود است.
اگر در هر نقطه اتصال قطع شد، باید فوراً دوباره وصل شوید. پس از قطع ارتباطی که پس از احراز هویت اتفاق می افتد، نیازی به عقب نشینی نیست. برای هر شناسه فرستنده ، FCM اجازه 2500 اتصال را به صورت موازی می دهد.
قطعههای زیر نحوه انجام احراز هویت و مجوز برای اتصال XMPP به FCM را نشان میدهند.
سرور XMPP
سرور XMPP درخواست اتصال به FCM می کند
<stream:stream to="fcm.googleapis.com" version="1.0" xmlns="jabber:client" xmlns:stream="http://etherx.jabber.org/streams">
FCM
FCM اتصال را باز می کند و مکانیزم احراز هویت از جمله روش PLAIN
را درخواست می کند.
<stream:features> <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"> <mechanism>X-OAUTH2</mechanism> <mechanism>X-GOOGLE-TOKEN</mechanism> <mechanism>PLAIN</mechanism> </mechanisms> </stream:features>
سرور XMPP
سرور XMPP باید با استفاده از روش PLAIN
auth پاسخ دهد و کلید سرور را از برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase ارائه کند.
<auth mechanism="PLAIN" xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>
FCM
<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>
سرور XMPP
<stream:stream to="fcm.googleapis.com" version="1.0" xmlns="jabber:client" xmlns:stream="http://etherx.jabber.org/streams">
FCM
<stream:features> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/> <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/> </stream:features>
سرور XMPP
<iq type="set"> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"></bind> </iq>
FCM
<iq type="result"> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"> <jid>SENDER_ID@fcm.googleapis.com/RESOURCE</jid> </bind> </iq>
توجه: FCM هنگام مسیریابی پیام ها از منبع محدود استفاده نمی کند.
برای جزئیات کامل در مورد ایجاد درخواست های ارسال، به ساخت درخواست های ارسال مراجعه کنید. مرجع پروتکل XMPP Legacy فهرستی از تمام پارامترهایی که پیام شما می تواند داشته باشد را ارائه می دهد.
،درخواستهایی که از سرور برنامه یا محیط مورد اعتماد شما به FCM ارسال میشوند باید مجاز باشند. به این تفاوت های مهم بین API قدیمی HTTP قدیمی و مجوز API HTTP v1 توجه کنید:
- API FCM HTTP v1 درخواستها را با توکن دسترسی کوتاه مدت OAuth 2.0 تأیید میکند. برای برش این نشانه، میتوانید از اعتبارنامه پیشفرض برنامه Google (در محیطهای سرور Google) استفاده کنید و/یا بهطور دستی اعتبار مورد نیاز را از یک فایل کلید خصوصی JSON که برای یک حساب سرویس ایجاد شده است، دریافت کنید. اگر از Firebase Admin SDK برای ارسال پیام استفاده میکنید، کتابخانه توکن را برای شما مدیریت میکند.
- پروتکلهای قدیمی منسوخ فقط میتوانند از کلیدهای API با عمر طولانی که از کنسول Firebase به دست میآیند استفاده کنند.
درخواست های ارسال 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) اعتبار شما را به ترتیب زیر بررسی می کند:
ADC بررسی می کند که آیا متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS تنظیم شده است یا خیر. اگر متغیر تنظیم شده باشد، ADC از فایل حساب سرویس که متغیر به آن اشاره می کند استفاده می کند.
اگر متغیر محیط تنظیم نشده باشد، ADC از حساب سرویس پیشفرض استفاده میکند که Compute Engine ، Google Kubernetes Engine ، App Engine و Cloud Functions برای برنامههایی که روی آن سرویسها اجرا میشوند، ارائه میکنند.
اگر 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)
}
FirebaseApp.Create(new AppOptions()
{
Credential = GoogleCredential.GetApplicationDefault(),
});
مدارک را به صورت دستی ارائه دهید
پروژههای Firebase از حسابهای سرویس Google پشتیبانی میکنند که میتوانید از آنها برای فراخوانی APIهای سرور Firebase از سرور برنامه یا محیط مورد اعتماد خود استفاده کنید. اگر در حال توسعه کد به صورت محلی یا نصب برنامه خود در محل هستید، می توانید از اعتبارنامه های به دست آمده از طریق این حساب سرویس برای تأیید درخواست های سرور استفاده کنید.
برای احراز هویت یک حساب سرویس و اجازه دسترسی به خدمات Firebase، باید یک فایل کلید خصوصی با فرمت JSON ایجاد کنید.
برای ایجاد یک فایل کلید خصوصی برای حساب سرویس خود:
در کنسول Firebase ، تنظیمات > حسابهای سرویس را باز کنید.
روی Generate New Private Key کلیک کنید، سپس با کلیک روی Generate Key تأیید کنید.
فایل JSON حاوی کلید را ایمن ذخیره کنید.
هنگام مجوز دادن از طریق یک حساب سرویس، دو انتخاب برای ارائه اعتبارنامه به برنامه خود دارید. میتوانید متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید، یا میتوانید مسیر کلید حساب سرویس را به صورت واضح در کد ارسال کنید. گزینه اول امن تر است و به شدت توصیه می شود.
برای تنظیم متغیر محیطی:
متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS را روی مسیر فایل فایل JSON که حاوی کلید حساب سرویس شما است، تنظیم کنید. این متغیر فقط برای جلسه پوسته فعلی شما اعمال می شود، بنابراین اگر جلسه جدیدی را باز کردید، متغیر را دوباره تنظیم کنید.
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 استفاده کنید.
از اعتبارنامه ها برای برش توکن های دسترسی استفاده کنید
مگر اینکه از Admin SDK استفاده کنید، که مجوز را به طور خودکار مدیریت می کند، باید رمز دسترسی را برش داده و برای ارسال درخواست ها اضافه کنید.
برای بازیابی رمز دسترسی کوتاه مدت 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);
});
});
}
در این مثال، کتابخانه سرویس گیرنده 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>
اضافه کنید:
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;
مجوز ارسال درخواست های پروتکل قدیمی
با پروتکل قدیمی HTTP، هر درخواست باید حاوی کلید سرور از برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase باشد. برای XMPP، باید از همان کلید سرور برای ایجاد یک اتصال استفاده کنید.
انتقال کلیدهای سرور قدیمی
از مارس 2020، FCM ایجاد کلیدهای سرور قدیمی را متوقف کرد. کلیدهای سرور قدیمی موجود به کار خود ادامه می دهند، اما توصیه می کنیم در عوض از نسخه جدید کلید با برچسب Server key در کنسول Firebase استفاده کنید.
اگر میخواهید یک کلید سرور قدیمی موجود را حذف کنید، میتوانید این کار را در کنسول Google Cloud انجام دهید.
درخواست های HTTP را مجاز کنید
درخواست پیام از دو بخش تشکیل شده است: هدر HTTP و بدنه HTTP. هدر HTTP باید شامل هدرهای زیر باشد:
-
Authorization
: key=YOUR_SERVER_KEY
مطمئن شوید که این کلید سرور است که مقدار آن در برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase موجود است. کلیدهای اندروید، پلتفرم اپل و مرورگر توسط FCM رد می شوند. -
Content-Type
:application/json
برای JSON.application/x-www-form-urlencoded;charset=UTF-8
برای متن ساده.
اگرContent-Type
حذف شده باشد، قالب به صورت متن ساده در نظر گرفته می شود.
به عنوان مثال:
Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA { "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data" : { ... }, }
برای جزئیات کامل در مورد ایجاد درخواست های ارسال، به ساخت درخواست های ارسال مراجعه کنید. مرجع پروتکل HTTP Legacy فهرستی از تمام پارامترهایی که پیام شما می تواند داشته باشد را ارائه می دهد.
بررسی اعتبار کلید سرور
اگر هنگام ارسال پیام ها خطاهای احراز هویت دریافت کردید، اعتبار کلید سرور خود را بررسی کنید. به عنوان مثال، در لینوکس، دستور زیر را اجرا کنید:
api_key=YOUR_SERVER_KEY curl --header "Authorization: key=$api_key" \ --header Content-Type:"application/json" \ https://fcm.googleapis.com/fcm/send \ -d "{\"registration_ids\":[\"ABC\"]}"
اگر کد وضعیت HTTP 401 را دریافت کردید، کلید سرور شما معتبر نیست.
مجوز اتصال XMPP
با XMPP، می توانید یک اتصال دائمی، ناهمزمان و دو طرفه به سرورهای FCM داشته باشید. از این اتصال می توان برای ارسال و دریافت پیام بین سرور و دستگاه های متصل به FCM کاربران استفاده کرد.
می توانید از اکثر کتابخانه های XMPP برای مدیریت یک اتصال طولانی مدت به FCM استفاده کنید. نقطه پایانی XMPP در fcm-xmpp.googleapis.com:5235
اجرا می شود. هنگام آزمایش عملکرد با کاربران غیر تولیدی، در عوض باید به سرور پیش از تولید در fcm-xmpp.googleapis.com:5236
متصل شوید (به درگاه مختلف توجه کنید).
آزمایش منظم در پیش تولید (محیط کوچکتر که در آن آخرین FCM اجرا می شود) برای جداسازی کاربران واقعی از کد آزمایشی مفید است. دستگاههای آزمایشی و کد آزمایشی متصل به fcm-xmpp.googleapis.com:5236
باید از شناسه فرستنده FCM متفاوتی استفاده کنند تا از خطرات ارسال پیامهای آزمایشی به کاربران تولیدی یا ارسال پیامهای بالادستی از ترافیک تولید از طریق اتصالات آزمایشی جلوگیری شود.
اتصال دو الزام مهم دارد:
- شما باید یک اتصال امنیت لایه حمل و نقل (TLS) را راه اندازی کنید. توجه داشته باشید که FCM در حال حاضر از برنامه افزودنی STARTTLS پشتیبانی نمی کند.
- FCM به مکانیزم احراز هویت SASL PLAIN با استفاده از
<your_ FCM _Sender_Id>@fcm.googleapis.com
( شناسه فرستنده FCM ) و کلید سرور به عنوان رمز عبور نیاز دارد. این مقادیر در برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase موجود است.
اگر در هر نقطه اتصال قطع شد، باید فوراً دوباره وصل شوید. پس از قطع ارتباطی که پس از احراز هویت اتفاق می افتد، نیازی به عقب نشینی نیست. برای هر شناسه فرستنده ، FCM اجازه 2500 اتصال را به صورت موازی می دهد.
قطعههای زیر نحوه انجام احراز هویت و مجوز برای اتصال XMPP به FCM را نشان میدهند.
سرور XMPP
سرور XMPP درخواست اتصال به FCM می کند
<stream:stream to="fcm.googleapis.com" version="1.0" xmlns="jabber:client" xmlns:stream="http://etherx.jabber.org/streams">
FCM
FCM اتصال را باز می کند و مکانیزم احراز هویت از جمله روش PLAIN
را درخواست می کند.
<stream:features> <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"> <mechanism>X-OAUTH2</mechanism> <mechanism>X-GOOGLE-TOKEN</mechanism> <mechanism>PLAIN</mechanism> </mechanisms> </stream:features>
سرور XMPP
سرور XMPP باید با استفاده از روش PLAIN
auth پاسخ دهد و کلید سرور را از برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase ارائه کند.
<auth mechanism="PLAIN" xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>
FCM
<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>
سرور XMPP
<stream:stream to="fcm.googleapis.com" version="1.0" xmlns="jabber:client" xmlns:stream="http://etherx.jabber.org/streams">
FCM
<stream:features> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/> <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/> </stream:features>
سرور XMPP
<iq type="set"> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"></bind> </iq>
FCM
<iq type="result"> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"> <jid>SENDER_ID@fcm.googleapis.com/RESOURCE</jid> </bind> </iq>
توجه: FCM هنگام مسیریابی پیام ها از منبع محدود استفاده نمی کند.
برای جزئیات کامل در مورد ایجاد درخواست های ارسال، به ساخت درخواست های ارسال مراجعه کنید. مرجع پروتکل XMPP Legacy فهرستی از تمام پارامترهایی که پیام شما می تواند داشته باشد را ارائه می دهد.
،درخواستهایی که از سرور برنامه یا محیط مورد اعتماد شما به FCM ارسال میشوند باید مجاز باشند. به این تفاوت های مهم بین API قدیمی HTTP قدیمی و مجوز API HTTP v1 توجه کنید:
- API FCM HTTP v1 درخواستها را با توکن دسترسی کوتاه مدت OAuth 2.0 تأیید میکند. برای برش این نشانه، میتوانید از اعتبارنامه پیشفرض برنامه Google (در محیطهای سرور Google) استفاده کنید و/یا بهطور دستی اعتبار مورد نیاز را از یک فایل کلید خصوصی JSON که برای یک حساب سرویس ایجاد شده است، دریافت کنید. اگر از Firebase Admin SDK برای ارسال پیام استفاده میکنید، کتابخانه توکن را برای شما مدیریت میکند.
- پروتکلهای قدیمی منسوخ فقط میتوانند از کلیدهای API با عمر طولانی که از کنسول Firebase به دست میآیند استفاده کنند.
مجوز HTTP V1 درخواست ارسال
بسته به جزئیات محیط سرور خود ، از ترکیبی از این استراتژی ها برای مجوز درخواست های سرور به خدمات Firebase استفاده کنید:
- اعتبار پیش فرض برنامه Google (ADC)
- یک پرونده JSON حساب کاربری خدمات
- یک نشانه دسترسی کوتاه مدت OAUTH 2.0 که از یک حساب سرویس گرفته شده است
اگر برنامه شما روی Compute Engine کار می کند ، Google Kubernetes Engine ، App Engine یا توابع ابر (از جمله Cloud Functions for Firebase ) ، از اعتبار پیش فرض برنامه (ADC) استفاده کنید. ADC از حساب خدمات پیش فرض موجود شما برای به دست آوردن اعتبار برای مجوز درخواست استفاده می کند ، و ADC آزمایش محلی انعطاف پذیر را از طریق متغیر محیط GOOGLE_APPLICATION_CREDENTIALS امکان پذیر می کند. برای کاملترین اتوماسیون جریان مجوز ، از ADC به همراه کتابخانه های سرور Admin SDK استفاده کنید.
اگر برنامه شما در یک محیط سرور غیر Google در حال اجرا است ، باید یک فایل JSON حساب کاربری سرویس را از پروژه Firebase خود بارگیری کنید. تا زمانی که به یک سیستم فایل حاوی پرونده کلید خصوصی دسترسی داشته باشید ، می توانید از متغیر محیط GOOGLE_APPLICATION_CREDENTIALS استفاده کنید تا درخواست ها را با این اعتبارنامه به دست آمده دستی مجاز کنید. اگر دسترسی به این پرونده را ندارید ، باید پرونده حساب خدمات را در کد خود ارجاع دهید - که به دلیل خطر افشای اعتبار شما باید با مراقبت های شدید انجام شود.
با استفاده از ADC اعتبارنامه ارائه دهید
اعتبارنامه پیش فرض برنامه Google (ADC) اعتبار شما را به ترتیب زیر بررسی می کند:
ADC بررسی می کند که آیا متغیر محیط GOOGLE_APPLICATION_CREDENTIALS تنظیم شده است یا خیر. اگر متغیر تنظیم شود ، ADC از پرونده حساب سرویس استفاده می کند که متغیر به آن اشاره می کند.
اگر متغیر محیط تنظیم نشده باشد ، ADC از حساب خدمات پیش فرض استفاده می کند که Compute Engine ، Google Kubernetes Engine ، App Engine و توابع ابر برنامه هایی را که در آن سرویس ها اجرا می شوند فراهم می کند.
اگر ADC نتواند از هر یک از اعتبار فوق استفاده کند ، سیستم خطایی را به وجود می آورد.
مثال کد SDK مدیر زیر این استراتژی را نشان می دهد. مثال صریحاً اعتبار برنامه را مشخص نمی کند. با این حال ، ADC قادر است تا زمانی که متغیر محیط تنظیم شود ، اعتبار را به طور ضمنی پیدا کند ، یا تا زمانی که برنامه در Compute Engine ، Google Kubernetes Engine ، App Engine یا توابع ابر کار کند.
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 پشتیبانی می کنند ، که می توانید از آنها برای تماس با API های سرور Firebase از سرور برنامه یا محیط مورد اعتماد استفاده کنید. اگر در حال تهیه کد به صورت محلی یا استقرار برنامه خود در محل هستید ، می توانید از اعتبارنامه های به دست آمده از طریق این حساب سرویس برای مجوز درخواست های سرور استفاده کنید.
برای احراز هویت یک حساب سرویس و اجازه دسترسی به خدمات Firebase، باید یک فایل کلید خصوصی با فرمت JSON ایجاد کنید.
برای تولید یک پرونده کلید خصوصی برای حساب خدمات خود:
در کنسول Firebase ، تنظیمات باز> حساب های خدمات .
بر روی تولید کلید خصوصی جدید کلیک کنید ، سپس با کلیک روی کلید Generate تأیید کنید.
فایل JSON حاوی کلید را ایمن ذخیره کنید.
هنگام مجوز از طریق یک حساب کاربری ، شما دو گزینه برای ارائه اعتبار به درخواست خود دارید. می توانید متغیر محیط GOOGLE_APPLICATION_CREDENTIALS را تنظیم کنید ، یا می توانید صریحاً مسیر را به کلید حساب سرویس در کد منتقل کنید. گزینه اول امن تر است و به شدت توصیه می شود.
برای تنظیم متغیر محیط:
متغیر محیط زیست GOOGLE_APPLICATION_CREDENTIALS در مسیر پرونده پرونده JSON که حاوی کلید حساب خدمات شما است ، تنظیم کنید. این متغیر فقط مربوط به جلسه پوسته فعلی شما است ، بنابراین اگر جلسه جدیدی را باز کردید ، دوباره متغیر را تنظیم کنید.
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 از اعتبار حساب خدمات استفاده کنید.
از اعتبارنامه برای دسترسی به نشانه های Mint Access استفاده کنید
مگر اینکه از Admin SDK استفاده کنید ، که مجوز را به صورت خودکار انجام می دهد ، باید نشانه دسترسی را نعناع کرده و آن را برای ارسال درخواست اضافه کنید.
برای بازیابی یک نشانه دسترسی کوتاه مدت 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);
});
});
}
در این مثال ، کتابخانه مشتری 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>
:
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;
پروتکل میراث را مجوز ارسال درخواست ارسال کنید
با پروتکل HTTP Legacy ، هر درخواست باید حاوی کلید سرور از برگه پیام Cloud پیام تنظیمات کنسول Firebase باشد. برای XMPP ، برای ایجاد اتصال باید از همان کلید سرور استفاده کنید.
کلیدهای سرور میراث را مهاجرت کنید
با شروع از مارس 2020 ، FCM از ایجاد کلیدهای سرور میراث متوقف شد. کلیدهای سرور Legacy موجود به کار خود ادامه می دهند ، اما ما توصیه می کنیم در عوض از نسخه جدیدتر کلید سرور با برچسب کلید در کنسول Firebase استفاده کنید.
اگر می خواهید یک کلید سرور میراث موجود را حذف کنید ، می توانید این کار را در کنسول Google Cloud انجام دهید.
درخواست های HTTP را مجاز کنید
درخواست پیام از دو بخش تشکیل شده است: هدر HTTP و بدنه HTTP. هدر HTTP باید دارای هدرهای زیر باشد:
-
Authorization
: key = your_server_key
اطمینان حاصل کنید که این کلید سرور است که مقدار آن در برگه پیام Cloud پیام تنظیمات کنسول Firebase در دسترس است. کلیدهای Android ، Apple Platform و مرورگر توسط FCM رد می شوند. -
Content-Type
:application/json
برای JSON ؛application/x-www-form-urlencoded;charset=UTF-8
برای متن ساده.
اگرContent-Type
حذف شود ، قالب فرض می شود که متن ساده است.
به عنوان مثال:
Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA { "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data" : { ... }, }
برای ایجاد درخواست های ارسال ، درخواست های ارسال را برای جزئیات کامل مشاهده کنید. Legacy HTTP Reference Reference لیستی از تمام پارامترهایی که پیام شما می تواند داشته باشد را ارائه می دهد.
بررسی اعتبار یک کلید سرور
اگر هنگام ارسال پیام خطاهای تأیید اعتبار را دریافت می کنید ، اعتبار کلید سرور خود را بررسی کنید. به عنوان مثال ، در لینوکس ، دستور زیر را اجرا کنید:
api_key=YOUR_SERVER_KEY curl --header "Authorization: key=$api_key" \ --header Content-Type:"application/json" \ https://fcm.googleapis.com/fcm/send \ -d "{\"registration_ids\":[\"ABC\"]}"
اگر یک کد وضعیت 401 HTTP دریافت کنید ، کلید سرور شما معتبر نیست.
اتصال XMPP را مجاز کنید
با XMPP ، می توانید اتصال مداوم ، ناهمزمان و دو طرفه به سرورهای FCM را حفظ کنید. این اتصال می تواند برای ارسال و دریافت پیام بین سرور و دستگاه های اتصال FCM کاربران خود استفاده شود.
شما می توانید از بیشتر کتابخانه های XMPP برای مدیریت اتصال طولانی مدت به FCM استفاده کنید. XMPP Endpoint در fcm-xmpp.googleapis.com:5235
اجرا می شود. هنگام آزمایش عملکرد با کاربران غیر تولیدی ، باید در عوض به سرور پیش تولید در fcm-xmpp.googleapis.com:5236
متصل شوید (به درگاه مختلف توجه داشته باشید).
آزمایش منظم در مورد پیش تولید (محیطی کوچکتر که آخرین ساخت FCM در آن اجرا می شود) برای جداسازی کاربران واقعی از کد آزمایش مفید است. دستگاه های تست و کدهای تست اتصال به fcm-xmpp.googleapis.com:5236
باید از شناسه فرستنده FCM دیگری استفاده کند تا از خطرات ارسال پیام های تست به کاربران تولید یا ارسال پیام های بالادست از ترافیک تولید از طریق اتصالات آزمایش جلوگیری شود.
اتصال دارای دو الزام مهم است:
- شما باید یک اتصال امنیتی لایه حمل و نقل (TLS) را شروع کنید. توجه داشته باشید که FCM در حال حاضر از پسوند startTLS پشتیبانی نمی کند.
- FCM به مکانیسم احراز هویت ساده SASL با استفاده از
<your_ FCM _Sender_Id>@fcm.googleapis.com
( شناسه فرستنده FCM ) و کلید سرور به عنوان رمز عبور نیاز دارد. این مقادیر در برگه پیام Cloud Messaging از صفحه تنظیمات کنسول Firebase موجود است.
اگر در هر نقطه اتصال از بین برود ، باید بلافاصله دوباره وصل شوید. دیگر نیازی به عقب نشینی پس از قطع ارتباط نیست که پس از احراز هویت اتفاق می افتد. برای هر شناسه فرستنده ، FCM اجازه می دهد 2500 اتصال به طور موازی باشد.
قطعه های زیر نحوه انجام احراز هویت و مجوز برای اتصال XMPP به FCM را نشان می دهد.
سرور XMPP
سرور XMPP درخواست اتصال به FCM می کند
<stream:stream to="fcm.googleapis.com" version="1.0" xmlns="jabber:client" xmlns:stream="http://etherx.jabber.org/streams">
FCM
FCM اتصال را باز می کند و یک مکانیسم AUTH از جمله روش PLAIN
را درخواست می کند.
<stream:features> <mechanisms xmlns="urn:ietf:params:xml:ns:xmpp-sasl"> <mechanism>X-OAUTH2</mechanism> <mechanism>X-GOOGLE-TOKEN</mechanism> <mechanism>PLAIN</mechanism> </mechanisms> </stream:features>
سرور XMPP
سرور XMPP باید با استفاده از روش PLAIN
Auth پاسخ دهد و کلید سرور را از برگه پیام Cloud پیام تنظیمات کنسول Firebase ارائه می دهد.
<auth mechanism="PLAIN" xmlns="urn:ietf:params:xml:ns:xmpp-sasl">MTI2MjAwMzQ3OTMzQHByb2plY3RzLmdjbS5hb mFTeUIzcmNaTmtmbnFLZEZiOW1oekNCaVlwT1JEQTJKV1d0dw==</auth>
FCM
<success xmlns="urn:ietf:params:xml:ns:xmpp-sasl"/>
سرور XMPP
<stream:stream to="fcm.googleapis.com" version="1.0" xmlns="jabber:client" xmlns:stream="http://etherx.jabber.org/streams">
FCM
<stream:features> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/> <session xmlns="urn:ietf:params:xml:ns:xmpp-session"/> </stream:features>
سرور XMPP
<iq type="set"> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"></bind> </iq>
FCM
<iq type="result"> <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"> <jid>SENDER_ID@fcm.googleapis.com/RESOURCE</jid> </bind> </iq>
توجه: FCM هنگام مسیریابی پیام از منبع محدود استفاده نمی کند.
برای ایجاد درخواست های ارسال ، درخواست های ارسال را برای جزئیات کامل مشاهده کنید. مرجع پروتکل Legacy XMPP لیستی از تمام پارامترهایی را که پیام شما می تواند داشته باشد ارائه می دهد.