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

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

खास जानकारी

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

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

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

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

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

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

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

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

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

sync सूचना को अनदेखा करना सुरक्षित है, लेकिन आप उसका इस्तेमाल भी कर सकते हैं. उदाहरण के लिए, अगर आप तय करते हैं कि आपको X-Goog-Channel-ID का इस्तेमाल किया जा सकता है और इस कॉल में X-Goog-Resource-ID की वैल्यू सूचनाएं पाना बंद करने के लिए. Google आपके यूआरएल पैरामीटर को कैसे इस्तेमाल करेगा, यह तय करने के लिए 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- प्रीफ़िक्स. कुछ प्रकार की सूचनाओं में ये चीज़ें भी शामिल हो सकती हैं ईमेल का मुख्य हिस्सा.

हेडर

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

हेडर ब्यौरा
हमेशा मौजूद रहें
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 दिखाता है एक्स्पोनेंशियल बैकऑफ़ के साथ फिर से कोशिश करता है. यह माना जाता है कि सामान लौटाने की स्थिति बताने वाले दूसरे हर कोड से, मैसेज नहीं भेजा जा सका.

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

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

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

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

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

  • अगर चैनल किसी सामान्य उपयोगकर्ता खाते से बनाया गया था, तो एक ही क्लाइंट का उपयोगकर्ता (जैसा कि पुष्टि करने के टोकन) के ज़रिए, चैनल बनाने वाले व्यक्ति के पास चैनल को बंद करने का अधिकार होता है.
  • अगर चैनल को सेवा खाते का इस्तेमाल करके बनाया गया था, तो उस चैनल के किसी उपयोगकर्ता ने भी ऐसा किया हो क्लाइंट चैनल को रोक सकता है.

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

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