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

نقل البيانات من واجهات برمجة تطبيقات "المراسلة عبر السحابة الإلكترونية من Firebase" القديمة إلى الإصدار 1 من بروتوكول HTTP

يجب نقل التطبيقات التي تستخدم واجهتَي برمجة التطبيقات القديمة لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" المتوقّفة نهائيًا إلى HTTP وXMPP إلى واجهة برمجة التطبيقات HTTP v1 في أقرب فرصة ممكنة. إرسال الرسائل (بما في ذلك الرسائل الرئيسية) التي تتضمّن واجهات برمجة التطبيقات هذه، تم إيقافها نهائيًا في 20 حزيران (يونيو) 2023 ويبدأ الإيقاف النهائي في 22 تموز (يوليو) 2024.

اطّلِع على مزيد من المعلومات حول الميزات المتأثرة تحديدًا.

بالإضافة إلى الدعم المستمر والميزات الجديدة، تتمتع واجهة برمجة التطبيقات HTTP v1 API في ما يلي هذه المزايا التي تفوق واجهات برمجة التطبيقات القديمة:

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

تعديل نقطة نهاية الخادم

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

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

لتعديل نقطة نهاية الخادم للإصدار 1 من 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 v1 طلبات طلب رمز الدخول إلى OAuth 2.0. في حال استخدام SDK للمشرف لإرسال الرسائل، ستتولى المكتبة الرمز المميز نيابةً عنك. إذا كنت تستخدم Eef الأولية، نحصل على الرمز المميز كما هو موضح في هذا القسم ونضيفه إلى بعنوان 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 Functions (بما في ذلك وظائف السحابة الإلكترونية في Firebase)، استخدِم بيانات الاعتماد التلقائية للتطبيق (ADC). يستخدم ADC الخدمة التلقائية الحالية حساب للحصول على بيانات الاعتماد اللازمة لمصادقة الطلبات، وتتيح ADC اختبار محلي مرن عبر متغير البيئة GOOGLE_APPLICATION_CREDENTIALS للحصول على أكبر قدر من التشغيل الآلي تدفق التفويض، يمكنك استخدام ADC مع مكتبات خوادم 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 أو 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);

Python

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

#C

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

تقديم بيانات الاعتماد يدويًا

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

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

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

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

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

لضبط متغيّر البيئة:

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

Linux أو macOS

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

Windows

باستخدام PowerShell:

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

بعد إكمال الخطوات المذكورة أعلاه، ستظهر بيانات الاعتماد التلقائية للتطبيق (ADC) تحديد بيانات الاعتماد الخاصة بك ضمنيًا، مما يتيح لك استخدام بيانات اعتماد الحساب عند الاختبار أو التشغيل في بيئات غير تابعة لشركة Google.

استخدام بيانات الاعتماد لإنشاء رموز الدخول

يمكنك استخدام بيانات اعتماد Firebase مع مكتبة مصادقة Google لاسترداد رمز الدخول إلى 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

في هذا المثال، تصادق مكتبة برامج واجهة Google API على الطلب باستخدام رمز JSON المميز للويب أو JWT. لمزيد من المعلومات، يُرجى مراجعة رموز JSON المميّزة للويب

Python

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

بعد انتهاء صلاحية رمز الدخول، يتم استدعاء طريقة إعادة تحميل الرمز المميز تلقائيًا لاسترداد رمز الدخول المحدث.

لمنح الإذن بالوصول إلى خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، عليك طلب النطاق. https://www.googleapis.com/auth/firebase.messaging

لإضافة رمز الدخول إلى عنوان طلب HTTP:

أضِف الرمز المميّز كقيمة للعنوان Authorization بالتنسيق. Authorization: Bearer <access_token>:

عقدة.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}index.js

Python

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

تعديل حمولة طلبات الإرسال

الإصدار 1 من بروتوكول HTTP في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" يُحدث تغييرًا كبيرًا في بنية رسالة JSON حمولة البيانات. تضمن هذه التغييرات بشكل أساسي معالجة الرسائل بشكل صحيح. عند استلامها على منصات عملاء مختلفة؛ بالإضافة إلى ذلك، تمنحك التغييرات مرونة إضافية في التخصيص أو "تجاوز" وحقول الرسائل لكل منصة.

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

مثال: رسالة إشعار بسيطة

في ما يلي مقارنة لحمولة بسيطة جدًا للإشعارات - تحتوي على الحقول title وbody وdata فقط، ما يدل على النقاط الأساسية الاختلافات في حمولات البيانات الأساسية القديمة والإصدار الأول من HTTP.

قبل

{
  "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 مدمَجة

على عكس واجهة برمجة التطبيقات القديمة للمراسلة، لا تتيح واجهة برمجة التطبيقات HTTP v1 قيم JSON المضمّنة في الحقل data. يجب إجراء تحويل من JSON إلى سلسلة.

قبل

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

بعد

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

مثال: استهداف أنظمة أساسية متعددة

لتفعيل استهداف الأنظمة الأساسية المتعددة، أجرت واجهة برمجة التطبيقات القديمة عمليات إلغاء في الخلفية. على النقيض من ذلك، يوفر 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، قدم عنوان URL الرمز المميّز الحالي للتسجيل في مفتاح token بدلاً من المفتاح to.

قبل

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

لمزيد من النماذج والمعلومات حول واجهة برمجة التطبيقات للإصدار 1 من خدمة FCM HTTP، يمكنك الاطّلاع على ما يلي:

إرشادات حول طريقة إنشاء طلبات إرسال خادم التطبيق باستخدام HTTP v1 API جميع "REST" تستخدم المقتطفات v1 API ما لم يُذكر خلاف ذلك على وجه التحديد.
مدونة Firebase