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:

• Một chuỗi thuộc tính id nhận dạng duy nhất kênh thông báo mới này trong dự án của bạn. Bạn nên 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 bạn đặt sẽ được lặp lạ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.

• 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 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 có một chứng chỉ SSL hợp lệ được cài đặt trên máy chủ web của bạn. 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.
  • Các chứng chỉ có tiêu đề không khớp với tên máy chủ đích.

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ể dùng mã thông báo kênh 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 tin nhắn đến đều dành cho một kênh mà ứng dụng của bạn đã tạo – để đảm bảo rằng thông báo không bị giả mạo – hoặc để chuyển thông báo đến đúng đích đến trong ứng dụng dựa trên mục đích của kênh này. Độ dài tối đa: 256 ký tự.

  Mã thông báo này đượ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, 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

  • Không gửi dữ liệu nhạy cảm như mã thông báo OAuth.

• Chuỗi thuộc tính expiration được đặt thành Dấu thời gian Unix (tính bằng mili giây) tính từ ngày và giờ mà bạn muốn API SDK dành cho quản trị viên 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ì kênh đó sẽ được đưa vào dưới dạng 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.

Xem phản hồi

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ột mã trạng thái HTTP 200 OK.

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

{
  "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 theo 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ề đến 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 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 của những thông báo 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 của phương thức watch.

Bạn có thể bỏ qua thông báo sync, nhưng bạn 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 nữa, 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 để ngừng nhận thông báo. Bạn cũng có thể sử dụng thông báo sync để thực hiện một số hoạt động khởi tạo nhằm chuẩn bị cho các sự kiện sau này.

Dưới đây là định dạng của thông báo sync mà API SDK dành cho quản trị viên gửi tới URL nhậ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 của kênh này sẽ có một số thông báo lớn hơn số thông báo trước đó, mặc dù số thông báo sẽ không theo tuần tự.

Gia hạn các 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 giới hạn nội bộ hoặc giá trị mặc định của API SDK dành cho quản trị viên (sử dụng giá trị có tính hạn chế cao hơn). Thời gian hết hạn của kênh (nếu có) sẽ đượ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 mà phương thức watch trả về. Ngoài ra, ngày và giờ hết hạn sẽ được đưa vào (ở định dạng mà con người có thể đọc được) trong mọi nội dung 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 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ế kênh đó bằng một kênh mới bằng cách gọi phương thức watch. Như thường lệ, 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ó khoảng thời gian "trùng lặp" khi 2 kênh thông báo cho cùng một tài nguyên hoạt động.

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

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

Thông báo thông báo cho Activity (Hoạt động) chứa các thông tin sau trong 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 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 dùng thư viện ứng dụng API của Google và trả về 500,502, 503 hoặc 504, thì API SDK dành cho quản trị viên sẽ thử lại theo thời gian đợi luỹ thừa. Tất cả các mã trạng thái trả lại hàng khác được coi là một lỗi thông báo.

Tìm hiểu về các sự kiện thông báo của API SDK dành cho quản trị viên

Phần này cung cấp thông tin chi tiết về những thông báo mà bạn có thể nhận được khi sử dụng thông báo đẩy thông qua 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ộ hóa và thông báo sự kiện. Loại thông báo này đượ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 như cho phương thức activities.list. Mỗi ứng dụng có các sự kiện riêng biệt:

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