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

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

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

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

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

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

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

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

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

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

अपने watch अनुरोध के साथ, ये वैकल्पिक फ़ील्ड भी दिए जा सकते हैं:

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

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

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

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

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

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

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

जवाब देखना

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

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

{
  "kind": "api#channel",
  "id": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

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

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

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

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

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

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

एडमिन SDK 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 होती है. इस चैनल से मिलने वाली हर सूचना के मैसेज नंबर, पिछले मैसेज के मैसेज नंबर से ज़्यादा होते हैं. हालांकि, मैसेज नंबर क्रम से नहीं होते.

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

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

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

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

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

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

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
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/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.com"
        }
      ]
    }
  ]
}

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

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

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

Admin SDK API के नोटिफ़िकेशन इवेंट को समझना

इस सेक्शन में, Admin SDK API के साथ पुश नोटिफ़िकेशन का इस्तेमाल करने पर मिलने वाले सूचना मैसेज के बारे में जानकारी दी गई है.

Reports API की पुश सूचनाओं में दो तरह के मैसेज होते हैं: सिंक मैसेज और इवेंट की सूचनाएं. मैसेज टाइप, X-Goog-Resource-State एचटीटीपी हेडर में दिखता है. इवेंट की सूचनाओं के लिए वैल्यू, activities.list तरीके के लिए वैल्यू जैसी ही होती हैं. हर ऐप्लिकेशन में यूनीक इवेंट होते हैं:

• admin
• calendar
• ड्राइव
• ग्रुप
• login
• मोबाइल
• सैमल
• टोकन
• user_accounts