Thông báo đẩy

Thuộc tính bắt buộc

Với mỗi yêu cầu watch, bạn phải cung cấp các trường sau:

• Chuỗi thuộc tính id giúp xác định duy nhất kênh thông báo mới này trong dự án. Bạn nên sử dụng một giá trị nhận dạng duy nhất trên toàn cầu (UUID) hoặc bất kỳ chuỗi duy nhất nào tương tự. Độ dài tối đa: 64 ký tự.

  Giá trị mã nhận dạng mà bạn đặt sẽ được phản hồi trong tiêu đề HTTP X-Goog-Channel-Id của mọi thông báo mà bạn nhận được cho kênh này.

• Một chuỗi thuộc tính type được đặt thành giá trị web_hook.

• Chuỗi thuộc tính address được đặt thành URL theo dõi và phản hồi thông báo cho kênh thông báo này. Đây là URL gọi lại webhook của bạn và phải sử dụng HTTPS.

  Xin lưu ý rằng API SDK dành cho quản trị viên chỉ có thể gửi thông báo đến địa chỉ HTTPS này nếu máy chủ web của bạn đã cài đặt một chứng chỉ SSL hợp lệ. Chứng chỉ không hợp lệ bao gồm:

  • Chứng chỉ tự ký.
  • Chứng chỉ do một nguồn không đáng tin cậy ký.
  • Chứng chỉ đã bị thu hồi.
  • Chứng chỉ có chủ đề không khớp với tên máy chủ mục tiêu.

Thuộc tính tuỳ chọn

Bạn cũng có thể chỉ định các trường không bắt buộc này bằng yêu cầu watch:

• Thuộc tính token chỉ định một giá trị chuỗi tuỳ ý để dùng làm mã thông báo kênh. Bạn có thể sử dụng mã thông báo kênh thông báo cho nhiều mục đích. Ví dụ: bạn có thể sử dụng mã thông báo để xác minh rằng mỗi thông báo đến là dành cho một kênh mà ứng dụng của bạn đã tạo – để đảm bảo thông báo không bị giả mạo – hoặc để định tuyến thông báo đến đúng đích trong ứng dụng dựa trên mục đích của kênh này. Chiều dài tối đa: 256 ký tự.

  Mã thông báo được đưa vào tiêu đề HTTP X-Goog-Channel-Token trong mọi thông báo mà ứng dụng của bạn nhận được cho kênh này.

  Nếu sử dụng mã thông báo kênh thông báo, bạn nên:

  • Sử dụng định dạng mã hoá có thể mở rộng, chẳng hạn như tham số truy vấn URL. Ví dụ: forwardTo=hr&createdBy=mobile

  • Đừng đưa dữ liệu nhạy cảm như mã thông báo OAuth vào.

• Chuỗi thuộc tính expiration được đặt thành dấu thời gian Unix (tính bằng mili giây) của ngày và giờ mà bạn muốn Admin SDK API ngừng gửi thông báo cho kênh thông báo này.

  Nếu một kênh có thời gian hết hạn, thì thời gian này sẽ được đưa vào làm giá trị của tiêu đề HTTP X-Goog-Channel-Expiration (ở định dạng mà con người có thể đọc được) trong mọi thông báo mà ứng dụng của bạn nhận được cho kênh này.

Phản hồi trên đồng hồ

Nếu yêu cầu watch tạo thành công một kênh thông báo, thì yêu cầu đó sẽ trả về mã trạng thái HTTP 200 OK.

Nội dung thông báo của phản hồi xem cung cấp thông tin về kênh thông báo bạn vừa tạo, như trong ví dụ bên dưới.

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

Ngoài các thuộc tính mà bạn đã gửi trong yêu cầu, thông tin được trả về cũng bao gồm resourceId và resourceUri để xác định tài nguyên đang được xem trên kênh thông báo này.

Bạn có thể truyền thông tin được trả về cho các thao tác khác trên kênh thông báo, chẳng hạn như khi bạn muốn ngừng nhận thông báo.

Để biết thêm thông tin chi tiết về phản hồi, hãy tham khảo phương thức watch cho tài nguyên Hoạt động trong Tài liệu tham khảo API.

Đồng bộ hoá thư

Sau khi tạo một kênh thông báo để xem tài nguyên, API SDK dành cho quản trị viên sẽ gửi thông báo sync để cho biết rằng thông báo đang bắt đầu. Giá trị tiêu đề HTTP X-Goog-Resource-State cho các thư này là sync. Do các vấn đề về thời gian mạng, bạn có thể nhận được thông báo sync ngay cả trước khi nhận được phản hồi phương thức watch.

Bạn có thể yên tâm bỏ qua thông báo sync, nhưng cũng có thể sử dụng thông báo này. Ví dụ: nếu quyết định không muốn giữ lại kênh, bạn có thể sử dụng các giá trị X-Goog-Channel-ID và X-Goog-Resource-ID trong lệnh gọi để dừng nhận thông báo. Bạn cũng có thể sử dụng thông báo sync để khởi chạy một số hoạt động chuẩn bị cho các sự kiện sau.

Dưới đây là định dạng của các thông báo sync mà API SDK dành cho quản trị viên gửi tới URL nhận của bạn.

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

Thông báo đồng bộ hoá luôn có giá trị tiêu đề HTTP X-Goog-Message-Number là 1. Mỗi thông báo tiếp theo cho kênh này có số thông báo lớn hơn số thông báo trước đó, mặc dù các số thông báo sẽ không theo thứ tự.

Gia hạn kênh thông báo

Một kênh thông báo có thể có thời gian hết hạn, với giá trị được xác định theo yêu cầu của bạn hoặc theo bất kỳ giới hạn nội bộ hoặc giá trị mặc định nào của API SDK quản trị (giá trị hạn chế hơn sẽ được sử dụng). Thời gian hết hạn của kênh (nếu có) được đưa vào dưới dạng dấu thời gian Unix (tính bằng mili giây) trong thông tin do phương thức watch trả về. Ngoài ra, ngày và giờ hết hạn cũng được đưa vào (ở định dạng mà con người có thể đọc được) trong mọi thông báo mà ứng dụng của bạn nhận được cho kênh này trong tiêu đề HTTP X-Goog-Channel-Expiration.

Hiện tại, không có cách nào tự động để gia hạn kênh thông báo. Khi một kênh sắp hết hạn, bạn phải thay thế bằng một kênh mới bằng cách gọi phương thức watch. Như mọi khi, bạn phải sử dụng một giá trị duy nhất cho thuộc tính id của kênh mới. Xin lưu ý rằng có thể có một khoảng thời gian "trùng lặp" khi hai kênh thông báo cho cùng một tài nguyên đang hoạt động.

Diễn giải định dạng thông báo

Tất cả thông báo đều bao gồm một tập hợp các tiêu đề HTTP có tiền tố X-Goog-. Một số loại thông báo cũng có thể bao gồm cả nội dung tin nhắn.

Thông báo cho Hoạt động chứa những thông tin sau trong phần nội dung yêu cầu:

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

Trả lời các thông báo

Để cho biết trạng thái thành công, bạn có thể trả về bất kỳ mã trạng thái nào sau đây: 200, 201, 202, 204 hoặc 102.

Nếu dịch vụ của bạn sử dụng thư viện ứng dụng API của Google và trả về 500,502, 503 hoặc 504, thì API SDK quản trị sẽ thử lại bằng thời gian đợi luỹ thừa. Mọi mã trạng thái trả về khác đều được coi là lỗi thông báo.

Tìm hiểu về các sự kiện thông báo của Admin SDK API

Phần này cung cấp thông tin chi tiết về các nội dung thông báo mà bạn có thể nhận được khi sử dụng thông báo đẩy với API SDK dành cho quản trị viên.

Thông báo đẩy API Báo cáo chứa hai loại thông báo: thông báo đồng bộ hoá và thông báo sự kiện. Loại thông báo được chỉ định trong tiêu đề HTTP X-Goog-Resource-State. Các giá trị có thể có cho thông báo sự kiện giống với phương thức activities.list. Mỗi ứng dụng có các sự kiện riêng biệt:

• admin
• lịch
• ổ đĩa
• nhóm
• login
• thiết bị di động
• saml
• mã thông báo
• user_accounts