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

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

खास जानकारी

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

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

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

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

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

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

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

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

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

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

दर्शकों के लिए उपलब्ध हर Directory API रिसॉर्स के लिए, यहां दिए गए फ़ॉर्मैट के यूआरआई पर एक 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.
  }
}

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

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 है. नेटवर्क के समय से जुड़ी समस्याओं की वजह से, हो सकता है कि watch तरीके का जवाब मिलने से पहले ही आपको sync मैसेज मिल जाए.

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

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

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

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

सूचनाएं पाएं

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

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

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

हेडर

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

हेडर ब्यौरा
हमेशा मौजूद
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 प्रॉपर्टी देनी होंगी, जैसा कि यहां दिए गए उदाहरण में दिखाया गया है. ध्यान दें कि अगर Directory API में कई तरह के ऐसे संसाधन हैं जिनमें 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"
}