Xây dựng một điều kiện khởi động

Tài liệu này giải thích cách tạo một chương trình khởi động cho phép ứng dụng hoặc dịch vụ của bạn thông báo cho Google Workspace Studio khi một sự kiện xảy ra và bắt đầu thực hiện một quy trình. Trong API, các chương trình bắt đầu được gọi là workflowTriggers.

Điều kiện khởi động bắt đầu một quy trình, trong khi bước là một nhiệm vụ duy nhất trong chuỗi nhiệm vụ bao gồm một quy trình. Bằng cách tạo một thành phần khởi động, bạn cho phép người dùng thiết lập các quy trình tự động phản ứng với các sự kiện theo thời gian thực từ ứng dụng hoặc dịch vụ của bạn.

Để tạo một tiện ích bổ sung khởi động, bạn cần khai báo tiện ích bổ sung đó trong tệp kê khai tiện ích bổ sung và triển khai các lệnh gọi lại vòng đời trong Google Apps Script, hoặc kích hoạt tiện ích bổ sung khởi động bằng cách đăng tải tải trọng đến điểm cuối API Google Workspace Studio.

Điều kiện tiên quyết và uỷ quyền OAuth

Để giao tiếp với điểm cuối API Workspace Studio, ứng dụng hoặc dịch vụ của bạn phải xác thực bằng OAuth 2.0. Ứng dụng phải yêu cầu người dùng cấp phạm vi OAuth chuyên dụng sau đây trong quá trình uỷ quyền:

https://www.googleapis.com/auth/workspace.studio.trigger

Phạm vi này cho phép ứng dụng gọi API Workspace Studio và kích hoạt các quy trình mà người dùng đã định cấu hình cho trình khởi tạo đó.

Xem không cần mạng và mã làm mới

Vì các trình khởi chạy thông báo cho Workspace Studio một cách không đồng bộ khi một sự kiện xảy ra trong dịch vụ bên ngoài (có thể là vài giờ, vài ngày hoặc vài tháng sau khi người dùng định cấu hình một quy trình), nên dịch vụ của bạn phải cung cấp mã truy cập OAuth 2.0 hợp lệ khi gọi điểm cuối API.

Mã truy cập do Google cung cấp trong đối tượng sự kiện của tiện ích bổ sung (chẳng hạn như trong quá trình định cấu hình trình khởi chạy hoặc các yêu cầu gọi lại vòng đời) chỉ tồn tại trong thời gian ngắn và chỉ có hiệu lực trong 1 giờ. Điều này không đủ để kích hoạt các sự kiện khởi động không đồng bộ trong tương lai. Để gọi Workspace Studio API theo thời gian, dịch vụ của bạn cần có một mã làm mới ngoại tuyến để tạo mã truy cập mới theo yêu cầu.

Cách bạn xử lý việc uỷ quyền và lấy mã làm mới phụ thuộc vào thời gian chạy của tiện ích bổ sung:

  • Tiện ích bổ sung HTTP (thời gian chạy thay thế): Đối với tiện ích bổ sung HTTP, dịch vụ phụ trợ của bạn phải triển khai một quy trình uỷ quyền OAuth 2.0 riêng biệt, độc lập với quy trình uỷ quyền tiện ích bổ sung tích hợp để yêu cầu quyền truy cập ngoại tuyến (access_type=offline) và nhận mã làm mới.

    Bạn có thể nhắc người dùng cho phép kết nối này bằng cách hiển thị thẻ đăng nhập hoặc uỷ quyền khi người dùng định cấu hình điều kiện khởi động trong Workspace Studio. Để biết thêm thông tin về việc trả lại thẻ uỷ quyền và xử lý quy trình OAuth, hãy xem phần Kết nối tiện ích bổ sung Google Workspace với dịch vụ bên thứ ba (coi Google Workspace là dịch vụ bên thứ ba mà bạn kết nối).

    Dịch vụ phụ trợ của bạn phải lưu trữ mã làm mới một cách an toàn (ví dụ: trong cơ sở dữ liệu của dịch vụ cùng với triggerId) và sử dụng mã này để truy xuất mã truy cập mới bất cứ khi nào một sự kiện xảy ra trước khi gửi yêu cầu đến notifyUri của trình khởi chạy hoặc điểm cuối API triggers.fire.

  • Tiện ích bổ sung Google Apps Script: Các tiện ích bổ sung dựa trên Google Apps Script sử dụng trình kích hoạt theo lịch (dựa trên thời gian) để thăm dò các sự kiện có thể bỏ qua việc triển khai một quy trình OAuth độc lập. Vì các trình kích hoạt theo lịch chạy trực tiếp trong môi trường thời gian chạy Google Apps Script, nên Google Apps Script sẽ tự động quản lý và làm mới mã thông báo OAuth bằng các phạm vi được khai báo trong tệp kê khai.

Xác định trình khởi động trong tệp kê khai

Để xác định một trình khởi chạy, hãy thêm trình khởi chạy đó vào tệp kê khai tiện ích bổ sung (appsscript.json) trong khối addOns.studio.flows.workflowElements. Cấu hình này là bắt buộc đối với cả Apps Script và thời gian chạy HTTP (thời gian chạy thay thế). Định cấu hình phần tử dưới dạng workflowTrigger thay vì workflowAction (được dùng khi xác định một bước). Để biết thêm thông tin, hãy xem phần Cấu trúc tệp kê khai cho tiện ích bổ sung Google Workspace.

Trong khối workflowTrigger, hãy chỉ định:

  • inputs: Các biến mà người dùng định cấu hình trên thẻ cấu hình (chẳng hạn như tên dự án, bộ lọc tài nguyên, v.v.).
  • outputs: Các biến mà chương trình khởi động có thể trả về cho các bước tiếp theo trong quy trình.
  • onConfigFunction: Tên của hàm callback hiển thị giao diện cấu hình người dùng.
  • onManageFunction: Tên của hàm gọi lại do Google gọi để xử lý việc tạo và xoá gói thuê bao dùng thử.

Mẫu mã sau đây cho thấy một ví dụ về định nghĩa tệp kê khai cho một trình khởi chạy sự kiện:

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Trigger App",
      "logoUrl": "https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/start/default/24px.svg",
      "useLocaleFromApp": true
    },
    "studio": {
      "flows": {
        "workflowElements": [
          {
            "id": "triggerDemo",
            "state": "ACTIVE",
            "name": "Event Trigger",
            "description": "Fires when a event occurs in the app.",
            "workflowTrigger": {
              "inputs": [
                {
                  "id": "projectId",
                  "description": "The project identifier to watch.",
                  "cardinality": "SINGLE",
                  "dataType": {
                    "basicType": "STRING"
                  }
                }
              ],
              "outputs": [
                {
                  "id": "eventName",
                  "description": "The name of the triggered event.",
                  "cardinality": "SINGLE",
                  "dataType": {
                    "basicType": "STRING"
                  }
                },
                {
                  "id": "eventMessage",
                  "description": "Detailed event message description.",
                  "cardinality": "SINGLE",
                  "dataType": {
                    "basicType": "STRING"
                  }
                }
              ],
              "onConfigFunction": "onConfigTrigger",
              "onManageFunction": "onManageTrigger"
            }
          }
        ]
      }
    }
  }
}

Xử lý vòng đời của gói thuê bao dành cho người mới bắt đầu

Khi người dùng định cấu hình và bật một quy trình có chứa trình khởi chạy của bạn, hoặc nếu quy trình bị tắt hoặc bị xoá, Google sẽ gọi tiện ích bổ sung của bạn bằng hàm gọi lại onManageFunction được khai báo trong tệp kê khai.

Đối tượng sự kiện trong vòng đời

Hàm callback nhận một WorkflowEventObject chứa ngữ cảnh hành động. Trước tiên, các tính năng này bao gồm:

  • Tạo điều kiện kích hoạt (event.workflow.triggerCreation): Kích hoạt khi quy trình được xuất bản hoặc bật.

    • triggerId: Một chuỗi UUID duy nhất xác định phiên bản đăng ký trình khởi chạy này.

    • notifyUri: URL điểm cuối REST API duy nhất được liên kết với chế độ đăng ký khởi động này (ví dụ: https://workspacestudio.googleapis.com/v1/triggers/YOUR_TRIGGER_ID:fire).

    • inputs: Các thông tin đầu vào về biến do người dùng định cấu hình trên thẻ.

  • Xoá điều kiện kích hoạt (event.workflow.triggerDeletion): Kích hoạt khi điều kiện khởi động bị xoá khỏi flow hoặc khi toàn bộ flow bị vô hiệu hoá hoặc bị xoá.

    • triggerId: Chuỗi UUID duy nhất của phiên bản thuê bao cần dọn dẹp.

Vòng đời của gói thuê bao Alternate Runtimes (HTTP API)

Đối với các tiện ích bổ sung được tạo bằng các thời gian chạy thay thế, thông báo về vòng đời của gói thuê bao sẽ được gửi bằng các yêu cầu HTTP POST đến URL điểm cuối HTTP đã định cấu hình của tiện ích bổ sung, trong đó tên thao tác do hàm callback onManageFunction chỉ định. Tải trọng khớp với biểu diễn JSON của WorkflowEventObject.

Để biết thêm thông tin về các thời gian chạy thay thế, hãy xem bài viết Tạo tiện ích bổ sung Google Workspace bằng cách sử dụng các điểm cuối HTTP.

Triển khai phương thức gọi lại trong vòng đời trong Apps Script

Ví dụ sau đây về Apps Script cho biết cách định cấu hình thẻ giao diện người dùng, xử lý các sự kiện trong vòng đời của gói thuê bao bằng onManageTrigger và gửi yêu cầu khởi động trở lại Google khi một sự kiện xảy ra.

Apps Script

/**
 * Generates and returns the user configuration card to collect inputs.
 */
function onConfigTrigger() {
  const projectInput = CardService.newTextInput()
    .setFieldName("projectId")
    .setTitle("Project ID")
    .setHint("Enter the project identifier to watch");

  const section = CardService.newCardSection()
    .setHeader("Configure Event Trigger")
    .addWidget(projectInput);

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

/**
 * Handles subscription lifecycle events sent from Google Workspace Studio.
 *
 * @param {Object} event The Workspace Studio event object.
 */
function onManageTrigger(event) {
  const triggerCreation = event.workflow.triggerCreation;
  const triggerDeletion = event.workflow.triggerDeletion;

  if (triggerCreation) {
    const triggerId = triggerCreation.triggerId;
    const notifyUri = triggerCreation.notifyUri;
    const inputs = triggerCreation.inputs;

    // Extract input values configured by the user.
    const projectId = inputs["projectId"].stringValues[0];

    // TODO: Save triggerId, notifyUri, and projectId in your database/service.
    // Your backend service listens for events related to 'projectId'
    // and calls notifyUri when those events occur.
    console.log("Trigger subscription created: " + triggerId +
                ", Notify URI: " + notifyUri +
                ", Match Project: " + projectId);

  } else if (triggerDeletion) {
    const triggerId = triggerDeletion.triggerId;

    // TODO: Remove references to triggerId from your database and stop
    // sending future event notifications to the associated notifyUri.
    console.log("Trigger subscription deleted: " + triggerId);
  }
}

/**
 * Mock function showing how your backend service fires the trigger.
 * This logic runs on your service when a watched event occurs.
 *
 * @param {string} notifyUri The stored notifyUri associated with the trigger.
 * @param {string} triggerId The stored triggerId.
 * @param {string} userAccessToken The OAuth 2.0 access token for the user
 *     (obtained using your stored refresh token).
 */
function simulateEventFire(notifyUri, triggerId, userAccessToken) {
  // A unique UUID version 4 is recommended as the requestId for idempotency.
  const requestId = Utilities.getUuid();

  const payload = {
    "name": "triggers/" + triggerId,
    "outputs": {
      "eventName": { "stringValues": ["EventOccurred"] },
      "eventMessage": { "stringValues": ["Hello from the service!"] }
    },
    "requestId": requestId
  };

  const options = {
    "method": "POST",
    "contentType": "application/json",
    "headers": {
      "Authorization": "Bearer " + userAccessToken
    },
    "payload": JSON.stringify(payload),
    "muteHttpExceptions": true
  };

  const response = UrlFetchApp.fetch(notifyUri, options);
  const responseCode = response.getResponseCode();

  if (responseCode === 200) {
    console.log("Trigger successfully fired!");
  } else if (responseCode === 404) {
    // 404 means the trigger registration is invalid or deleted.
    console.log("Trigger not found. Stop sending events for this trigger.");
    // TODO: Clean up the trigger from your backend database.
  } else if (responseCode === 429 || responseCode >= 500) {
    console.log("Temporary error (" + responseCode + "). Retry using exponential backoff.");
  } else {
    console.log("Failed to fire trigger. HTTP Code: " + responseCode + " - " + response.getContentText());
  }
}

Sử dụng Workspace Studio API

Bạn có thể sử dụng Workspace Studio API (workspacestudio.googleapis.com) để thông báo cho Google về các sự kiện bắt đầu bằng cách lập trình.

Các điểm cuối nằm trong đường dẫn cơ sở: https://workspacestudio.googleapis.com/v1.

Thông báo về sự kiện khởi động

Kích hoạt một chương trình khởi động bằng phương thức triggers.fire để bắt đầu thực thi một quy trình.

  • Phương thức HTTP: POST
  • Đường dẫn: /v1/triggers/{triggerId}:fire (trong đó {triggerId} là giá trị nhận dạng duy nhất được truy xuất trong quá trình tạo gói thuê bao kích hoạt)
  • Phạm vi OAuth: https://www.googleapis.com/auth/workspace.studio.trigger

Mã mẫu sau đây cho thấy cách kích hoạt một điều kiện khởi động trong yêu cầu.

Yêu cầu

{
  "name": "triggers/TRIGGER_ID",
  "outputs": {
    "eventName": {
      "stringValues": [
        "EventOccurred"
      ]
    },
    "eventMessage": {
      "stringValues": [
        "Hello from the service!"
      ]
    }
  },
  "log": {
    "textFormatElements": [
      {
        "text": "An event occurred in the app."
      }
    ]
  },
  "requestId": "UNIQUE_REQUEST_ID"
}
  • name (chuỗi, bắt buộc): Tên tài nguyên của điều kiện khởi động, được định dạng là triggers/{triggerId}.
  • outputs (map, optional): Bản đồ của các biến đầu ra khởi động đại diện cho dữ liệu sự kiện. Mỗi giá trị là một đối tượng VariableData hỗ trợ danh sách được nhập (chẳng hạn như stringValues, booleanValues, integerValues).
  • log (đối tượng, không bắt buộc): Một biểu thị bằng mã đánh dấu TextFormat xuất hiện trong nhật ký hoạt động thực thi Workspace Studio.
  • requestId (chuỗi, không bắt buộc): Giá trị nhận dạng duy nhất (nên dùng UUID phiên bản 4) có tối đa 36 ký tự ASCII để đảm bảo tính chất bất biến của API khi thử lại.

Đáp

Phản hồi trả về một đối tượng JSON trống {} khi thành công.

Hạn mức API của Workspace Studio

Lưu lượng truy cập được gửi đến dịch vụ workspacestudio.googleapis.com bị hạn chế để ngăn hệ thống bị quá tải, khuyến khích sử dụng tài nguyên một cách hợp lý và bảo vệ hiệu suất tổng thể của Google Workspace.

Chúng tôi áp dụng các hạn mức sau:

Loại hạn mức Hạn mức
Mỗi phút trên mỗi dự án 1.000 yêu cầu ban đầu
Mỗi phút trên mỗi người dùng 100 yêu cầu ban đầu

Sau đây là các loại hạn mức:

  • Mỗi phút trên mỗi dự án: Giới hạn số lượng sự kiện khởi động tích luỹ được kích hoạt từ dự án Google Cloud của một nhà phát triển duy nhất là 1.000 yêu cầu mỗi phút trên tất cả người dùng đang chạy các sự kiện khởi động của dự án đó.
  • Mỗi phút cho mỗi người dùng: Giới hạn tổng số lần gọi điều kiện khởi động của bất kỳ người dùng cuối nào trong một dự án trên đám mây nhất định ở mức 100 yêu cầu mỗi phút.

Xử lý lỗi hạn mức dựa trên thời gian

Nếu bạn vượt quá hạn mức này, API sẽ trả về mã lỗi HTTP 429 Too Many Requests (hoặc 429 Resource Exhausted) cho biết bạn đã vượt quá hạn mức về tốc độ.

Để giải quyết các lỗi này, mã của bạn phải bắt được ngoại lệ và sử dụng chiến lược thời gian đợi luỹ thừa bị cắt. Thuật toán thời gian đợi luỹ thừa sẽ thử lại các yêu cầu không thành công bằng cách tăng dần độ trễ giữa các lần thử, bao gồm cả độ trễ ngẫu nhiên (tính toán lại độ trễ ngẫu nhiên ở mỗi lần lặp) để ngăn nhiều ứng dụng đồng bộ hoá và thử lại cùng một lúc:

  1. Tạo một yêu cầu đối với Workspace Studio API.
  2. Nếu yêu cầu không thành công và trả về lỗi 429, hãy đợi 1 second + random_number_milliseconds rồi thử lại.
  3. Nếu không thành công, hãy đợi 2 seconds + random_number_milliseconds rồi thử lại.
  4. Nếu không thành công, hãy đợi 4 seconds + random_number_milliseconds rồi thử lại.
  5. Tiếp tục vòng lặp này, tăng gấp đôi độ trễ cho đến khi đạt đến ngưỡng maximum_backoff (thường là 32 hoặc 64 giây).
  6. Sau khi đạt đến thời gian chờ tối đa, hãy thử lại bằng độ trễ không đổi đó cho đến khi đạt đến giới hạn tối đa về số lần thử lại, sau đó dừng và ghi lại lỗi.

Các phương pháp hay nhất

Khi thiết kế và triển khai một chương trình khởi động, hãy cân nhắc các phương pháp hay nhất sau đây:

Phát ra các sự kiện riêng lẻ thay vì danh sách hàng loạt

Thiết kế trình khởi chạy để phát ra một sự kiện riêng lẻ cho mỗi lần xuất hiện riêng biệt (chẳng hạn như một bản ghi duy nhất được cập nhật, một tin nhắn mới được đăng hoặc một việc cần làm được giao) thay vì phát ra một sự kiện duy nhất chứa một lô hoặc danh sách các mục:

  • Tính nhất quán với các trình kích hoạt tích hợp sẵn: Trong Workspace Studio, các trình kích hoạt Google Workspace tích hợp sẵn (chẳng hạn như nhận email trong Gmail hoặc người dùng tham gia một không gian trong Google Chat) sẽ kích hoạt một sự kiện duy nhất. Việc phát ra các sự kiện một mục phù hợp với hành vi này và mang lại trải nghiệm nhất quán, có thể dự đoán cho người dùng trên tất cả các thành phần khởi động.
  • Cấu hình luồng đơn giản hơn: Các bước xuôi dòng trong một luồng thường xử lý từng mục tại một thời điểm. Việc phát sự kiện một mục cho phép người dùng liên kết trực tiếp các biến mà không cần thêm các bước phức tạp để lặp lại mảng hoặc phân tích cú pháp danh sách.
  • Xử lý riêng từng thay đổi theo lô và từng lần thăm dò: Nếu dịch vụ phụ trợ của bạn thăm dò một API bên ngoài và phát hiện nhiều mục đã thay đổi trong một khoảng thời gian thăm dò duy nhất, hãy kích hoạt một sự kiện khởi động riêng cho từng mục thay vì gộp các mục đó vào một sự kiện theo lô.
  • Quản lý hạn mức và tốc độ sự kiện: Vì việc kích hoạt các sự kiện riêng lẻ cho nhiều mục đã thay đổi có thể gây ra một loạt yêu cầu đột ngột, hãy đảm bảo dịch vụ của bạn nằm trong hạn mức Workspace Studio API (chẳng hạn như giới hạn 100 yêu cầu mỗi phút cho mỗi người dùng). Nếu một chu kỳ thăm dò mang lại số lượng lớn các mục (ví dụ: hơn 100 bản ghi đã thay đổi), hãy điều chỉnh tốc độ hoặc điều chỉnh tốc độ gửi sự kiện theo thời gian để tránh lỗi 429 Too Many Requests.

Hành vi cốt lõi và trường hợp đặc biệt

Khi tích hợp các thành phần khởi động, nhà phát triển phải xử lý các hành vi lỗi cụ thể và các tính năng thời gian chạy:

  • Không hỗ trợ chạy thử: Workspace Studio không hỗ trợ chạy thử cho người mới bắt đầu.
  • Tính chất bất biến và ngăn chặn phát lại: Mặc dù không bắt buộc, nhưng bạn nên đưa một requestId duy nhất (chẳng hạn như UUID) vào tải trọng HTTP hoặc Apps Script. Việc cung cấp requestId đảm bảo tính chất luỹ đẳng bằng cách cho phép API phát hiện và bỏ qua các thông báo trùng lặp, ngăn quy trình chạy nhiều lần cho một sự kiện duy nhất.

  • Các quy trình bị vô hiệu hoá và được kích hoạt lại: Khi một quy trình có chứa điều kiện khởi động của bạn bị vô hiệu hoá trong Workspace Studio, Google sẽ gửi một sự kiện trong vòng đời triggerDeletion đến cuộc gọi lại onManageFunction của bạn. Ngoài ra, mọi lệnh gọi đến phương thức FireTrigger được liên kết đều trả về mã lỗi 404 Not Found (Requested entity was not found.). Dịch vụ của bạn phải phản ứng với lỗi 404 bằng cách dừng gửi thông báo về sự kiện trong tương lai cho mã nhận dạng phiên bản khởi động đó.

    Nếu sau này người dùng bật lại quy trình này, Google sẽ bắt đầu một vòng đời thuê bao mới bằng cách gọi lệnh gọi lại onManageFunction của bạn với một sự kiện triggerCreation mới chứa triggerId và notifyUri mới. triggerId trước đó đã ngừng hoạt động vĩnh viễn và không được kích hoạt lại, vì vậy, dịch vụ của bạn không nên thăm dò hoặc kiểm tra xem một phiên bản trình kích hoạt cũ có được bật lại hay không. Để biết thêm thông tin, hãy xem bài viết Xử lý vòng đời của gói thuê bao dùng thử.

  • Xoá gói thuê bao theo cách bất biến: Hàm gọi lại onManageFunction của bạn phải xử lý các yêu cầu xoá gói thuê bao khởi đầu của Google theo cách bất biến. Nếu Google gọi lệnh xoá nhiều lần cho cùng một triggerId (ví dụ: trong quá trình thử lại do mất kết nối tạm thời), thì hàm sẽ trả về thành công.

  • Hạn mức quy trình: Ngoài hạn mức API của Workspace Studio, quy trình của người dùng còn phải tuân theo các chế độ kiểm soát hạn mức nội bộ bổ sung. Các vòng lặp có tần suất cao hoặc số lượng sự kiện quá mức có thể vượt quá ngưỡng an toàn, dẫn đến việc quy trình bị vô hiệu hoá tự động.