पुश नोटिफ़िकेशन

इस दस्तावेज़ में पुश नोटिफ़िकेशन के इस्तेमाल का तरीका बताया गया है. इससे ऐप्लिकेशन दिखाई देता है.

खास जानकारी

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

पुश नोटिफ़िकेशन का इस्तेमाल करने के लिए, आपको ये दो काम करने होंगे:

  • कॉलबैक पाने के लिए यूआरएल या "वेबहुक" सेट अप करें.

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

  • आपको जिस संसाधन एंडपॉइंट को देखना है उसके लिए, (सूचना चैनल) सेट अप करें.

    चैनल, सूचना के लिए रूटिंग की जानकारी तय करता है मैसेज. चैनल सेट अप करने के दौरान, आपको उस यूआरएल की जानकारी देनी होगी जहां आपको सूचनाएं चाहिए. जब भी किसी चैनल के संसाधन में बदलाव होता है, डायरेक्ट्री एपीआई, POST के तौर पर सूचना का मैसेज भेजता है उस यूआरएल के लिए अनुरोध भेज सकते हैं.

फ़िलहाल, Directory API में उपयोगकर्ता संसाधन में हुए बदलावों के बारे में सूचनाएं पाने की सुविधा उपलब्ध है.

सूचना के चैनल बनाएं

पुश नोटिफ़िकेशन का अनुरोध करने के लिए, आपको हर उस संसाधन के लिए सूचना चैनल सेट अप करना होगा जिसे आपको मॉनिटर करना है. सूचना चैनल सेट अप करने के बाद, Directory API आपके ऐप्लिकेशन को सूचना देता है कि निगरानी में रखे गए किसी भी संसाधन में बदलाव हुआ है.

स्मार्टवॉच के लिए अनुरोध करना

दर्शकों के लिए उपलब्ध हर Directory API रिसॉर्स के लिए, यहां दिए गए फ़ॉर्मैट के यूआरआई पर एक watch तरीका होता है:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

सूचनाओं का चैनल सेट अप करने के लिए, करते हैं, तो एक POST अनुरोध संसाधन के लिए watch तरीका.

सूचना का हर चैनल किसी खास उपयोगकर्ता और, दोनों से जुड़ा होता है कोई खास संसाधन या संसाधनों का सेट. watch का अनुरोध तब तक सफल नहीं होगा, जब तक मौजूदा उपयोगकर्ता या सेवा खाता इस संसाधन का स्वामी है या उसे ऐक्सेस करने की अनुमति है.

उदाहरण

किसी एक डोमेन के User संसाधन के लिए, निगरानी के सभी अनुरोधों का सामान्य फ़ॉर्म यह है:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=domain&event=event
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

domain और event पैरामीटर का इस्तेमाल करके, उस डोमेन और इवेंट टाइप की जानकारी दें जिसके लिए आपको सूचनाएं चाहिए.

किसी ग्राहक के उपयोगकर्ता संसाधन के लिए, वॉच के सभी अनुरोधों का सामान्य फ़ॉर्म यह होता है:

POST https://admin.googleapis.com/admin/directory/users/v1/watch?customer=customer&event=event
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "params": {
    "ttl": 3600 // (Optional) Your requested time-to-live for this channel.
  }
}

ग्राहक के Google खाते का यूनीक आईडी बताने के लिए, customer और event पैरामीटर का इस्तेमाल करें. साथ ही, यह भी बताएं कि आपको किस तरह के इवेंट के लिए सूचनाएं चाहिए.

event के लिए संभावित वैल्यू ये हैं:

  • add: उपयोगकर्ता का बनाया गया इवेंट
  • delete: उपयोगकर्ता का मिटाया गया इवेंट
  • makeAdmin: उपयोगकर्ता एडमिन की स्थिति में बदलाव से जुड़ा इवेंट
  • undelete: उपयोगकर्ता ने मिटाया गया इवेंट वापस लाया
  • update: उपयोगकर्ता ने इवेंट अपडेट किया

ध्यान दें: यहां दिए गए उदाहरणों में, साफ़ तौर पर समझाने के लिए अनुरोध बॉडी को शामिल नहीं किया गया है.

डोमेन mydomain.com के लिए, उपयोगकर्ता के बनाए गए इवेंट देखें:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?domain=mydomain.com&event=add

ग्राहक my_customer के लिए, उपयोगकर्ता के बनाए गए इवेंट देखें:

POST https://admin.googleapis.com/admin/directory/v1/users/watch?customer=my_customer&event=add

ज़रूरी प्रॉपर्टी

हर watch अनुरोध के साथ, आपको ये फ़ील्ड देने होंगे:

  • id प्रॉपर्टी स्ट्रिंग, जो आपके प्रोजेक्ट में इस नए सूचना चैनल की खास तौर पर पहचान करती है. हमारा सुझाव है कि आप इनका इस्तेमाल करें एक यूनिवर्सल यूनीक आइडेंटिफ़ायर (UUID) या इससे मिलता-जुलता कोई अन्य यूनीक स्ट्रिंग. ज़्यादा से ज़्यादा 64 वर्ण इस्तेमाल किए जा सकते हैं.

    आपने जो आईडी वैल्यू सेट की है वह हर सूचना का X-Goog-Channel-Id एचटीटीपी हेडर मैसेज मिलेगा जो आपको इस चैनल के लिए मिला है.

  • type प्रॉपर्टी की स्ट्रिंग, जिसकी वैल्यू web_hook पर सेट की गई है.

  • उस यूआरएल पर सेट की गई address प्रॉपर्टी स्ट्रिंग जो सुनता है और इस सूचना चैनल से जुड़ी सूचनाओं का जवाब देता है. यह है वेबहुक कॉलबैक यूआरएल है और इसे एचटीटीपीएस का इस्तेमाल करना चाहिए.

    ध्यान दें कि Directory API, इस एचटीटीपीएस पते पर सिर्फ़ तब सूचनाएं भेज सकता है, जब आपके वेब सर्वर पर मान्य एसएसएल सर्टिफ़िकेट इंस्टॉल हो. अमान्य सर्टिफ़िकेट में ये शामिल हैं:

    • खुद हस्ताक्षर किए हुए सर्टिफ़िकेट.
    • किसी गैर-भरोसेमंद सोर्स के हस्ताक्षर किए हुए सर्टिफ़िकेट.
    • वे सर्टिफ़िकेट जो निरस्त कर दिए गए हैं.
    • ऐसे सर्टिफ़िकेट जिनका विषय टारगेट से मेल नहीं खाता होस्टनेम.

वैकल्पिक प्रॉपर्टी

आप इन वैकल्पिक फ़ील्ड को अपने watch अनुरोध:

  • ऐसी token प्रॉपर्टी जिसमें आर्बिट्ररी स्ट्रिंग शामिल की जाती है चैनल टोकन के रूप में इस्तेमाल करने के लिए मान. सूचना वाले चैनल का इस्तेमाल किया जा सकता है अलग-अलग मकसद के लिए टोकन जनरेट किए जा सकते हैं. उदाहरण के लिए, आप ताकि पुष्टि हो सके कि हर आने वाला मैसेज उस चैनल के लिए है जिसे आपने ऐप्लिकेशन बनाया गया—ताकि यह सुनिश्चित किया जा सके कि सूचना स्पूफ़ किया गया—या संदेश को उसके अंदर सही गंतव्य पर रूट करने के लिए इस चैनल के उद्देश्य के आधार पर आपका आवेदन. ज़्यादा से ज़्यादा लंबाई: 256 वर्ण.

    टोकन इसमें शामिल है हर सूचना में X-Goog-Channel-Token एचटीटीपी हेडर मैसेज मिलेगा जो आपके ऐप्लिकेशन को इस चैनल के लिए मिलता है.

    अगर सूचना चैनल के टोकन का इस्तेमाल किया जाता है, तो हमारा सुझाव है कि:

    • ऐसे एन्कोडिंग फ़ॉर्मैट का इस्तेमाल करें जिसे बढ़ाया जा सकता हो. जैसे, यूआरएल क्वेरी पैरामीटर. उदाहरण: forwardTo=hr&createdBy=mobile

    • OAuth टोकन जैसी संवेदनशील जानकारी शामिल न करें.

  • expiration प्रॉपर्टी की स्ट्रिंग, जिसे उस तारीख और समय के यूनिक्स टाइमस्टैंप (मिलीसेकंड में) पर सेट किया गया है जब आपको Directory API को इस सूचना चैनल के लिए मैसेज भेजना बंद करना है.

    अगर किसी चैनल के लिए खत्म होने का समय तय किया गया है, तो उसे X-Goog-Channel-Expiration एचटीटीपी हेडर की वैल्यू के तौर पर शामिल किया जाता है. यह वैल्यू, मनुष्य के पढ़ने लायक फ़ॉर्मैट में होती है. यह वैल्यू, आपके ऐप्लिकेशन को इस चैनल के लिए मिलने वाली हर सूचना के मैसेज में शामिल होती है.

अनुरोध के बारे में ज़्यादा जानकारी के लिए, एपीआई रेफ़रंस में उपयोगकर्ता संसाधन के लिए watch तरीका देखें.

जवाब देखें

अगर watch अनुरोध सही तरीके से सूचना बनाता है चैनल है, तो यह एक एचटीटीपी 200 OK स्टेटस कोड दिखाता है.

स्मार्टवॉच पर मिले जवाब के मैसेज में, आपके बनाए गए सूचना चैनल के बारे में जानकारी दी जाती है. इसकी जानकारी नीचे दिए गए उदाहरण में दी गई है.

{
  "kind": "api#channel",
  "id": "01234567-89ab-cdef-0123456789ab", // ID you specified for this channel.
  "resourceId": "B4ibMJiIhTjAQd7Ff2K2bexk8G4", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 1384823632000, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

आपके अनुरोध के तहत भेजी गई प्रॉपर्टी के अलावा, मिली जानकारी में resourceId और इस पर देखे जा रहे संसाधन की पहचान करने के लिए resourceUri सूचना का चैनल.

दिखाई गई जानकारी को सूचना देने वाले किसी अन्य चैनल पर भेजा जा सकता है कार्रवाइयों, जैसे कि जब आपको रिसेपमेंट को बंद करना हो सूचनाएं पर टैप करें.

जवाब के बारे में ज़्यादा जानकारी पाने के लिए, watch देखें एपीआई रेफ़रंस में उपयोगकर्ता संसाधन का तरीका.

मैसेज सिंक करना

किसी संसाधन को देखने के लिए सूचना चैनल बनाने के बाद, Directory API एक sync मैसेज भेजता है. इससे पता चलता है कि सूचनाएं भेजना शुरू हो गया है. X-Goog-Resource-State एचटीटीपी इन मैसेज के हेडर का मान sync है. नेटवर्क की वजह से समय से जुड़ी समस्याएं हैं, तो हो सकता है कि sync मैसेज मिले इससे पहले कि आपको watch तरीके का रिस्पॉन्स मिले.

sync सूचना को अनदेखा किया जा सकता है. हालांकि, इसका इस्तेमाल भी किया जा सकता है. उदाहरण के लिए, अगर आपको चैनल को बनाए रखना नहीं है, तो सूचनाएं पाने की सुविधा बंद करने के लिए, कॉल में X-Goog-Channel-ID और X-Goog-Resource-ID वैल्यू का इस्तेमाल किया जा सकता है. Google आपके यूआरएल पैरामीटर को कैसे इस्तेमाल करेगा, यह तय करने के लिए sync सूचना बाद के इवेंट.

Directory API, मैसेज पाने वाले आपके यूआरएल पर sync मैसेज भेजता है. इन मैसेज का फ़ॉर्मैट यहां दिया गया है.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

सिंक किए गए मैसेज में हमेशा एक X-Goog-Message-Number एचटीटीपी होता है 1 की हेडर वैल्यू. इस चैनल से मिलने वाली हर सूचना के मैसेज नंबर, पिछले मैसेज के मैसेज नंबर से ज़्यादा होते हैं. हालांकि, मैसेज नंबर क्रम से नहीं होते.

सूचना के चैनल रिन्यू करना

सूचना वाले चैनल के लिए, समयसीमा खत्म होने की तारीख और वैल्यू हो सकती है आपके अनुरोध या किसी डायरेक्ट्री एपीआई की इंटरनल सीमाओं से तय किया गया या डिफ़ॉल्ट (ज़्यादा पाबंदी वाली वैल्यू का इस्तेमाल किया जाता है). अगर चैनल के लिए, समयसीमा खत्म होने की कोई तारीख तय की गई है, तो watch तरीके से मिली जानकारी में, चैनल के खत्म होने की तारीख को यूनिक्स टाइमस्टैंप (मिलीसेकंड में) के तौर पर शामिल किया जाता है. इसके अलावा, X-Goog-Channel-Expiration एचटीटीपी हेडर में, आपके ऐप्लिकेशन को इस चैनल के लिए मिलने वाले हर सूचना मैसेज में, समयसीमा खत्म होने की तारीख और समय (मानव-पढ़ने लायक फ़ॉर्मैट में) शामिल होता है.

फ़िलहाल, सूचना चैनल को अपने-आप रिन्यू करने का कोई तरीका उपलब्ध नहीं है. जब किसी चैनल की समयसीमा खत्म होने वाली हो, तो आपको watch तरीके का इस्तेमाल करके, उसे नए चैनल से बदलना होगा. हमेशा की तरह, आपको नए चैनल की id प्रॉपर्टी के लिए एक यूनीक वैल्यू का इस्तेमाल करना होगा. ध्यान दें कि एक ही संसाधन के लिए, सूचना देने वाले दो चैनल चालू होने पर, "ओवरलैप" की अवधि हो सकती है.

सूचनाएं पाएं

जब भी निगरानी में रखे गए किसी संसाधन में बदलाव होता है, तो आपके ऐप्लिकेशन को बदलाव के बारे में बताने वाला सूचना मैसेज मिलता है. Directory API, इन मैसेज को एचटीटीपीएस POST अनुरोधों के तौर पर उस यूआरएल पर भेजता है जिसे आपने इस सूचना चैनल के लिए, address प्रॉपर्टी के तौर पर चुना है.

सूचना मैसेज के फ़ॉर्मैट को समझना

सूचना वाले सभी मैसेज में, एचटीटीपी हेडर का एक सेट होता है. कुछ तरह की सूचनाओं में मैसेज का मुख्य हिस्सा भी शामिल हो सकता है.

हेडर

डायरेक्ट्री एपीआई की ओर से आपके ईमेल पाने पर, सूचना वाले मैसेज पोस्ट किए गए यूआरएल में नीचे दिए गए एचटीटीपी हेडर शामिल हैं:

हेडर ब्यौरा
हमेशा मौजूद रहें
X-Goog-Channel-ID इसकी पहचान करने के लिए, यूयूआईडी या कोई दूसरी यूनीक स्ट्रिंग सूचना का चैनल.
X-Goog-Message-Number यह एक इंटिजर है, जिससे इस सूचना चैनल के लिए मैसेज की पहचान की जाती है. sync मैसेज के लिए यह वैल्यू हमेशा 1 होती है. मैसेज करें चैनल पर हर मैसेज के लिए, संख्या बढ़ती है, लेकिन क्रम में नहीं.
X-Goog-Resource-ID देखे गए संसाधन की पहचान करने वाली ओपेक वैल्यू. यह आईडी है सभी एपीआई वर्शन में अच्छी तरह से काम करता है.
X-Goog-Resource-State सूचना को ट्रिगर करने वाले संसाधन की नई स्थिति. वैल्यू इस तरह की हो सकती हैं: sync या इवेंट का नाम.
X-Goog-Resource-URI देखे गए संसाधन के लिए एपीआई वर्शन के हिसाब से खास आइडेंटिफ़ायर.
कभी-कभी मौजूद होता है
X-Goog-Channel-Expiration सूचना चैनल की समयसीमा खत्म होने की तारीख और समय, जिसे ऐसे फ़ॉर्मैट में दिखाया गया हो जिसे कोई भी व्यक्ति आसानी से पढ़ सके. सिर्फ़ तब मौजूद होता है, जब इसकी वैल्यू दी गई हो.
X-Goog-Channel-Token सूचना चैनल टोकन, जिसे आपके ऐप्लिकेशन ने सेट किया है, और जिसकी मदद से सूचना के सोर्स की पुष्टि की जा सकती है. सिर्फ़ तभी मौजूद होता है, जब तय किया गया है.

उपयोगकर्ताओं को सूचना देने वाले मैसेज के अनुरोध के मुख्य हिस्से में यह जानकारी शामिल होती है:

प्रॉपर्टी ब्यौरा
kind इसकी पहचान उपयोगकर्ता के संसाधन के तौर पर करता है. वैल्यू: तय की गई स्ट्रिंग "admin#directory#user".
id उपयोगकर्ता संसाधन का यूनीक आइडेंटिफ़ायर.
etag सूचना मैसेज का ETag. यह उपयोगकर्ता रिसॉर्स के ETag से अलग होता है.
primaryEmail उपयोगकर्ता का मुख्य ईमेल पता.

उदाहरण

User रिसॉर्स इवेंट के लिए सूचना मैसेज का सामान्य फ़ॉर्मैट यह है:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: directoryApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: 'https://admin.googleapis.com/admin/directory/v1/users?domain=domain&event=event
X-Goog-Resource-State:  event
X-Goog-Message-Number: 10

{
  "kind": "admin#directory#user",
  "id": long,
  "etag": string,
  "primaryEmail": string
}

उपयोगकर्ता के मिटाए गए इवेंट का उदाहरण:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 189
X-Goog-Channel-ID: deleteChannel
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Mon, 09 Dec 2013 22:24:23 GMT
X-Goog-Resource-ID:  B4ibMJiIhTjAQd7Ff2K2bexk8G4
X-Goog-Resource-URI: https://admin.googleapis.com/admin/directory/v1/users?domain=mydomain.com&event=delete&alt=json
X-Goog-Resource-State:  delete
X-Goog-Message-Number: 236440

{
  "kind": "admin#directory#user",
  "id": "111220860655841818702",
  "etag": "\"Mf8RAmnABsVfQ47MMT_18MHAdRE/evLIDlz2Fd9zbAqwvIp7Pzq8UAw\"",
  "primaryEmail": "user@mydomain.com"
}

सूचनाओं का उत्तर दें

अनुरोध पूरा होने की जानकारी देने के लिए, इनमें से कोई भी स्टेटस कोड दिखाया जा सकता है: 200, 201, 202, 204 या 102.

अगर आपकी सेवा Google की एपीआई क्लाइंट लाइब्रेरी का इस्तेमाल करती है और 500,502, 503 या 504 दिखाती है, तो Directory API एक्सपोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करता है. रिटर्न स्टेटस का कोई भी अन्य कोड, मैसेज भेजने में हुई गड़बड़ी माना जाता है.

सूचनाएं पाने की सुविधा बंद करें

expiration प्रॉपर्टी की मदद से, यह कंट्रोल किया जा सकता है कि सूचनाएं अपने-आप कब बंद हों. आप इससे पहले किसी खास चैनल के लिए, सूचनाएं पाने की सुविधा बंद करने का विकल्प चुना हो इसकी समयसीमा stop को इस पर कॉल करने पर खत्म होगी निम्न यूआरआई:

https://www.googleapis.com/admin/directory_v1/channels/stop

इस तरीके के लिए आपको कम से कम चैनल का id और resourceId प्रॉपर्टी, जैसा कि उदाहरण देखें. ध्यान दें कि अगर निर्देशिका एपीआई में कई तरह के ऐसे संसाधन जिनमें watch तरीके हैं, सिर्फ़ एक तरीका है stop तरीका.

सिर्फ़ ज़रूरी अनुमति वाले उपयोगकर्ता ही किसी चैनल को रोक सकते हैं. खास तौर पर:

  • अगर चैनल को किसी सामान्य उपयोगकर्ता खाते से बनाया गया था, तो चैनल को सिर्फ़ वही उपयोगकर्ता बंद कर सकता है जिसने चैनल बनाया था. यह उपयोगकर्ता, उसी क्लाइंट से जुड़ा होना चाहिए जिससे चैनल बनाया गया था. इसकी पहचान, ऑथराइज़ेशन टोकन से मिले OAuth 2.0 क्लाइंट आईडी से की जाती है.
  • अगर चैनल को किसी सेवा खाते से बनाया गया है, तो उसी क्लाइंट का कोई भी उपयोगकर्ता चैनल को बंद कर सकता है.

यहां दिया गया कोड सैंपल, सूचनाएं पाने की सुविधा बंद करने का तरीका बताता है:

POST https://www.googleapis.com/admin/directory_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}