लेगसी FCM एपीआई से एचटीटीपी v1 पर माइग्रेट करें

एचटीटीपी और एक्सएमपीपी के लिए, बंद किए गए FCM लेगसी एपीआई का इस्तेमाल करने वाले ऐप्लिकेशन को जल्द से जल्द एचटीटीपी v1 एपीआई पर माइग्रेट कर देना चाहिए. उन एपीआई की मदद से मैसेज भेजने की सुविधा 20 जून, 2023 से बंद कर दी गई थी. इसमें अपस्ट्रीम मैसेज भी शामिल हैं. 22 जुलाई, 2024 से यह सुविधा पूरी तरह बंद हो जाएगी.

जिन सुविधाओं पर असर पड़ा है उनके बारे में ज़्यादा जानें.

HTTP v1 एपीआई में, नई सुविधाओं और सहायता के साथ-साथ, लेगसी एपीआई की तुलना में ये फ़ायदे भी हैं:

  • ऐक्सेस टोकन की मदद से बेहतर सुरक्षा एचटीटीपी v1 एपीआई, OAuth2 सुरक्षा मॉडल के मुताबिक कुछ समय के लिए बने रहने वाले ऐक्सेस टोकन का इस्तेमाल करता है. अगर ऐक्सेस टोकन सार्वजनिक हो जाता है, तो उसकी समयसीमा खत्म होने से पहले, उसे सिर्फ़ एक घंटे तक नुकसान पहुंचाने के मकसद से इस्तेमाल किया जा सकता है. रीफ़्रेश टोकन को, लेगसी एपीआई में इस्तेमाल की जाने वाली सुरक्षा कुंजियों के मुकाबले कम बार भेजा जाता है. इस वजह से, उनके कैप्चर किए जाने की संभावना बहुत कम होती है.

  • अलग-अलग प्लैटफ़ॉर्म के लिए मैसेज को ज़्यादा बेहतर तरीके से पसंद के मुताबिक बनाना मैसेज के मुख्य हिस्से के लिए, एचटीटीपी v1 एपीआई में ऐसी सामान्य कुंजियां होती हैं जो टारगेट किए गए सभी इंस्टेंस पर भेजी जाती हैं. साथ ही, प्लैटफ़ॉर्म के हिसाब से ऐसी कुंजियां भी होती हैं जिनकी मदद से, अलग-अलग प्लैटफ़ॉर्म के लिए मैसेज को पसंद के मुताबिक बनाया जा सकता है. इससे, "ओवरराइड" बनाए जा सकते हैं, जो एक ही मैसेज में अलग-अलग क्लाइंट प्लैटफ़ॉर्म पर थोड़े अलग पेलोड भेजते हैं.

  • क्लाइंट प्लैटफ़ॉर्म के नए वर्शन के लिए, ज़्यादा बेहतर और आने वाले समय के हिसाब से HTTP v1 API, Apple प्लैटफ़ॉर्म, Android, और वेब पर उपलब्ध मैसेजिंग विकल्पों के साथ पूरी तरह से काम करता है. JSON पेलोड में हर प्लैटफ़ॉर्म का अपना अलग ब्लॉक होता है. इसलिए, FCM ज़रूरत के हिसाब से एपीआई को नए वर्शन और नए प्लैटफ़ॉर्म पर लगा सकता है.

सर्वर एंडपॉइंट को अपडेट करना

एचटीटीपी v1 एपीआई के एंडपॉइंट का यूआरएल, लेगसी एंडपॉइंट से इन तरीकों से अलग होता है:

  • यह वर्शन वाला है और पाथ में /v1 है.
  • पाथ में, आपके ऐप्लिकेशन के Firebase प्रोजेक्ट का प्रोजेक्ट आईडी, /projects/myproject-ID/ फ़ॉर्मैट में होता है. यह आईडी, Firebase कंसोल के सामान्य प्रोजेक्ट सेटिंग टैब में उपलब्ध है.
  • इसमें send तरीके को साफ़ तौर पर :send के तौर पर बताया गया है.

एचटीटीपी v1 के लिए सर्वर एंडपॉइंट को अपडेट करने के लिए, अपने भेजे गए अनुरोधों के हेडर में एंडपॉइंट में ये एलिमेंट जोड़ें.

इससे पहले एचटीटीपी अनुरोध

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

अनुरोध भेजने की अनुमति देने का तरीका अपडेट करें

पुराने अनुरोधों में इस्तेमाल की गई सर्वर कुंजी स्ट्रिंग के बजाय, एचटीटीपी 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 (Cloud Functions for Firebase के साथ) पर चल रहा है, तो ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल (एडीसी) का इस्तेमाल करें. अनुरोधों को अनुमति देने के लिए क्रेडेंशियल हासिल करने के लिए, ADC आपके मौजूदा डिफ़ॉल्ट सेवा खाते का इस्तेमाल करता है. साथ ही, ADC, एनवायरमेंट वैरिएबल GOOGLE_APPLICATION_CREDENTIALS के ज़रिए सुविधाजनक लोकल टेस्टिंग की सुविधा देता है. अनुमति देने के फ़्लो को पूरी तरह से अपने-आप पूरा करने के लिए, एडमिन SDK सर्वर लाइब्रेरी के साथ-साथ ADC का इस्तेमाल करें.

अगर आपका ऐप्लिकेशन, Google के सर्वर एनवायरमेंट के बजाय किसी दूसरे सर्वर एनवायरमेंट पर चल रहा है, तो आपको अपने Firebase प्रोजेक्ट से सेवा खाते की JSON फ़ाइल डाउनलोड करनी होगी. जब तक आपके पास निजी पासकोड वाली फ़ाइल वाले फ़ाइल सिस्टम का ऐक्सेस है, तब तक मैन्युअल तरीके से हासिल किए गए इन क्रेडेंशियल का इस्तेमाल करके अनुरोधों को अनुमति देने के लिए, एनवायरमेंट वैरिएबल GOOGLE_APPLICATION_CREDENTIALS का इस्तेमाल किया जा सकता है. अगर आपके पास ऐसी फ़ाइल का ऐक्सेस नहीं है, तो आपको अपने कोड में सेवा खाते की फ़ाइल का रेफ़रंस देना होगा. ऐसा करते समय, आपको सावधानी बरतनी होगी, क्योंकि इससे आपके क्रेडेंशियल का खुलासा हो सकता है.

एडीसी का इस्तेमाल करके क्रेडेंशियल देना

Google ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल (ADC), आपके क्रेडेंशियल की जांच इस क्रम में करते हैं:

  1. एडीसी यह जांच करता है कि एनवायरमेंट वैरिएबल GOOGLE_APPLICATION_CREDENTIALS सेट है या नहीं. अगर वैरिएबल सेट है, तो ADC उस सेवा खाते की फ़ाइल का इस्तेमाल करता है जिस पर वैरिएबल ले जाता है.

  2. अगर एनवायरमेंट वैरिएबल सेट नहीं है, तो ADC उस डिफ़ॉल्ट सेवा खाते का इस्तेमाल करता है जो Compute Engine, Google Kubernetes Engine, App Engine, और Cloud Functions, उन सेवाओं पर चलने वाले ऐप्लिकेशन के लिए उपलब्ध कराता है.

  3. अगर एडीसी ऊपर दिए गए किसी भी क्रेडेंशियल का इस्तेमाल नहीं कर पाता है, तो सिस्टम में गड़बड़ी का मैसेज दिखता है.

एडमिन SDK कोड के इस उदाहरण में, इस रणनीति के बारे में बताया गया है. उदाहरण में, ऐप्लिकेशन के क्रेडेंशियल के बारे में साफ़ तौर पर नहीं बताया गया है. हालांकि, जब तक एनवायरमेंट वैरिएबल सेट है या ऐप्लिकेशन Compute Engine, Google Kubernetes Engine, App Engine या Cloud Functions पर चल रहा है, तब तक ADC अपने-आप क्रेडेंशियल ढूंढ सकता है.

Node.js

admin.initializeApp({
  credential: admin.credential.applicationDefault(),
});

Java

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)
}

C#

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

मैन्युअल तरीके से क्रेडेंशियल देना

Firebase प्रोजेक्ट, Google सेवा खातों के साथ काम करते हैं. इनका इस्तेमाल करके, अपने ऐप्लिकेशन सर्वर या भरोसेमंद एनवायरमेंट से Firebase सर्वर एपीआई को कॉल किया जा सकता है. अगर स्थानीय तौर पर कोड डेवलप किया जा रहा है या अपने ऐप्लिकेशन को ऑन-प्राइमिस डिप्लॉय किया जा रहा है, तो सर्वर के अनुरोधों को अनुमति देने के लिए, इस सेवा खाते से मिले क्रेडेंशियल का इस्तेमाल किया जा सकता है.

किसी सेवा खाते की पुष्टि करने और उसे Firebase की सेवाओं को ऐक्सेस करने की अनुमति देने के लिए, आपको JSON फ़ॉर्मैट में निजी कुंजी फ़ाइल जनरेट करनी होगी.

अपने सेवा खाते के लिए, निजी पासकोड वाली फ़ाइल जनरेट करने के लिए:

  1. Firebase कंसोल में, सेटिंग > सेवा खाते खोलें.

  2. नई निजी कुंजी जनरेट करें पर क्लिक करें. इसके बाद, कुंजी जनरेट करें पर क्लिक करके पुष्टि करें.

  3. कुंजी वाली JSON फ़ाइल को सुरक्षित तरीके से सेव करें.

सेवा खाते से अनुमति देते समय, आपके पास अपने ऐप्लिकेशन को क्रेडेंशियल देने के लिए दो विकल्प होते हैं. GOOGLE_APPLICATION_CREDENTIALS एनवायरमेंट वैरिएबल सेट किया जा सकता है या कोड में सेवा खाते की कुंजी का पाथ साफ़ तौर पर दिया जा सकता है. पहला विकल्प ज़्यादा सुरक्षित है और इसका सुझाव दिया जाता है.

एनवायरमेंट वैरिएबल सेट करने के लिए:

एनवायरमेंट वैरिएबल GOOGLE_APPLICATION_CREDENTIALS को उस JSON फ़ाइल के फ़ाइल पाथ पर सेट करें जिसमें आपके सेवा खाते की कुंजी मौजूद है. यह वैरिएबल सिर्फ़ आपके मौजूदा शेल सेशन पर लागू होता है. इसलिए, नया सेशन खोलने पर वैरिएबल को फिर से सेट करें.

Linux या macOS

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

शीशा

PowerShell की मदद से:

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

ऊपर दिए गए चरणों को पूरा करने के बाद, ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल (एडीसी) आपके क्रेडेंशियल को सीधे तौर पर तय कर सकते हैं. इससे, Google से बाहर के प्लैटफ़ॉर्म में जांच करते समय या रन करते समय, सेवा खाते के क्रेडेंशियल का इस्तेमाल किया जा सकता है.

ऐक्सेस टोकन बनाने के लिए क्रेडेंशियल का इस्तेमाल करना

कुछ समय तक चलने वाले OAuth 2.0 ऐक्सेस टोकन को फिर से पाने के लिए, अपनी पसंदीदा भाषा के लिए Google ऑथराइज़ेशन लाइब्रेरी के साथ अपने Firebase क्रेडेंशियल का इस्तेमाल करें:

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);
    });
  });
}

इस उदाहरण में, 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.token

Java

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.

ऐक्सेस टोकन को किसी एचटीटीपी अनुरोध के हेडर में जोड़ने के लिए:

Authorization हेडर की वैल्यू के तौर पर Authorization: Bearer <access_token> फ़ॉर्मैट में टोकन जोड़ें:

node.js

headers: {
  'Authorization': 'Bearer ' + accessToken
}

Python

headers = {
  'Authorization': 'Bearer ' + _get_access_token(),
  'Content-Type': 'application/json; UTF-8',
}

Java

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;

भेजने के अनुरोधों का पेलोड अपडेट करना

FCM HTTP v1 में, JSON मैसेज के पेलोड के स्ट्रक्चर में एक अहम बदलाव किया गया है. मुख्य तौर पर, ये बदलाव यह पक्का करते हैं कि अलग-अलग क्लाइंट प्लैटफ़ॉर्म पर मैसेज मिलने पर उन्हें सही तरीके से हैंडल किया जाए. इसके अलावा, इन बदलावों से आपको हर प्लैटफ़ॉर्म के हिसाब से मैसेज फ़ील्ड को पसंद के मुताबिक बनाने या "बदलने" की सुविधा भी मिलती है.

इस सेक्शन में दिए गए उदाहरणों की जांच करने के अलावा, अलग-अलग प्लैटफ़ॉर्म पर मैसेज को पसंद के मुताबिक बनाना लेख पढ़ें. साथ ही, एचटीटीपी v1 को इस्तेमाल करने के बारे में जानने के लिए, एपीआई का संदर्भ देखें.

उदाहरण: सूचना का आसान मैसेज

यहां सूचना के एक बहुत ही आसान पेलोड की तुलना की गई है. इसमें सिर्फ़ title, body, और data फ़ील्ड शामिल हैं. इससे, लेगसी और एचटीटीपी 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 डेटा

लेगसी मैसेजिंग एपीआई के उलट, एचटीटीपी v1 एपीआई, data फ़ील्ड में नेस्ट की गई JSON वैल्यू के साथ काम नहीं करता. JSON को स्ट्रिंग में बदलना ज़रूरी है.

इससे पहले

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

इसके बाद

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

उदाहरण: एक से ज़्यादा प्लैटफ़ॉर्म को टारगेट करना

एक से ज़्यादा प्लैटफ़ॉर्म पर टारगेटिंग की सुविधा चालू करने के लिए, लेगसी एपीआई ने बैकएंड में बदलाव किया. इसके उलट, एचटीटीपी 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"
        }
      }
    }
  }
}

उदाहरण: प्लैटफ़ॉर्म के लिए बदलाव करने की सुविधा का इस्तेमाल करके कस्टमाइज़ करना

एचटीटीपी 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 की मदद से खास डिवाइसों को टारगेट करने के लिए, 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 एचटीटीपी v1 एपीआई के ज़्यादा सैंपल और जानकारी के लिए, यहां देखें: