ข้อความ Push

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

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

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

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

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

• สตริงพร็อพเพอร์ตี้ address ที่ตั้งค่าเป็น URL ที่รอฟังและตอบสนองต่อการแจ้งเตือนสำหรับช่องทางการแจ้งเตือนนี้ นี่คือ URL เรียกกลับของเว็บฮุคและต้องใช้ 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 สำหรับทรัพยากร Activity ในการอ้างอิง 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

ข้อความที่ซิงค์จะมีค่าส่วนหัว HTTP X-Goog-Message-Number เป็น 1 เสมอ การแจ้งเตือนที่ตามมาสำหรับช่องนี้แต่ละครั้งจะมีหมายเลขข้อความที่มากกว่าจำนวนก่อนหน้า แม้ว่าจำนวนข้อความจะไม่เรียงตามลำดับก็ตาม

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

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

ปัจจุบันยังไม่มีวิธีต่ออายุช่องทางการแจ้งเตือนโดยอัตโนมัติ เมื่อแชแนลใกล้หมดอายุ คุณต้องแทนที่ด้วยแชแนลใหม่โดยเรียกใช้เมธอด 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 ระบบจะลองใหม่ด้วย Exponential Backoff รหัสสถานะการคืนสินค้าอื่นๆ ทั้งหมดจะถือว่าเป็นข้อความล้มเหลว

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

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

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

• admin
• ปฏิทิน
• ไดรฟ์
• กลุ่ม
• login
• อุปกรณ์เคลื่อนที่
• saml
• โทเค็น
• user_accounts