इस दस्तावेज़ में उन पुश नोटिफ़िकेशन के इस्तेमाल का तरीका बताया गया है जो किसी संसाधन में बदलाव होने पर, आपके ऐप्लिकेशन को इसकी सूचना देते हैं.
खास जानकारी
डायरेक्ट्री एपीआई की मदद से, पुश नोटिफ़िकेशन मिलते हैं. इनकी मदद से, संसाधनों में हो रहे बदलावों पर नज़र रखी जा सकती है. इस सुविधा का इस्तेमाल करके, अपने ऐप्लिकेशन की परफ़ॉर्मेंस को बेहतर बनाया जा सकता है. इसकी मदद से, पोलिंग रिसॉर्स में शामिल अतिरिक्त नेटवर्क और उन पर होने वाले खर्च को हटाया जा सकता है जिनसे यह पता लगाया जा सकता है कि इन रिसॉर्स में बदलाव हुआ है या नहीं. जब भी कोई देखा गया संसाधन बदलता है, तो डायरेक्ट्री एपीआई आपके ऐप्लिकेशन को सूचना देता है.
पुश नोटिफ़िकेशन का इस्तेमाल करने के लिए, आपको दो काम करने होंगे:
पाने वाला यूआरएल या "वेबहुक" कॉलबैक रिसीवर सेट करें.
यह एक एचटीटीपीएस सर्वर है, जो एपीआई की सूचनाओं से जुड़े मैसेज को हैंडल करता है. ये मैसेज, संसाधन में बदलाव होने पर ट्रिगर होते हैं.
हर उस रिसॉर्स एंडपॉइंट के लिए सूचना चैनल सेट अप करें जिसे आपको देखना है.
चैनल, सूचना वाले मैसेज को रूट करने की जानकारी तय करता है. चैनल सेट अप करते समय, आपको उस यूआरएल की पहचान करनी होगी जिस पर आपको सूचनाएं चाहिए. जब भी किसी चैनल के संसाधन में बदलाव होता है, तो डायरेक्ट्री एपीआई उस यूआरएल पर
POST
अनुरोध के तौर पर सूचना का मैसेज भेजता है.
फ़िलहाल, डायरेक्ट्री एपीआई में उपयोगकर्ताओं के संसाधन में हुए बदलावों की सूचनाएं दी जाती हैं.
सूचना चैनल बनाएं
पुश नोटिफ़िकेशन का अनुरोध करने के लिए, आपको हर उस संसाधन के लिए सूचना का चैनल सेट अप करना होगा जिसे आपको मॉनिटर करना है. सूचना चैनल सेट अप हो जाने के बाद, देखे गए किसी भी रिसॉर्स में बदलाव होने पर, डायरेक्ट्री एपीआई आपके ऐप्लिकेशन को इसकी जानकारी देता है.
स्मार्टवॉच के लिए अनुरोध करें
देखे जा सकने वाले हर डायरेक्ट्री एपीआई संसाधन में, नीचे दिए गए फ़ॉर्म के यूआरआई पर जुड़ा एक watch
तरीका होता है:
https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch
किसी खास संसाधन में हुए बदलाव की जानकारी पाने वाले मैसेज के लिए, सूचना का चैनल सेट अप करने के लिए
संसाधन के watch
तरीके को POST
अनुरोध भेजें.
सूचना का हर चैनल, किसी खास उपयोगकर्ता और किसी खास संसाधन (या संसाधनों के सेट), दोनों से जुड़ा होता है. 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
प्रॉपर्टी स्ट्रिंग, यूआरएल के लिए सेट है, जो इस सूचना चैनल की सूचनाओं को सुनता है और उनके जवाब देता है. यह आपके वेबहुक कॉलबैक यूआरएल है और इसके लिए एचटीटीपीएस का इस्तेमाल करना ज़रूरी है.ध्यान दें कि डायरेक्ट्री एपीआई इस एचटीटीपीएस पते पर सूचनाएं सिर्फ़ तब भेज सकता है, जब आपके वेब सर्वर पर मान्य एसएसएल सर्टिफ़िकेट इंस्टॉल हो. अमान्य सर्टिफ़िकेट में ये शामिल हैं:
- खुद हस्ताक्षर किए हुए सर्टिफ़िकेट.
- किसी गैर-भरोसेमंद सोर्स के हस्ताक्षर किए हुए सर्टिफ़िकेट.
- वे सर्टिफ़िकेट जो निरस्त कर दिए गए हैं.
- ऐसे सर्टिफ़िकेट जिनका विषय, टारगेट होस्टनेम से मेल नहीं खाता.
वैकल्पिक प्रॉपर्टी
watch
अनुरोध के साथ,
इन वैकल्पिक फ़ील्ड की जानकारी भी दी जा सकती है:
-
ऐसी
token
प्रॉपर्टी जो चैनल टोकन के तौर पर इस्तेमाल करने के लिए, आर्बिट्रेरी स्ट्रिंग की वैल्यू तय करती है. सूचना चैनल के टोकन का इस्तेमाल अलग-अलग कामों के लिए किया जा सकता है. उदाहरण के लिए, टोकन का इस्तेमाल करके यह पुष्टि की जा सकती है कि आने वाला हर मैसेज, आपके ऐप्लिकेशन के बनाए गए चैनल के लिए है. इससे यह पक्का किया जा सकता है कि सूचना की नकल नहीं की गई है या फिर इस चैनल के मकसद के हिसाब से, मैसेज को ऐप्लिकेशन में सही डेस्टिनेशन पर भेजा जा सकता है. ज़्यादा से ज़्यादा लंबाई: 256 वर्ण.इस चैनल के लिए आपके ऐप्लिकेशन को मिलने वाली हर सूचना के मैसेज में, टोकन को
X-Goog-Channel-Token
एचटीटीपी हेडर में शामिल किया जाता है.सूचना चैनल के टोकन इस्तेमाल करने पर, हमारा सुझाव है कि आप:
कोड में बदलने के आसान फ़ॉर्मैट का इस्तेमाल करें, जैसे कि यूआरएल क्वेरी पैरामीटर. उदाहरण:
forwardTo=hr&createdBy=mobile
OAuth टोकन जैसी संवेदनशील जानकारी शामिल न करें.
-
expiration
प्रॉपर्टी स्ट्रिंग को उस यूनिक्स टाइमस्टैंप (मिलीसेकंड में) पर सेट किया गया है जिस तारीख और समय के लिए आपको डायरेक्ट्री एपीआई, इस सूचना चैनल के लिए मैसेज भेजना बंद करना है.अगर किसी चैनल के लिए, कोई तय समयसीमा तय की गई है, तो इसे आपके ऐप्लिकेशन को मिलने वाली सूचना के हर मैसेज में,
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
तरीका देखें.
मैसेज सिंक करें
किसी संसाधन को देखने के लिए सूचना चैनल बनाने के बाद, डायरेक्ट्री एपीआई एक sync
मैसेज भेजता है.
इससे यह जानकारी मिलती है कि सूचनाएं मिलने की सुविधा शुरू की जा रही है. इन मैसेज के लिए, X-Goog-Resource-State
एचटीटीपी हेडर की वैल्यू sync
है. नेटवर्क टाइमिंग से जुड़ी समस्याओं की वजह से, शायद watch
तरीके से रिस्पॉन्स मिलने से पहले भी आपको sync
मैसेज मिल सकता है.
sync
सूचना को अनदेखा करना सुरक्षित है, लेकिन आप इसका इस्तेमाल भी कर सकते हैं. उदाहरण के लिए, अगर आपको यह चैनल नहीं रखना है, तो सूचनाएं पाना बंद करने के लिए, कॉल में X-Goog-Channel-ID
और X-Goog-Resource-ID
वैल्यू इस्तेमाल करें. बाद के इवेंट की तैयारी करने के लिए,
sync
सूचना का इस्तेमाल करके भी
शुरुआत की जा सकती है.
डायरेक्ट्री एपीआई, ईमेल पाने वाले यूआरएल को
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
प्रॉपर्टी के लिए,
एक यूनीक वैल्यू का इस्तेमाल करना होगा. ध्यान दें कि जब एक ही संसाधन के लिए दो सूचना चैनल चालू हों, तब
हो सकता है कि एक ही समय पर दो बार सूचना भेज दी गई हो.
सूचनाएं पाएं
जब भी देखा गया कोई संसाधन बदलता है, तो आपके ऐप्लिकेशन को इस बदलाव के बारे में सूचना देने वाला एक मैसेज मिलता है. डायरेक्ट्री एपीआई इन
मैसेज को, एचटीटीपीएस POST
अनुरोध के तौर पर उस यूआरएल पर भेजता है जिसे आपने
सूचना देने वाले इस चैनल के लिए
address
प्रॉपर्टी के तौर पर बताया है.
सूचना मैसेज के फ़ॉर्मैट को समझना
सभी सूचना मैसेज में एचटीटीपी हेडर का एक सेट होता है. इसमें
X-Goog-
प्रीफ़िक्स शामिल होते हैं.
कुछ तरह की सूचनाओं में मैसेज का मुख्य हिस्सा भी शामिल हो सकता है.
हेडर
डायरेक्ट्री एपीआई की ओर से आपके ईमेल पाने वाले यूआरएल पर पोस्ट किए गए सूचना मैसेज में, ये एचटीटीपी हेडर शामिल होते हैं:
हेडर | ब्यौरा |
---|---|
हमेशा मौजूद रखें | |
|
यूयूआईडी या अन्य यूनीक स्ट्रिंग, जो आपने इस सूचना चैनल की पहचान के लिए दी थी. |
|
वह पूर्णांक जो इस सूचना चैनल के लिए इस मैसेज की पहचान करता है. sync मैसेज के लिए वैल्यू हमेशा 1 होती है. चैनल पर हर मैसेज के बाद,
मैसेज की संख्या बढ़ जाती है, लेकिन वह एक क्रम में नहीं होती. |
|
देखे गए संसाधन की पहचान करने वाली ओपेक वैल्यू. यह आईडी, एपीआई के सभी वर्शन में एक जैसा रहता है. |
|
सूचना को ट्रिगर करने वाली नई संसाधन स्थिति.
संभावित वैल्यू:
sync या कोई इवेंट का नाम.
|
|
देखे गए संसाधन के लिए, एपीआई वर्शन के हिसाब से आइडेंटिफ़ायर. |
कभी-कभी मौजूद होते हैं | |
|
सूचना चैनल की समयसीमा खत्म होने की तारीख और समय. इस फ़ॉर्मैट में जानकारी दी गई है, जिसे कोई भी व्यक्ति आसानी से पढ़ सकता है. यह सिर्फ़ तब मौजूद होता है, जब इसे सेट किया गया हो. |
|
सूचना चैनल का टोकन, जिसे आपके ऐप्लिकेशन ने सेट किया था. साथ ही, इसका इस्तेमाल सूचना के सोर्स की पुष्टि करने के लिए किया जा सकता है. यह जानकारी सिर्फ़ तब मौजूद होती है, जब दी गई हो. |
उपयोगकर्ताओं के लिए भेजे गए सूचना मैसेज में, अनुरोध के मुख्य हिस्से में यह जानकारी शामिल होती है:
प्रॉपर्टी | ब्यौरा |
---|---|
kind |
इसकी पहचान उपयोगकर्ता के संसाधन के तौर पर की गई है. वैल्यू: तय स्ट्रिंग "admin#directory#user ". |
id |
उपयोगकर्ता के संसाधन का यूनीक आइडेंटिफ़ायर. |
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
दिखाती है, तो डायरेक्ट्री एपीआई
एक्सपोनेन्शियल बैकऑफ़ के साथ फिर से कोशिश करता है.
सामान लौटाने के दूसरे स्टेटस कोड को मैसेज फ़ेलियर माना जाता है.
सूचनाएं पाने की सुविधा बंद करें
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" }