Thông báo đẩy

Tài liệu này mô tả cách sử dụng thông báo đẩy để thông báo cho ứng dụng của bạn khi một tài nguyên thay đổi.

Tổng quan

API SDK dành cho quản trị viên cung cấp thông báo đẩy cho phép bạn giám sát những thay đổi về tài nguyên. Bạn có thể sử dụng tính năng này để cải thiện hiệu suất của ứng dụng của bạn. Tính năng này giúp bạn loại bỏ chi phí mạng và tính toán bổ sung liên quan đến việc thăm dò ý kiến các tài nguyên để xác định xem các tài nguyên đó có thay đổi hay không. Bất cứ khi nào một tài nguyên được theo dõi thay đổi, API SDK dành cho quản trị viên sẽ thông báo cho ứng dụng của bạn.

Để sử dụng thông báo đẩy, bạn phải làm hai việc:

  • Thiết lập URL nhận hoặc trình nhận lệnh gọi lại "webhook".

    Đây là một máy chủ HTTPS xử lý thông báo API được kích hoạt khi một tài nguyên thay đổi.

  • Thiết lập (kênh thông báo) cho mỗi điểm cuối tài nguyên mà bạn muốn đồng hồ.

    Kênh chỉ định thông tin định tuyến cho thông báo. Trong quá trình thiết lập kênh, bạn phải xác định URL cụ thể mà bạn muốn nhận thông báo. Bất cứ khi nào tài nguyên của một kênh thay đổi, API SDK quản trị sẽ gửi một thông báo dưới dạng yêu cầu POST đến URL đó.

Hiện tại, API SDK dành cho quản trị viên hỗ trợ thông báo về những thay đổi đối với tài nguyên về Hoạt động.

Tạo kênh thông báo

Để yêu cầu thông báo đẩy, bạn phải thiết lập một kênh thông báo cho từng tài nguyên mà bạn muốn theo dõi. Sau khi bạn thiết lập các kênh thông báo, API SDK quản trị sẽ thông báo cho ứng dụng của bạn khi có bất kỳ tài nguyên nào được theo dõi thay đổi.

Đưa ra yêu cầu xem

Mỗi tài nguyên API SDK dành cho quản trị viên có thể xem được đều có một phương thức watch liên kết tại một URI có dạng như sau:

https://www.googleapis.com/API_NAME/API_VERSION/RESOURCE_PATH/watch

Để thiết lập kênh thông báo cho thông báo về các thay đổi đối với tài nguyên cụ thể, hãy gửi yêu cầu POST đến Phương thức watch cho tài nguyên.

Mỗi kênh thông báo được liên kết với cả một người dùng và người dùng cụ thể một tài nguyên (hoặc một nhóm tài nguyên) cụ thể. Yêu cầu watch sẽ không thành công trừ phi người dùng hiện tại hoặc tài khoản dịch vụ sở hữu hoặc có quyền truy cập vào tài nguyên này.

Ví dụ

Tất cả yêu cầu xem đối với tài nguyên Hoạt động đều có dạng chung:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/userKey or all/applications/applicationName/watch
Authorization: Bearer auth_token_for_current_user
Content-Type: application/json

{
  "id": "01234567-89ab-cdef-0123456789ab", // Your channel ID.
  "type": "web_hook",
  "address": "https://mydomain.com/notifications", // Your receiving URL.
  ...
  "token": "target=myApp-myFilesChannelDest", // (Optional) Your channel token.
  "payload": true, // (Optional) Whether to include the payload (message body) in notifications.
  "expiration": 3600 // (Optional) Your requested channel expiration time.
}

Bạn có thể sử dụng các tham số userKey, applicationName, eventName và filters để chỉ nhận thông báo về một số sự kiện, người dùng hoặc ứng dụng cụ thể.

Lưu ý: Để rõ ràng, các ví dụ sau đây sẽ bỏ qua phần nội dung yêu cầu.

Theo dõi tất cả hoạt động của quản trị viên:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch

Chú ý tất cả các hoạt động liên quan đến Tài liệu:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch

Theo dõi hoạt động quản trị của một người dùng cụ thể:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/liz@example.com/applications/admin/watch

Theo dõi một sự kiện cụ thể, chẳng hạn như thay đổi mật khẩu của người dùng:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin/watch?eventName=CHANGE_PASSWORD

Chú ý những thay đổi đối với một tài liệu cụ thể:

POST https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/docs/watch?eventName=EDIT&filters==doc_id=123456abcdef

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 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 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 quản trị chỉ có thể gửi thông báo đến địa chỉ HTTPS này nếu có 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.
    • 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 để 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. 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 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 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 đó 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.

Để biết thêm thông tin chi tiết về yêu cầu này, 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.

Xem câu trả lời

Nếu yêu cầu watch tạo thành công 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 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ể 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 kênh thông báo để theo dõi một 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. 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ể 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 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 để 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 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.

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ố 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

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 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 (ở định dạng mà con người có thể đọc được) được đưa vào 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. 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ư 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.

Nhận thông báo

Bất cứ khi nào tài nguyên được theo dõi thay đổi, ứng dụng của bạn sẽ nhận được một nội dung thông báo mô tả thay đổi. API SDK dành cho quản trị viên gửi các thông báo này dưới dạng yêu cầu POST HTTPS đến URL mà bạn chỉ định làm thuộc tính address cho kênh thông báo này.

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ông báo.

Tiêu đề

Thông báo do API SDK quản trị đăng lên URL nhận của bạn bao gồm các tiêu đề HTTP sau:

Tiêu đề Mô tả
Luôn có sẵn
X-Goog-Channel-ID UUID hoặc chuỗi duy nhất khác mà bạn đã cung cấp để xác định kênh thông báo này.
X-Goog-Message-Number Số nguyên xác định thông báo này cho kênh thông báo này. Giá trị luôn là 1 đối với thông báo sync. Số tin nhắn tăng lên cho mỗi tin nhắn tiếp theo trên kênh, nhưng các số này không theo thứ tự.
X-Goog-Resource-ID Giá trị mờ xác định tài nguyên được theo dõi. Mã nhận dạng này ổn định trên các phiên bản API.
X-Goog-Resource-State Trạng thái tài nguyên mới đã kích hoạt thông báo. Các giá trị có thể có: sync hoặc tên sự kiện.
X-Goog-Resource-URI Giá trị nhận dạng dành riêng cho phiên bản API cho tài nguyên được theo dõi.
Thỉnh thoảng xuất hiện
X-Goog-Channel-Expiration Ngày và giờ hết hạn kênh thông báo, được thể hiện bằng ở định dạng mà con người có thể đọc được. Chỉ xuất hiện nếu được xác định.
X-Goog-Channel-Token Mã thông báo kênh thông báo do ứng dụng của bạn đặt và bạn có thể dùng để xác minh nguồn thông báo. Chỉ hiển thị nếu xác định.

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:

Thuộc tính Mô tả
kind Nhận dạng tài nguyên này là tài nguyên Hoạt động. Giá trị: chuỗi cố định "admin#reports#activity".
id Giá trị nhận dạng duy nhất của bản ghi hoạt động.
id.time Thời gian xảy ra hoạt động. Giá trị nằm trong Định dạng ngày và giờ ISO 8601. Thời gian là ngày đầy đủ cùng với giờ, phút và giây ở dạng YYYY-MM-DDThh:mm:ssTZD. Ví dụ: 2010-04-05T17:30:04+01:00.
id.uniqueQualifier Bộ hạn định duy nhất nếu nhiều sự kiện có cùng thời gian.
id.applicationName Tên ứng dụng chứa sự kiện. Có thể là các giá trị sau:
id.customerId Giá trị nhận dạng duy nhất của một tài khoản Google Workspace.
actor Người dùng thực hiện hành động.
actor.callerType Loại tác giả đã thực hiện hoạt động được liệt kê trong báo cáo. Trong phiên bản API này, callerType là yêu cầu thực thể USER hoặc OAuth 2LO đã thực hiện hành động được liệt kê trong báo cáo.
actor.email Địa chỉ email chính của người dùng có các hoạt động đang được báo cáo.
actor.profileId Mã hồ sơ Google Workspace duy nhất của người dùng.
ownerDomain Miền của Bảng điều khiển dành cho quản trị viên hoặc chủ sở hữu tài liệu của ứng dụng Tài liệu. Đây là miền chịu ảnh hưởng của sự kiện trong báo cáo.
ipAddress Địa chỉ IP của người dùng thực hiện hành động. Đây là địa chỉ Giao thức Internet (IP) của người dùng khi đăng nhập vào Google Workspace. Địa chỉ này có thể phản ánh hoặc không phản ánh vị trí thực tế của người dùng. Ví dụ: Địa chỉ IP có thể là địa chỉ máy chủ proxy của người dùng hoặc địa chỉ mạng riêng ảo (VPN). API này hỗ trợ IPv4 và IPv6.
events[] Sự kiện hoạt động trong báo cáo.
events[].type Loại sự kiện. Dịch vụ hoặc tính năng của Google Workspace mà quản trị viên thay đổi được xác định trong tài sản type. Tài sản này xác định một sự kiện bằng tài sản eventName.
events[].name Tên sự kiện. Đây là tên cụ thể của hoạt động do API báo cáo. Mỗi eventName đều liên quan đến một dịch vụ hoặc tính năng cụ thể của Google Workspace mà API sắp xếp thành các loại sự kiện.
Đối với tham số yêu cầu eventName nói chung:
  • Nếu không cung cấp eventName, báo cáo sẽ trả về mọi phiên bản có thể có của eventName.
  • Khi bạn yêu cầu một eventName, phản hồi của API sẽ trả về tất cả hoạt động có chứa eventName đó. Các hoạt động được trả về có thể có các thuộc tính eventName khác ngoài thuộc tính được yêu cầu.
events[].parameters[] Các cặp giá trị thông số cho nhiều ứng dụng.
events[].parameters[].name Tên của thông số.
events[].parameters[].value Giá trị chuỗi của thông số.
events[].parameters[].intValue Giá trị số nguyên của thông số.
events[].parameters[].boolValue Giá trị boolean của thông số.

Ví dụ

Nội dung thông báo cho các sự kiện tài nguyên Hoạt động có dạng chung:

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

Ví dụ về sự kiện hoạt động quản trị:

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 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 đề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 API SDK dành cho quản trị viên

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

Dừng thông báo

Thuộc tính expiration kiểm soát thời điểm thông báo tự động dừng. Bạn có thể chọn ngừng nhận thông báo cho một kênh cụ thể trước khi kênh đó hết hạn bằng cách gọi phương thức stop tại URI sau:

https://www.googleapis.com/admin/reports_v1/channels/stop

Phương thức này yêu cầu bạn cung cấp ít nhất thuộc tính id và resourceId của kênh, như minh hoạ trong ví dụ bên dưới. Xin lưu ý rằng nếu API SDK dành cho quản trị viên có một số loại các tài nguyên có watch phương thức, thì chỉ có một phương thức stop.

Chỉ những người dùng có quyền phù hợp mới có thể dừng kênh. Cụ thể:

  • Nếu kênh được tạo bởi một tài khoản người dùng thông thường thì chỉ có cùng một tài khoản người dùng từ cùng một ứng dụng khách (như được xác định bằng ID ứng dụng khách OAuth 2.0 từ mã auth) đã tạo kênh có thể khiến kênh đó ngừng hoạt động.
  • Nếu kênh được tạo bằng một tài khoản dịch vụ, thì bất kỳ người dùng nào trên kênh đó khách hàng có thể dừng kênh.

Mã mẫu sau đây cho biết cách ngừng nhận thông báo:

POST https://www.googleapis.com/admin/reports_v1/channels/stop
  
Authorization: Bearer CURRENT_USER_AUTH_TOKEN
Content-Type: application/json

{
  "id": "4ba78bf0-6a47-11e2-bcfd-0800200c9a66",
  "resourceId": "ret08u3rv24htgh289g"
}