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 xác định duy nhất thuộc tính này kênh thông báo mới trong dự án của mình. 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ỳ sản phẩm nào tương tự chuỗi duy nhất. Độ dài tối đa: 64 ký tự.

  Giá trị mã nhận dạng mà bạn đã đặt đượ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 đối với 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 nghe và phản hồi các 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 có thể gửi thông báo đến địa chỉ HTTPS này chỉ khi có cài đặt chứng chỉ SSL hợp lệ trên máy chủ web của bạn. Các 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ó tiêu đề không phù hợp với mục tiêu tên máy 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 chuỗi tuỳ ý để sử dụng làm mã thông báo kênh. Bạn có thể dùng kênh thông báo mã 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 là dành cho kênh mà bạn ứng dụng của bạn đã được tạo—để đảm bảo rằng thông báo hiện không được giả mạo—hoặc định tuyến thư đến đúng đích trong đơn đăng ký của bạn 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 đối với kênh này.

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

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

  • Đừ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) của ngày và giờ mà bạn muốn API SDK dành cho quản trị viên ngừng gửi tin nhắn 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 đó sẽ được thêm vào dưới dạng giá trị của tiêu đề HTTP X-Goog-Channel-Expiration (ở dạng mà con người có thể đọc được định dạng) trong mỗi nội dung thông báo mà lượt đăng ký nhận được cho kênh này.

Xem câu trả lời

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

Nội dung tin nhắn 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ư được minh hoạ 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 những tài sản bạn đã gửi trong yêu cầu, thông tin trả về cũng bao gồm resourceId và resourceUri để xác định tài nguyên đang được xem kênh thông báo.

Bạn có thể chuyển thông tin trả về sang kênh thông báo khác 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 về câu trả lời này, hãy tham khảo 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 gửi một thông báo sync để cho biết rằng thông báo sẽ bắt đầu. HTTP X-Goog-Resource-State giá trị tiêu đề cho các thư này là sync. Do mạng vấn đề về thời gian, có thể nhận được thông báo sync ngay cả trước khi bạn nhận được phản hồi phương thức watch.

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

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

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

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

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

Kênh thông báo có thể có thời gian hết hạn kèm theo một 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ộ nào của API SDK dành cho quản trị viên hoặc mặc định (giá trị càng hạn chế sẽ được sử dụng). Thời hạn của kênh thời gian, 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 do phương thức watch trả về. Ngoài ra, ngày và giờ hết hạn (ở định dạng 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 tự động nào để gia hạn kênh thông báo. Thời gian 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ư 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ể trở thành sự "trùng lặp" đó là khoảng thời gian mà 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 nội dung 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 nội dung thư.

Nội dung thông báo về Hoạt động chứa những 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 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 (API SDK dành cho quản trị viên) thử lại có thời gian đợi luỹ thừa. Mọi mã trạng thái trả về khác đượ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 API SDK dành cho quản trị viên

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 của API Báo cáo chứa 2 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ỉ rõ 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ư giá trị của phương thức activities.list. Mỗi ứng dụng có các sự kiện riêng biệt:

• quản trị viên
• lịch
• lái xe
• nhóm
• login
• thiết bị di động
• saml
• mã thông báo
• user_accounts