लीगेसी FCM API से HTTP v1 पर माइग्रेट करें

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

चल रहे समर्थन और नई सुविधाओं के अलावा, HTTP v1 API में पुराने एपीआई की तुलना में ये फायदे हैं:

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

  • सभी प्लेटफ़ॉर्म पर संदेशों का अधिक कुशल अनुकूलन संदेश के मुख्य भाग के लिए, HTTP v1 API में सामान्य कुंजियाँ होती हैं जो सभी लक्षित उदाहरणों पर जाती हैं, साथ ही प्लेटफ़ॉर्म-विशिष्ट कुंजियाँ होती हैं जो आपको सभी प्लेटफ़ॉर्म पर संदेश को अनुकूलित करने देती हैं। यह आपको "ओवरराइड्स" बनाने की अनुमति देता है जो एक ही संदेश में विभिन्न क्लाइंट प्लेटफ़ॉर्म पर थोड़ा अलग पेलोड भेजता है।

  • नए क्लाइंट प्लेटफ़ॉर्म संस्करणों के लिए अधिक विस्तार योग्य और भविष्य-प्रूफ़ HTTP v1 API पूरी तरह से ऐप्पल प्लेटफ़ॉर्म, एंड्रॉइड और वेब पर उपलब्ध मैसेजिंग विकल्पों का समर्थन करता है। चूँकि JSON पेलोड में प्रत्येक प्लेटफ़ॉर्म का अपना परिभाषित ब्लॉक होता है, FCM आवश्यकतानुसार एपीआई को नए संस्करणों और नए प्लेटफ़ॉर्म तक बढ़ा सकता है।

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

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

  • इसे पथ में /v1 के साथ संस्करणित किया गया है।
  • पथ में /projects/myproject-ID/ प्रारूप में, आपके ऐप के लिए फायरबेस प्रोजेक्ट की प्रोजेक्ट आईडी शामिल है। यह आईडी फायरबेस कंसोल के सामान्य प्रोजेक्ट सेटिंग्स टैब में उपलब्ध है।
  • यह स्पष्ट रूप से send विधि को :send के रूप में निर्दिष्ट करता है।

HTTP v1 के लिए सर्वर एंडपॉइंट को अपडेट करने के लिए, इन तत्वों को अपने भेजें अनुरोधों के हेडर में एंडपॉइंट पर जोड़ें।

HTTP अनुरोध पहले

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

एक्सएमपीपी पहले अनुरोध करता है

लीगेसी एक्सएमपीपी संदेश निम्नलिखित समापन बिंदु के कनेक्शन पर भेजे जाते हैं:

fcm-xmpp.googleapis.com:5235

बाद

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

अनुरोध भेजने का प्राधिकरण अद्यतन करें

लीगेसी अनुरोधों में प्रयुक्त सर्वर कुंजी स्ट्रिंग के स्थान पर, HTTP v1 भेजने के अनुरोधों के लिए OAuth 2.0 एक्सेस टोकन की आवश्यकता होती है। यदि आप संदेश भेजने के लिए एडमिन एसडीके का उपयोग कर रहे हैं, तो लाइब्रेरी आपके लिए टोकन संभालती है। यदि आप कच्चे प्रोटोकॉल का उपयोग कर रहे हैं, तो इस अनुभाग में वर्णित अनुसार टोकन प्राप्त करें और इसे Authorization: Bearer <valid Oauth 2.0 token> ।

पहले

Authorization: key=AIzaSyZ-1u...0GBYzPu7Udno5aA

बाद

Authorization: Bearer ya29.ElqKBGN2Ri_Uz...HnS_uNreA

अपने सर्वर वातावरण के विवरण के आधार पर, फायरबेस सेवाओं के लिए सर्वर अनुरोधों को अधिकृत करने के लिए इन रणनीतियों के संयोजन का उपयोग करें:

  • Google एप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल (एडीसी)
  • एक सेवा खाता JSON फ़ाइल
  • सेवा खाते से प्राप्त एक अल्पकालिक OAuth 2.0 एक्सेस टोकन

यदि आपका एप्लिकेशन कंप्यूट इंजन, Google Kubernetes इंजन, ऐप इंजन, या क्लाउड फ़ंक्शंस (फ़ायरबेस के लिए क्लाउड फ़ंक्शंस सहित) पर चल रहा है , तो एप्लिकेशन डिफॉल्ट क्रेडेंशियल्स (एडीसी) का उपयोग करें। ADC अनुरोधों को अधिकृत करने के लिए क्रेडेंशियल प्राप्त करने के लिए आपके मौजूदा डिफ़ॉल्ट सेवा खाते का उपयोग करता है, और ADC पर्यावरण चर GOOGLE_APPLICATION_CREDENTIALS के माध्यम से लचीले स्थानीय परीक्षण को सक्षम करता है। प्राधिकरण प्रवाह के पूर्ण स्वचालन के लिए, एडमिन एसडीके सर्वर लाइब्रेरीज़ के साथ एडीसी का उपयोग करें।

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

एडीसी का उपयोग करके क्रेडेंशियल प्रदान करें

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

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

  2. यदि पर्यावरण चर सेट नहीं है, तो एडीसी डिफ़ॉल्ट सेवा खाते का उपयोग करता है जो कंप्यूट इंजन, Google कुबेरनेट्स इंजन, ऐप इंजन और क्लाउड फ़ंक्शंस उन सेवाओं पर चलने वाले अनुप्रयोगों के लिए प्रदान करते हैं।

  3. यदि एडीसी उपरोक्त क्रेडेंशियल्स में से किसी का भी उपयोग नहीं कर सकता है, तो सिस्टम एक त्रुटि उत्पन्न करता है।

निम्नलिखित एडमिन एसडीके कोड उदाहरण इस रणनीति को दर्शाता है। उदाहरण स्पष्ट रूप से एप्लिकेशन क्रेडेंशियल निर्दिष्ट नहीं करता है। हालाँकि, जब तक पर्यावरण चर सेट है, या जब तक एप्लिकेशन कंप्यूट इंजन, Google Kubernetes इंजन, ऐप इंजन, या क्लाउड फ़ंक्शंस पर चल रहा है, ADC अंतर्निहित रूप से क्रेडेंशियल ढूंढने में सक्षम है।

नोड.जे.एस

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

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

फायरबेस प्रोजेक्ट Google सेवा खातों का समर्थन करते हैं, जिनका उपयोग आप अपने ऐप सर्वर या विश्वसनीय वातावरण से फायरबेस सर्वर एपीआई को कॉल करने के लिए कर सकते हैं। यदि आप स्थानीय रूप से कोड विकसित कर रहे हैं या अपने एप्लिकेशन को ऑन-प्रिमाइसेस तैनात कर रहे हैं, तो आप सर्वर अनुरोधों को अधिकृत करने के लिए इस सेवा खाते के माध्यम से प्राप्त क्रेडेंशियल्स का उपयोग कर सकते हैं।

किसी सेवा खाते को प्रमाणित करने और उसे फायरबेस सेवाओं तक पहुंचने के लिए अधिकृत करने के लिए, आपको JSON प्रारूप में एक निजी कुंजी फ़ाइल उत्पन्न करनी होगी।

अपने सेवा खाते के लिए एक निजी कुंजी फ़ाइल बनाने के लिए:

  1. फायरबेस कंसोल में, सेटिंग्स > सेवा खाते खोलें।

  2. नई निजी कुंजी जनरेट करें पर क्लिक करें, फिर कुंजी जेनरेट करें पर क्लिक करके पुष्टि करें।

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

सेवा खाते के माध्यम से अधिकृत करते समय, आपके पास अपने आवेदन में क्रेडेंशियल प्रदान करने के लिए दो विकल्प होते हैं। आप या तो GOOGLE_APPLICATION_CREDENTIALS पर्यावरण चर सेट कर सकते हैं, या आप कोड में सेवा खाता कुंजी का पथ स्पष्ट रूप से पास कर सकते हैं। पहला विकल्प अधिक सुरक्षित है और इसकी पुरजोर अनुशंसा की जाती है।

पर्यावरण चर सेट करने के लिए:

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

लिनक्स या macOS

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

खिड़कियाँ

पॉवरशेल के साथ:

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

आपके द्वारा उपरोक्त चरणों को पूरा करने के बाद, एप्लिकेशन डिफॉल्ट क्रेडेंशियल्स (एडीसी) आपके क्रेडेंशियल्स को अंतर्निहित रूप से निर्धारित करने में सक्षम है, जो आपको गैर-Google वातावरण में परीक्षण या चलाने के दौरान सेवा खाता क्रेडेंशियल्स का उपयोग करने की अनुमति देता है।

एक्सेस टोकन प्राप्त करने के लिए क्रेडेंशियल्स का उपयोग करें

अल्पकालिक OAuth 2.0 एक्सेस टोकन प्राप्त करने के लिए अपनी पसंदीदा भाषा के लिए Google Auth लाइब्रेरी के साथ अपने Firebase क्रेडेंशियल का उपयोग करें:

नोड.जे.एस

 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 वेब टोकन देखें।

अजगर

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
messaging.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

आपके एक्सेस टोकन की समय सीमा समाप्त होने के बाद, अपडेटेड एक्सेस टोकन को पुनः प्राप्त करने के लिए टोकन रिफ्रेश विधि को स्वचालित रूप से कॉल किया जाता है।

एफसीएम तक पहुंच को अधिकृत करने के लिए, स्कोप https://www.googleapis.com/auth/firebase.messaging का अनुरोध करें।

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

Authorization हेडर के मान के रूप में टोकन को Authorization: Bearer <access_token> प्रारूप में जोड़ें:

नोड.जे.एस

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 " + getServiceAccountAccessToken());
httpURLConnection.setRequestProperty("Content-Type", "application/json; UTF-8");
return httpURLConnection;
FirebaseMessagingSnippets.java

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

FCM HTTP v1 JSON संदेश पेलोड की संरचना में एक महत्वपूर्ण परिवर्तन प्रस्तुत करता है। मुख्य रूप से, ये परिवर्तन यह सुनिश्चित करते हैं कि विभिन्न क्लाइंट प्लेटफ़ॉर्म पर प्राप्त होने पर संदेशों को सही ढंग से प्रबंधित किया जाए; इसके अतिरिक्त, परिवर्तन आपको प्रति प्लेटफ़ॉर्म संदेश फ़ील्ड को अनुकूलित करने या "ओवरराइड" करने के लिए अतिरिक्त लचीलापन देते हैं।

इस अनुभाग में उदाहरणों का निरीक्षण करने के अलावा, सभी प्लेटफ़ॉर्म पर एक संदेश को कस्टमाइज़ करना देखें और 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 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 एपीआई के साथ विशिष्ट उपकरणों को लक्षित करने के लिए, 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 HTTP v1 API के बारे में अधिक नमूनों और जानकारी के लिए, निम्नलिखित देखें: