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

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

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

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

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

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

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

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

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

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

नीचे दिए गए एडमिन 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 से बाहर के एनवायरमेंट में टेस्ट करते समय या चलाते समय, सेवा खाते के क्रेडेंशियल का इस्तेमाल किया जा सकता है.

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

अपनी पसंदीदा भाषा के लिए, Google की पुष्टि करने वाली लाइब्रेरी के साथ-साथ Firebase क्रेडेंशियल का इस्तेमाल करें. इससे, कम समय के लिए इस्तेमाल होने वाला 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);
    });
  });
}

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

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

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

उदाहरण: खास डिवाइस को टारगेट करना

कुछ खास डिवाइसों को एचटीटीपी v1 एपीआई के ज़रिए टारगेट करने के लिए, डिवाइस के मौजूदा रजिस्ट्रेशन टोकन को to कुंजी के बजाय token कुंजी में दें.

इससे पहले

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