تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الانتقال من بروتوكول HTTP القديم إلى HTTP v1

يجب أن تفكر التطبيقات التي تستخدم واجهة برمجة تطبيقات HTTP القديمة من FCM في الترحيل إلى واجهة برمجة تطبيقات HTTP v1 باستخدام الإرشادات الواردة في هذا الدليل. تتميز واجهة برمجة تطبيقات HTTP v1 بالمزايا التي تتفوق على واجهة برمجة التطبيقات القديمة:

أمان أفضل عبر رموز الوصول تستخدم واجهة برمجة تطبيقات HTTP v1 رموز وصول قصيرة العمر وفقًا لنموذج أمان OAuth2. في حالة ما إذا أصبح رمز الوصول عامًا ، فلا يمكن استخدامه إلا بشكل ضار لمدة ساعة أو نحو ذلك قبل انتهاء صلاحيته. لا يتم إرسال الرموز المميزة للتحديث كثيرًا مثل مفاتيح الأمان المستخدمة في واجهة برمجة التطبيقات القديمة ، لذلك تقل احتمالية التقاطها.
تخصيص أكثر فاعلية للرسائل عبر الأنظمة الأساسية بالنسبة إلى نص الرسالة ، تحتوي واجهة برمجة تطبيقات HTTP v1 API على مفاتيح مشتركة تنتقل إلى جميع الحالات المستهدفة ، بالإضافة إلى المفاتيح الخاصة بالنظام الأساسي التي تتيح لك تخصيص الرسالة عبر الأنظمة الأساسية. يتيح لك هذا إنشاء "تجاوزات" ترسل حمولات مختلفة قليلاً إلى منصات عملاء مختلفة في رسالة واحدة.
أكثر قابلية للتوسيع ومثبتة للمستقبل لإصدارات منصة العميل الجديدة تدعم واجهة برمجة تطبيقات HTTP v1 خيارات المراسلة المتوفرة على أنظمة Apple الأساسية و Android و Web بشكل كامل. نظرًا لأن كل منصة لها كتلة محددة خاصة بها في حمولة JSON ، يمكن لـ FCM توسيع واجهة برمجة التطبيقات إلى إصدارات جديدة ومنصات جديدة حسب الحاجة.

قم بتحديث نقطة نهاية الخادم

يختلف عنوان URL لنقطة النهاية لواجهة برمجة تطبيقات HTTP v1 عن endpont القديم في الطرق التالية:

تم إصداره ، مع /v1 في المسار.
يحتوي المسار على معرّف المشروع لمشروع Firebase لتطبيقك ، بالتنسيق /projects/myproject-ID/ . يتوفر هذا المعرف في علامة التبويب إعدادات المشروع العامة لوحدة تحكم Firebase.
وهي تحدد بوضوح طريقة send على النحو التالي :send .

لتحديث نقطة نهاية الخادم لـ HTTP v1 ، أضف هذه العناصر إلى نقطة النهاية في رأس طلبات الإرسال.

قبل

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

بعد

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

تحديث الإذن لطلبات الإرسال

بدلاً من سلسلة مفتاح الخادم المستخدمة في الطلبات القديمة ، تتطلب طلبات إرسال HTTP v1 رمز وصول 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:

بيانات الاعتماد الافتراضية لتطبيق Google (ADC)
ملف JSON لحساب الخدمة
رمز دخول OAuth 2.0 قصير العمر مشتق من حساب خدمة

إذا كان تطبيقك يعمل على Compute Engine أو Google Kubernetes Engine أو App Engine أو وظائف السحابة (بما في ذلك وظائف السحابة لـ 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 أو وظائف السحابة.

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 ، والتي يمكنك استخدامها للاتصال بواجهات برمجة تطبيقات خادم Firebase من خادم التطبيق أو البيئة الموثوقة. إذا كنت تقوم بتطوير التعليمات البرمجية محليًا أو نشر تطبيقك محليًا ، فيمكنك استخدام بيانات الاعتماد التي تم الحصول عليها عبر حساب الخدمة هذا لتفويض طلبات الخادم.

لمصادقة حساب خدمة وتفويضه للوصول إلى خدمات Firebase ، يجب عليك إنشاء ملف مفتاح خاص بتنسيق JSON.

لإنشاء ملف مفتاح خاص لحساب الخدمة الخاص بك:

في وحدة تحكم Firebase ، افتح الإعدادات> حسابات الخدمة .
انقر فوق إنشاء مفتاح خاص جديد ، ثم قم بالتأكيد بالنقر فوق إنشاء مفتاح .
قم بتخزين ملف JSON الذي يحتوي على المفتاح بشكل آمن.

عند التفويض عبر حساب خدمة ، لديك خياران لتقديم بيانات الاعتماد لتطبيقك. يمكنك إما تعيين متغير بيئة GOOGLE_APPLICATION_CREDENTIALS ، أو يمكنك صراحة تمرير المسار إلى مفتاح حساب الخدمة في التعليمات البرمجية. الخيار الأول أكثر أمانًا ويوصى به بشدة.

لتعيين متغير البيئة:

اضبط متغير البيئة GOOGLE_APPLICATION_CREDENTIALS على مسار ملف ملف JSON الذي يحتوي على مفتاح حساب الخدمة. ينطبق هذا المتغير فقط على جلسة shell الحالية ، لذلك إذا فتحت جلسة جديدة ، فقم بتعيين المتغير مرة أخرى.

Linux أو 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) تحديد بيانات الاعتماد الخاصة بك بشكل ضمني ، مما يسمح لك باستخدام بيانات اعتماد حساب الخدمة عند الاختبار أو التشغيل في بيئات غير تابعة لـ Google.

استخدم بيانات الاعتماد لصك رموز الوصول

استخدم بيانات اعتماد Firebase مع مكتبة مصادقة Google للغتك المفضلة لاسترداد رمز وصول OAuth 2.0 قصير العمر:

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 الطلب باستخدام رمز ويب 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.tokenmessaging.py

جافا

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  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 " + getAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;Messaging.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"
    }
  }
}

مثال: استهداف منصات متعددة

لتمكين الاستهداف متعدد الأنظمة الأساسية ، نفذت واجهة برمجة التطبيقات القديمة عمليات تجاوز في الخلفية. على النقيض من ذلك ، يوفر 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 المرونة لتخصيص الرسائل لكل نظام أساسي.

قبل

// 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 ، قم بتوفير رمز التسجيل المميز الحالي للجهاز في مفتاح token بدلاً من مفتاح to .

قبل

  { "notification": {
      "body": "This is an FCM notification message!",
      "time": "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 ، راجع مدونة Firebase .