ข้อความ Push

พร็อพเพอร์ตี้ที่จำเป็น

ในคำขอ watch แต่ละรายการ คุณจะต้องกรอกข้อมูลในช่องต่อไปนี้

• สตริงพร็อพเพอร์ตี้ id ที่ระบุช่องทางการแจ้งเตือนใหม่นี้ภายในโปรเจ็กต์ของคุณโดยไม่ซ้ำกัน เราขอแนะนำให้ใช้ตัวระบุที่ไม่ซ้ำกับผู้อื่น (UUID) หรือสตริงที่ไม่ซ้ำกันแบบอื่นๆ ที่คล้ายกัน ความยาวสูงสุด: 64 อักขระ

  ระบบจะแสดงค่ารหัสที่คุณตั้งไว้ในX-Goog-Channel-Idส่วนหัว HTTP ของข้อความการแจ้งเตือนทุกข้อความที่คุณได้รับสำหรับช่องนี้

• ตั้งค่าสตริงพร็อพเพอร์ตี้ type เป็นค่า web_hook

• สตริงพร็อพเพอร์ตี้ address ที่ตั้งค่าเป็น URL ที่คอยฟังและตอบสนองต่อการแจ้งเตือนสําหรับช่องทางการแจ้งเตือนนี้ นี่คือ URL การเรียกกลับของ Webhook ของคุณ และต้องใช้ HTTPS

  โปรดทราบว่า Admin SDK API จะส่งการแจ้งเตือนไปยังที่อยู่ HTTPS นี้ได้ก็ต่อเมื่อมีการติดตั้งใบรับรอง SSL ที่ถูกต้องในเว็บเซิร์ฟเวอร์เท่านั้น ใบรับรองที่ไม่ถูกต้องมีดังนี้

  • ใบรับรองแบบ Self-signed
  • ใบรับรองที่ลงนามโดยแหล่งที่มาที่ไม่น่าเชื่อถือ
  • ใบรับรองที่เพิกถอนไปแล้ว
  • ใบรับรองที่มีเรื่องไม่ตรงกับชื่อโฮสต์เป้าหมาย

พร็อพเพอร์ตี้ที่ไม่บังคับ

นอกจากนี้ คุณยังระบุฟิลด์ที่ไม่บังคับเหล่านี้พร้อมกับคำขอwatchได้ด้วย

• พร็อพเพอร์ตี้ token ที่ระบุค่าสตริงแบบอิสระเพื่อใช้เป็นโทเค็นของช่อง คุณใช้โทเค็นช่องทางการแจ้งเตือนเพื่อวัตถุประสงค์ต่างๆ ได้ เช่น คุณสามารถใช้โทเค็นเพื่อยืนยันว่าข้อความขาเข้าแต่ละรายการมีไว้สำหรับช่องทางที่แอปพลิเคชันของคุณสร้างขึ้น เพื่อให้แน่ใจว่าไม่มีการปลอมแปลงการแจ้งเตือน หรือเพื่อกำหนดเส้นทางข้อความไปยังปลายทางที่เหมาะสมภายในแอปพลิเคชันตามวัตถุประสงค์ของช่องทางนี้ ความยาวสูงสุด: 256 อักขระ

  โทเค็นจะรวมอยู่ในส่วนหัว HTTP X-Goog-Channel-Token ในทุกข้อความแจ้งเตือนที่แอปพลิเคชันได้รับสำหรับแชแนลนี้

  หากคุณใช้โทเค็นช่องทางการแจ้งเตือน เราขอแนะนำให้ทำดังนี้

  • ใช้รูปแบบการเข้ารหัสที่ขยายได้ เช่น พารามิเตอร์การค้นหาของ URL ตัวอย่าง: forwardTo=hr&createdBy=mobile

  • อย่าใส่ข้อมูลที่ละเอียดอ่อน เช่น โทเค็น OAuth

• สตริงพร็อพเพอร์ตี้ expiration ที่ตั้งค่าเป็นการประทับเวลา Unix (เป็นมิลลิวินาที) ของวันที่และเวลาที่คุณต้องการให้ Admin SDK API หยุดส่งข้อความสำหรับช่องทางการแจ้งเตือนนี้

  หากแชแนลมีเวลาหมดอายุ แชแนลดังกล่าวจะรวมเป็นค่าของส่วนหัว HTTP X-Goog-Channel-Expiration (ในรูปแบบที่มนุษย์อ่านได้) ในข้อความแจ้งเตือนทุกรายการที่แอปพลิเคชันได้รับสำหรับแชแนลนี้

ดูการตอบกลับ

หากคำขอ watch สร้างช่องทางการแจ้งเตือนสำเร็จ คำขอจะแสดงรหัสสถานะ HTTP 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 สําหรับทรัพยากร Activities ในข้อมูลอ้างอิง API

ซิงค์ข้อความ

หลังจากสร้างช่องทางการแจ้งเตือนเพื่อดูทรัพยากรแล้ว Admin SDK API จะส่งข้อความ sync เพื่อระบุว่าการแจ้งเตือนกำลังจะเริ่มขึ้น ค่าส่วนหัว HTTP ของ X-Goog-Resource-State สำหรับข้อความเหล่านี้คือ sync คุณอาจได้รับข้อความ sync ก่อนที่จะได้รับการตอบกลับของเมธอด watch เนื่องจากเกิดปัญหาเกี่ยวกับเวลาของเครือข่าย

คุณไม่จำเป็นต้องสนใจการแจ้งเตือน sync แต่จะใช้ก็ได้ ตัวอย่างเช่น หากตัดสินใจว่าไม่ต้องการเก็บแชแนลไว้ คุณสามารถใช้ค่า X-Goog-Channel-ID และ X-Goog-Resource-ID ในการเรียกใช้เพื่อหยุดรับการแจ้งเตือน นอกจากนี้ คุณยังใช้การแจ้งเตือน sync เพื่อทำการเริ่มต้นใช้งานบางอย่างเพื่อเตรียมพร้อมสําหรับเหตุการณ์ในภายหลังได้ด้วย

รูปแบบของsyncข้อความที่ Admin SDK API ส่งไปยัง URL ที่คุณรับจะแสดงอยู่ด้านล่าง

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 HTTP เป็น 1 เสมอ การแจ้งเตือนแต่ละรายการที่ตามมาสำหรับแชแนลนี้จะมีหมายเลขข้อความที่มากกว่ารายการก่อนหน้า แม้ว่าหมายเลขข้อความจะไม่เรียงตามลำดับก็ตาม

ต่ออายุช่องทางการแจ้งเตือน

ช่องทางการแจ้งเตือนอาจมีเวลาหมดอายุ โดยค่าจะกำหนดโดยคำขอของคุณหรือขีดจำกัดภายในของ Admin SDK API หรือค่าเริ่มต้น (ระบบจะใช้ค่าที่เข้มงวดกว่า) ระบบจะรวมเวลาหมดอายุของแชแนล (หากมี) ไว้ในการประทับเวลา Unix (เป็นมิลลิวินาที) ในข้อมูลที่เมธอด watch แสดงผล นอกจากนี้ ระบบจะระบุวันที่และเวลาหมดอายุ (ในรูปแบบที่มนุษย์อ่านได้) ไว้ในข้อความแจ้งเตือนทุกข้อความที่แอปพลิเคชันของคุณได้รับสำหรับแชแนลนี้ในส่วนX-Goog-Channel-Expirationส่วนหัว HTTP

ปัจจุบันยังไม่มีวิธีต่ออายุช่องทางการแจ้งเตือนอัตโนมัติ เมื่อช่องใกล้จะหมดอายุ คุณต้องแทนที่ด้วยช่องใหม่โดยเรียกใช้เมธอด watch คุณต้องใช้ค่าที่ไม่ซ้ำกันสำหรับพร็อพเพอร์ตี้ id ของแชแนลใหม่เหมือนเช่นเคย โปรดทราบว่าอาจมีระยะเวลาที่ "ทับซ้อนกัน" เมื่อช่องทางการแจ้งเตือน 2 ช่องทางสำหรับทรัพยากรเดียวกันทำงานอยู่

ตีความรูปแบบข้อความแจ้งเตือน

ข้อความแจ้งเตือนทั้งหมดจะมีชุดส่วนหัว HTTP ที่มีคำนำหน้า 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

หากบริการของคุณใช้ไลบรารีไคลเอ็นต์ API ของ Google และแสดงผลเป็น 500,502, 503 หรือ 504 Admin SDK API จะลองอีกครั้งโดยใช้การถดถอยแบบเลขชี้กำลัง รหัสสถานะการคืนสินค้าอื่นๆ ทั้งหมดจะถือว่าเป็นข้อความล้มเหลว

ทําความเข้าใจเหตุการณ์การแจ้งเตือนของ Admin SDK API

ส่วนนี้จะแสดงรายละเอียดเกี่ยวกับข้อความแจ้งเตือนที่คุณได้รับเมื่อใช้ข้อความ Push กับ Admin SDK API

การแจ้งเตือนแบบพุชของ Reports API มีข้อความ 2 ประเภท ได้แก่ ข้อความซิงค์และการแจ้งเตือนเหตุการณ์ ประเภทข้อความจะระบุไว้ในX-Goog-Resource-Stateส่วนหัว HTTP ค่าที่เป็นไปได้สำหรับการแจ้งเตือนเหตุการณ์จะเหมือนกับของเมธอด activities.list แอปพลิเคชันแต่ละรายการมีเหตุการณ์ที่ไม่ซ้ำกัน ดังนี้

• admin
• calendar
• ไดรฟ์
• groups
• login
• mobile
• saml
• โทเค็น
• user_accounts