สร้างเงื่อนไขเริ่มต้น

เอกสารนี้อธิบายวิธีสร้างโปรเจ็กต์เริ่มต้นที่ช่วยให้แอปหรือบริการของคุณ แจ้งเตือน Google Workspace Studio เมื่อเกิดเหตุการณ์และเริ่ม การดำเนินการโฟลว์ ใน API เงื่อนไขเริ่มต้นจะเรียกว่า workflowTriggers

ตัวเริ่มต้นจะเริ่มโฟลว์ ส่วนขั้นตอนคืองานเดียวในลำดับ ของงานที่ประกอบเป็นโฟลว์ การสร้างสตาร์ทเตอร์ช่วยให้ผู้ใช้ตั้งค่าโฟลว์อัตโนมัติที่ตอบสนองต่อเหตุการณ์แบบเรียลไทม์จากแอปหรือบริการของคุณได้

การสร้างตัวเริ่มต้นเกี่ยวข้องกับการประกาศตัวเริ่มต้นในไฟล์ Manifest ของส่วนเสริมและการใช้โค้ดเรียกกลับของวงจร ใน Google Apps Script หรือการเรียกใช้ตัวเริ่มต้นโดยการโพสต์เพย์โหลดไปยัง ปลายทาง Google Workspace Studio API

ข้อกำหนดเบื้องต้น

• บัญชี Google ที่มีสิทธิ์เข้าถึง Workspace Studio
• โปรเจ็กต์ Google Cloud

เปิดใช้ API

เปิดใช้ Google Workspace Studio API ในโปรเจ็กต์ Google Cloud โดยทำดังนี้

เปิดใช้ API

เปลี่ยนไปใช้โปรเจ็กต์ที่อยู่ในระบบคลาวด์มาตรฐานของ Google (Google Apps Script เท่านั้น)

โดยค่าเริ่มต้น โปรเจ็กต์ Apps Script จะใช้โปรเจ็กต์ที่อยู่ในระบบคลาวด์เริ่มต้น ที่ไม่รองรับการเปิดใช้ API หรือการกำหนดค่าหน้าจอขอความยินยอม OAuth หากสร้างโปรเจ็กต์เริ่มต้นด้วย Apps Script คุณต้องเปลี่ยนไปใช้โปรเจ็กต์ Google Cloud มาตรฐานโดยทำดังนี้

1. ในเครื่องมือแก้ไขสคริปต์ของ Apps Script ให้คลิกการตั้งค่าโปรเจ็กต์
2. ในส่วนโปรเจ็กต์ Google Cloud Platform (GCP) ให้คลิกเปลี่ยนโปรเจ็กต์
3. ป้อนหมายเลขโปรเจ็กต์ที่อยู่ในระบบคลาวด์มาตรฐาน แล้วคลิกตั้งค่าโปรเจ็กต์
4. หลังจากเปลี่ยนโปรเจ็กต์แล้ว ให้ให้สิทธิ์สคริปต์อีกครั้งโดยการเรียกใช้ฟังก์ชันใดก็ได้ ในตัวแก้ไขและให้สิทธิ์ที่ขอ

ดูข้อมูลเพิ่มเติมได้ที่ เปลี่ยนไปใช้โปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google Cloud มาตรฐาน

กำหนดค่าหน้าจอขอความยินยอม OAuth

หากต้องการสื่อสารกับปลายทาง API ของ Workspace Studio แอปหรือ บริการของคุณต้องตรวจสอบสิทธิ์โดยใช้ OAuth 2.0 กำหนดค่าหน้าจอขอความยินยอม OAuth ของโปรเจ็กต์ และเพิ่มขอบเขต OAuth เฉพาะต่อไปนี้

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

ขอบเขตนี้ให้สิทธิ์แอปในการเรียกใช้ Workspace Studio API และ เริ่มทำงานโฟลว์ที่ผู้ใช้กำหนดค่าไว้สำหรับ เงื่อนไขเริ่มต้นนั้น

ดูข้อมูลเพิ่มเติมได้ที่หัวข้อกำหนดค่าหน้าจอขอความยินยอม OAuth และเลือกขอบเขต

โทเค็นการเข้าถึงแบบออฟไลน์และโทเค็นการรีเฟรช

เนื่องจากตัวเริ่มต้นจะแจ้ง Workspace Studio แบบไม่พร้อมกันเมื่อมีเหตุการณ์เกิดขึ้นในบริการภายนอก ซึ่งอาจเกิดขึ้นหลายชั่วโมง หลายวัน หรือหลายเดือนหลังจากที่ผู้ใช้กำหนดค่าโฟลว์แล้ว บริการของคุณจึงต้องระบุโทเค็นเพื่อการเข้าถึง OAuth 2.0 ที่ถูกต้องเมื่อเรียกใช้ปลายทาง API

โทเค็นเพื่อการเข้าถึงที่ Google ระบุไว้ในออบเจ็กต์เหตุการณ์ของส่วนเสริม (เช่น ระหว่างการกำหนดค่าเริ่มต้นหรือคำขอการเรียกกลับวงจร) จะมีอายุสั้น และใช้ได้เพียง 1 ชั่วโมงเท่านั้น ซึ่งไม่เพียงพอสำหรับการทริกเกอร์เหตุการณ์เริ่มต้น แบบไม่พร้อมกันในอนาคต หากต้องการเรียกใช้ Workspace Studio API เมื่อเวลาผ่านไป บริการของคุณจะต้องมีโทเค็นการรีเฟรชแบบออฟไลน์เพื่อสร้างโทเค็นเพื่อการเข้าถึงใหม่ตามต้องการ

วิธีจัดการการให้สิทธิ์และรับโทเค็นการรีเฟรชจะขึ้นอยู่กับ รันไทม์ของส่วนเสริม

• ส่วนเสริม HTTP (รันไทม์สำรอง): สำหรับส่วนเสริม HTTP บริการแบ็กเอนด์ของคุณต้องใช้โฟลว์การให้สิทธิ์ OAuth 2.0 แยกต่างหาก ซึ่งไม่ขึ้นอยู่กับการให้สิทธิ์ส่วนเสริมในตัว เพื่อขอสิทธิ์เข้าถึงแบบออฟไลน์ (access_type=offline) และรับโทเค็นการรีเฟรช

  คุณสามารถแจ้งให้ผู้ใช้ให้สิทธิ์การเชื่อมต่อนี้โดยแสดงการ์ดลงชื่อเข้าใช้หรือ การให้สิทธิ์เมื่อผู้ใช้กำหนดค่า Starter ใน Workspace Studio ดูข้อมูลเพิ่มเติมเกี่ยวกับการส่งคืน การ์ดการให้สิทธิ์และการจัดการโฟลว์ OAuth ได้ที่เชื่อมต่อส่วนเสริม ของ Google Workspace กับบริการ ของบุคคลที่สาม (ถือว่า Google Workspace เป็นบริการของบุคคลที่สามที่คุณเชื่อมต่อ)

  บริการแบ็กเอนด์ต้องจัดเก็บโทเค็นการรีเฟรชอย่างปลอดภัย (เช่น ในฐานข้อมูลของบริการควบคู่กับ triggerId) และใช้เพื่อดึงโทเค็นเพื่อการเข้าถึงใหม่ทุกครั้งที่เกิดเหตุการณ์ก่อนส่งคำขอไปยัง notifyUri ของผู้เริ่มต้นหรือปลายทาง API ของ triggers.fire

• ส่วนเสริม Google Apps Script: ส่วนเสริมที่ใช้ Google Apps Script ซึ่งใช้ทริกเกอร์ที่กำหนดเวลาไว้ (อิงตามเวลา) เพื่อสำรวจหาเหตุการณ์สามารถข้ามการติดตั้งใช้งาน โฟลว์ OAuth ที่เป็นอิสระได้ เนื่องจากทริกเกอร์ที่กำหนดเวลาจะทำงานโดยตรงภายในสภาพแวดล้อมรันไทม์ของ Google Apps Script ดังนั้น Google Apps Script จะจัดการและรีเฟรชโทเค็น OAuth โดยอัตโนมัติโดยใช้ขอบเขตที่ประกาศไว้ในไฟล์ Manifest คุณสามารถดึงโทเค็นเพื่อการเข้าถึง OAuth ได้โดยใช้ ScriptApp.getOAuthToken()

  หมายเหตุ: เมื่อทดสอบโปรแกรมเริ่มต้นด้วยเว็บแอป Apps Script ให้กำหนดค่า "executeAs": "USER_ACCESSING" ในไฟล์ Manifest หากติดตั้งใช้งานเป็น "USER_DEPLOYING" ("ฉัน") รูปแบบการรักษาความปลอดภัยของ Google จะทิ้งขอบเขตที่ไม่ใช่หลัก เช่น workspace.studio.trigger จาก ScriptApp.getOAuthToken() ในสภาพแวดล้อมการใช้งานจริงที่ผู้ใช้ทุกคนเข้าถึงได้ ให้ใช้บัญชีบริการหรือโทเค็นการรีเฟรช OAuth 2.0

กำหนดตัวเริ่มต้นในไฟล์ Manifest

หากต้องการกำหนดเงื่อนไขเริ่มต้น ให้เพิ่มลงในไฟล์ Manifest ของส่วนเสริม (appsscript.json) ภายในบล็อก addOns.studio.flows.workflowElements การกำหนดค่านี้จำเป็นสำหรับทั้ง Apps Script และรันไทม์ HTTP (รันไทม์สำรอง) กำหนดค่าองค์ประกอบเป็น workflowTrigger แทน workflowAction (ซึ่งใช้เมื่อกำหนดขั้นตอน) ดูข้อมูลเพิ่มเติมได้ที่โครงสร้างไฟล์ Manifest สำหรับส่วนเสริม Google Workspace

ภายในบล็อก workflowTrigger ให้ระบุข้อมูลต่อไปนี้

• inputs: ตัวแปรที่ผู้ใช้กําหนดค่าในการ์ดการกําหนดค่า (เช่น ชื่อโปรเจ็กต์ ตัวกรองทรัพยากร ฯลฯ)
• outputs: ตัวแปรที่ขั้นตอนเริ่มต้นส่งคืนไปยังขั้นตอนปลายทางในโฟลว์
• onConfigFunction: ชื่อของฟังก์ชัน Callback ที่แสดงอินเทอร์เฟซการกำหนดค่าของผู้ใช้
• onManageFunction: ชื่อของฟังก์ชัน Callback ที่ Google เรียกใช้เพื่อ จัดการการสร้างและการลบการสมัครใช้บริการเริ่มต้น

ตัวอย่างโค้ดต่อไปนี้แสดงตัวอย่างคำจำกัดความของไฟล์ Manifest สำหรับตัวเริ่มเหตุการณ์

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/workspace.studio.trigger"
  ],
  "urlFetchWhitelist": [
    "https://workspacestudio.googleapis.com/"
  ],
  "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"
            }
          }
        ]
      }
    }
  }
}

จัดการวงจรการสมัครใช้บริการเริ่มต้น

เมื่อผู้ใช้กำหนดค่าและเปิดใช้โฟลว์ ที่มีตัวเริ่มต้นของคุณ หรือหากโฟลว์ ถูกปิดใช้หรือลบ Google จะเรียกใช้ส่วนเสริมของคุณโดยใช้ฟังก์ชัน onManageFunction Callback ที่ประกาศไว้ในไฟล์ Manifest

ออบเจ็กต์เหตุการณ์ในวงจรลูกค้า

ฟังก์ชัน Callback จะได้รับ WorkflowEventObject ที่มีบริบทการดำเนินการ โดยในระยะแรก จะมีฟีเจอร์ต่อไปนี้

• การสร้างทริกเกอร์ (event.workflow.triggerCreation): เริ่มทำงานเมื่อเผยแพร่หรือเปิดใช้โฟลว์

  • triggerId: สตริง UUID ที่ไม่ซ้ำกันซึ่งระบุอินสแตนซ์การลงทะเบียนเริ่มต้นนี้

  • notifyUri: URL ของปลายทาง REST API ที่ไม่ซ้ำกันซึ่งเชื่อมโยงกับการลงทะเบียนเริ่มต้นนี้ (เช่น https://workspacestudio.googleapis.com/v1/triggers/YOUR_TRIGGER_ID:fire) หากไม่มี notifyUri ในเพย์โหลดของเหตุการณ์ ให้สร้าง URL ของปลายทางโดยตรงโดยใช้ triggerId: https://workspacestudio.googleapis.com/v1/triggers/{triggerId}:fire

  • inputs: ข้อมูลตัวแปรที่ผู้ใช้กำหนดค่าจากการ์ด

• การลบทริกเกอร์ (event.workflow.triggerDeletion): เรียกใช้เมื่อนำ เงื่อนไขเริ่มต้นออกจากโฟลว์ หรือ เมื่อปิดใช้หรือ ลบโฟลว์ทั้งหมด

  • triggerId: สตริง UUID ที่ไม่ซ้ำกันของอินสแตนซ์การสมัครใช้บริการที่จะ ล้างข้อมูล

วงจรการสมัครใช้บริการของ Alternate Runtimes (HTTP API)

สำหรับส่วนเสริมที่สร้างขึ้นโดยใช้รันไทม์อื่น ระบบจะส่งการแจ้งเตือนวงจรการสมัครใช้บริการ โดยใช้คำขอ HTTP POST ไปยัง URL ปลายทาง HTTP ที่กำหนดค่าไว้ของส่วนเสริม พร้อมชื่อการดำเนินการที่ระบุโดยฟังก์ชัน Callback onManageFunction เพย์โหลดตรงกับ การแสดงผลในรูปแบบ JSON ของ WorkflowEventObject

ดูข้อมูลเพิ่มเติมเกี่ยวกับรันไทม์สำรองได้ที่สร้างส่วนเสริมของ Google Workspace โดยใช้ ปลายทาง HTTP

ใช้ Lifecycle Callback ใน Apps Script

ตัวอย่าง Apps Script ต่อไปนี้แสดงวิธีกำหนดค่าการ์ดอินเทอร์เฟซผู้ใช้ จัดการเหตุการณ์วงจรการสมัครใช้บริการโดยใช้ onManageTrigger และเรียกใช้ คำขอเริ่มต้นกลับไปยัง Google เมื่อเกิดเหตุการณ์

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;
    // Fall back to constructing the endpoint URL if notifyUri is omitted.
    const notifyUri = triggerCreation.notifyUri ||
        ("https://workspacestudio.googleapis.com/v1/triggers/" +
         triggerId + ":fire");
    const inputs = triggerCreation.inputs;

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

    // Tip: In Apps Script, use PropertiesService to persist triggerId and notifyUri:
    // const props = PropertiesService.getUserProperties();
    // props.setProperty("notifyUri", notifyUri);
    // props.setProperty("triggerId", triggerId);
    //
    // 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;

    // In Apps Script, clean up stored properties:
    // PropertiesService.getUserProperties().deleteProperty("notifyUri");
    // PropertiesService.getUserProperties().deleteProperty("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.
 *     In Apps Script, defaults to ScriptApp.getOAuthToken().
 */
function simulateEventFire(notifyUri, triggerId, userAccessToken) {
  // In Apps Script, obtain the OAuth token using ScriptApp.getOAuthToken().
  const token = userAccessToken || ScriptApp.getOAuthToken();
  // 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 " + token
    },
    "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());
  }
}

ใช้ Workspace Studio API

คุณสามารถใช้ Workspace Studio API (workspacestudio.googleapis.com) เพื่อแจ้งให้ Google ทราบถึงเหตุการณ์เริ่มต้น โดยอัตโนมัติ

โดยปลายทางจะอยู่ในเส้นทางฐานต่อไปนี้ https://workspacestudio.googleapis.com/v1

แจ้งเตือนเหตุการณ์เริ่มต้น

เรียกใช้ตัวเริ่มต้นโดยใช้เมธอด triggers.fire เพื่อเริ่มการดำเนินการของโฟลว์

• เมธอด HTTP: POST
• เส้นทาง: /v1/triggers/{triggerId}:fire (โดยที่ {triggerId} คือตัวระบุที่ไม่ซ้ำกัน ซึ่งดึงข้อมูลมาในระหว่างการสร้างการสมัครใช้บริการทริกเกอร์)
• ขอบเขตของ OAuth: https://www.googleapis.com/auth/workspace.studio.trigger

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีเรียกใช้สตาร์ทเตอร์ในคำขอ

คำขอ

{
  "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 (สตริง ต้องระบุ): ชื่อทรัพยากรของสตาร์ทเตอร์ในรูปแบบ triggers/{triggerId}
• outputs (แผนที่ ไม่บังคับ): แผนที่ของตัวแปรเอาต์พุตเริ่มต้นที่แสดง ข้อมูลเหตุการณ์ ค่าแต่ละค่าคือออบเจ็กต์ VariableData ที่รองรับรายการที่พิมพ์ (เช่น stringValues, booleanValues, integerValues)
• log (ออบเจ็กต์, ไม่บังคับ): การแสดงมาร์กอัป TextFormat ที่แสดงใน บันทึกกิจกรรมการดำเนินการของ Workspace Studio
• requestId (สตริง, ไม่บังคับ): ตัวระบุที่ไม่ซ้ำ (แนะนำให้ใช้ UUID v4) ที่มีอักขระ ASCII ได้สูงสุด 36 ตัวเพื่อให้แน่ใจว่า API จะทำงานซ้ำได้เมื่อลองอีกครั้ง

คำตอบ

การตอบกลับจะแสดงออบเจ็กต์ JSON ว่าง {} เมื่อสำเร็จ

โควต้า API ของ Workspace Studio

การเข้าชมที่ส่งไปยังบริการ workspacestudio.googleapis.com จะถูกจำกัดเพื่อ ป้องกันไม่ให้ระบบทำงานหนักเกินไป ส่งเสริมการใช้ทรัพยากรอย่างเป็นธรรม และปกป้องประสิทธิภาพโดยรวมของ Google Workspace

ระบบจะบังคับใช้โควต้าต่อไปนี้

ประเภทโควต้า	โควต้า
ต่อนาทีต่อโปรเจ็กต์	คำขอเริ่มต้น 1,000 รายการ
ต่อนาทีต่อผู้ใช้	คำขอเริ่มต้น 100 รายการ

ประเภทโควต้ามีดังนี้

• ต่อนาทีต่อโปรเจ็กต์: จำกัดจำนวนสะสมของเหตุการณ์เริ่มต้น ที่เรียกใช้จากโปรเจ็กต์ Google Cloud ของนักพัฒนาแอปรายเดียวเป็น 1,000 คำขอต่อ นาทีในผู้ใช้ทั้งหมดที่เรียกใช้เหตุการณ์เริ่มต้น
• ต่อนาทีต่อผู้ใช้: จำกัดการเรียกใช้ฟังก์ชันเริ่มต้นสะสมของผู้ใช้ปลายทางรายเดียวในโปรเจ็กต์ Cloud ที่กำหนดไว้ที่ 100 คำขอต่อนาที

จัดการข้อผิดพลาดเกี่ยวกับโควต้าตามเวลา

หากใช้เกินโควต้าเหล่านี้ API จะแสดงรหัสข้อผิดพลาด HTTP 429 Too Many Requests (หรือ 429 Resource Exhausted) ซึ่งระบุว่าใช้โควต้าอัตราเกิน

หากต้องการแก้ไขข้อผิดพลาดเหล่านี้ โค้ดของคุณควรตรวจหาข้อยกเว้นและใช้ กลยุทธ์ Exponential Backoff ที่ถูกตัดทอน Exponential Backoff จะลองส่งคำขอที่ล้มเหลวอีกครั้งโดยเพิ่มระยะเวลาหน่วงระหว่างการลองแต่ละครั้ง รวมถึง การสุ่มเวลาหน่วง (คำนวณเวลาหน่วงแบบสุ่มใหม่ในแต่ละการวนซ้ำ) เพื่อ ป้องกันไม่ให้ไคลเอ็นต์หลายรายซิงค์และลองส่งอีกครั้งในเวลาเดียวกัน

1. ส่งคำขอไปยัง Workspace Studio API
2. หากคำขอไม่สำเร็จและมีข้อผิดพลาด 429 ให้รอ 1 second + random_number_milliseconds แล้วลองอีกครั้ง
3. หากไม่สำเร็จอีกครั้ง ให้รอ 2 seconds + random_number_milliseconds แล้วลองอีกครั้ง
4. หากไม่สำเร็จอีกครั้ง ให้รอ 4 seconds + random_number_milliseconds แล้วลองอีกครั้ง
5. ทำซ้ำลูปนี้ โดยเพิ่มการหน่วงเวลาเป็น 2 เท่าจนถึงขีดจำกัด maximum_backoff (โดยปกติคือ 32 หรือ 64 วินาที)
6. เมื่อถึงระยะเวลา Backoff สูงสุด ให้ลองอีกครั้งโดยใช้การหน่วงเวลาคงที่นั้น จนกว่าจะถึงขีดจำกัดการลองใหม่สูงสุด จากนั้นให้หยุดและบันทึกข้อผิดพลาด

แนวทางปฏิบัติแนะนำ

เมื่อออกแบบและติดตั้งใช้งาน Starter ให้พิจารณาแนวทางปฏิบัติแนะนำต่อไปนี้

ส่งเหตุการณ์เดียวแทนที่จะส่งรายการเป็นกลุ่ม

ออกแบบเงื่อนไขเริ่มต้นให้ปล่อยเหตุการณ์แต่ละรายการสำหรับการเกิดแต่ละครั้งที่แตกต่างกัน (เช่น บันทึกเดียวที่อัปเดต ข้อความใหม่ที่โพสต์ หรืองานที่มอบหมาย) แทนที่จะปล่อยเหตุการณ์เดียวที่มีชุดหรือรายการของรายการ

• ความสอดคล้องกับตัวเริ่มต้นในตัว: ใน Workspace Studio ตัวเริ่มต้น Google Workspace ในตัว (เช่น การรับอีเมลใน Gmail หรือผู้ใช้เข้าร่วมพื้นที่ใน Google Chat) จะทริกเกอร์ใน เหตุการณ์เดียว การส่งเหตุการณ์แบบไอเทมเดียวสอดคล้องกับลักษณะการทำงานนี้และ มอบประสบการณ์การใช้งานที่สอดคล้องและคาดการณ์ได้สำหรับผู้ใช้ในทุกแพ็กเกจเริ่มต้น
• การกำหนดค่าโฟลว์ที่ง่ายขึ้น: โดยปกติแล้ว ขั้นตอนปลายทางในโฟลว์จะประมวลผลรายการทีละรายการ การปล่อยเหตุการณ์แบบรายการเดียวช่วยให้ผู้ใช้สามารถแมปตัวแปรได้โดยตรงโดยไม่ต้อง เพิ่มขั้นตอนที่ซับซ้อนเพื่อวนซ้ำอาร์เรย์หรือแยกวิเคราะห์รายการ
• จัดการการสำรวจและการเปลี่ยนแปลงแบบเป็นกลุ่มแยกกัน: หากบริการแบ็กเอนด์ สำรวจ API ภายนอกและตรวจพบรายการที่เปลี่ยนแปลงหลายรายการในช่วงเวลาการสำรวจเดียว ให้ทริกเกอร์เหตุการณ์เริ่มต้นแต่ละรายการสำหรับแต่ละรายการแทนที่จะ รวมไว้ในเหตุการณ์แบบเป็นกลุ่มเดียว
• จัดการอัตราและโควต้าเหตุการณ์: เนื่องจากการทริกเกอร์เหตุการณ์แต่ละรายการสำหรับ รายการที่เปลี่ยนแปลงหลายรายการอาจทำให้เกิดคำขอจำนวนมากอย่างฉับพลัน โปรดตรวจสอบว่าบริการของคุณอยู่ภายในโควต้า Workspace Studio API (เช่น ขีดจำกัดคำขอ 100 รายการต่อนาทีต่อผู้ใช้) หากรอบการสำรวจ สร้างรายการจำนวนมาก (เช่น มีการเปลี่ยนแปลงมากกว่า 100 รายการ) ให้เว้นระยะหรือจำกัดการส่งเหตุการณ์เมื่อเวลาผ่านไปเพื่อหลีกเลี่ยงข้อผิดพลาด 429 Too Many Requests

หมายเหตุ: ในทางเทคนิคแล้ว ระบบรองรับตัวเริ่มต้นการประมวลผลแบบกลุ่มที่กำหนดเองซึ่งปล่อยรายการออบเจ็กต์ แต่ไม่สอดคล้องกับตัวเริ่มต้นมาตรฐาน และอาจต้องใช้ตรรกะเพิ่มเติมในขั้นตอนดาวน์สตรีมเพื่อจัดการอาร์เรย์

พฤติกรรมหลักและกรณีที่พบได้ยาก

เมื่อผสานรวมตัวเริ่มต้น นักพัฒนาแอปต้องจัดการลักษณะการทำงานของข้อผิดพลาดที่เฉพาะเจาะจงและฟีเจอร์รันไทม์ ดังนี้

• ไม่รองรับการทดสอบ: Workspace Studio ไม่รองรับการทดสอบสำหรับผู้เริ่มต้น
• การป้องกันการเล่นซ้ำและการดำเนินการซ้ำ: แม้ว่าจะไม่จำเป็นอย่างเคร่งครัด แต่คุณควรใส่ requestId ที่ไม่ซ้ำกัน (เช่น UUID) ในเพย์โหลด HTTP หรือ Apps Script การระบุ requestId จะช่วยให้มั่นใจได้ว่าระบบจะไม่ทำงานซ้ำซ้อนเมื่อมีการป้อนข้อมูลหลายครั้ง โดยช่วยให้ API ตรวจหาและละเว้นการแจ้งเตือนที่ซ้ำกันได้ ซึ่งจะป้องกันไม่ให้โฟลว์ทำงานหลายครั้งสำหรับเหตุการณ์เดียว

• โฟลว์ที่ปิดใช้และเปิดใช้อีกครั้ง: เมื่อมีการปิดใช้โฟลว์ที่มีสตาร์เตอร์ใน Workspace Studio Google จะส่งtriggerDeletionเหตุการณ์วงจรonManageFunctionไปยังการเรียกกลับ นอกจากนี้ การเรียกไปยังเมธอด FireTrigger ที่เชื่อมโยงจะแสดงรหัสข้อผิดพลาด 404 Not Found (Requested entity was not found.) บริการของคุณควรตอบสนองต่อข้อผิดพลาด 404 โดยหยุดการแจ้งเตือนเหตุการณ์ในอนาคตสำหรับรหัสอินสแตนซ์เริ่มต้นนั้น

  หากผู้ใช้เปิดใช้โฟลว์อีกครั้งในภายหลัง Google จะเริ่มวงจรการสมัครใช้บริการใหม่โดยเรียกใช้onManageFunction Callback ของคุณด้วยเหตุการณ์ triggerCreation ใหม่ที่มี triggerId และ notifyUri ใหม่ เราจะหยุดให้บริการ triggerId อย่างถาวรและจะไม่เปิดใช้งานอีก ดังนั้นบริการของคุณจึงไม่ควรสำรวจหรือตรวจสอบว่ามีการเปิดใช้ทริกเกอร์ อินสแตนซ์เก่าอีกครั้งหรือไม่ ดูข้อมูลเพิ่มเติมได้ที่ จัดการวงจรการสมัครใช้บริการเริ่มต้น

• การลบการสมัครใช้บริการแบบ Idempotent: onManageFunctionฟังก์ชันการเรียกกลับ ต้องจัดการคำขอลบการสมัครใช้บริการเริ่มต้นจาก Google แบบ Idempotent หาก Google เรียกใช้ Hook การลบหลายครั้งสำหรับtriggerIdเดียวกัน (เช่น ระหว่างการลองใหม่เนื่องจากการเชื่อมต่อขาดหายชั่วคราว) ฟังก์ชัน ควรแสดงผลสำเร็จ

• โควต้าโฟลว์: นอกเหนือจาก โควต้า API ของ Workspace Studio แล้ว โฟลว์ ของผู้ใช้ยังอยู่ภายใต้การควบคุมโควต้าภายในเพิ่มเติม ด้วย ลูปความถี่สูงหรือปริมาณเหตุการณ์ที่มากเกินไปอาจเกินเกณฑ์ความปลอดภัย ซึ่งส่งผลให้ระบบปิดใช้โฟลว์โดยอัตโนมัติ

• ปฏิเสธการให้สิทธิ์ (403) เมื่อทริกเกอร์ทำงาน: หากการเรียกไปยัง triggers.fireปลายทางแสดงผล 403 PERMISSION_DENIED ที่มีสถานะข้อผิดพลาด SERVICE_DISABLED ให้ตรวจสอบว่า

  • เปิดใช้ Google Workspace Studio API ในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google แล้ว
  • หากใช้ Google Apps Script โปรเจ็กต์จะลิงก์กับโปรเจ็กต์ที่อยู่ในระบบคลาวด์มาตรฐาน แทนที่จะเป็นโปรเจ็กต์ Cloud ของ Apps Script เริ่มต้น
  • โทเค็นเพื่อการเข้าถึง OAuth มี https://www.googleapis.com/auth/workspace.studio.trigger ขอบเขต

หัวข้อที่เกี่ยวข้อง

• สร้างขั้นตอน
• เชื่อมต่อส่วนเสริมของ Google Workspace กับบริการของบุคคลที่สาม
• ตัวแปรอินพุต
• ตัวแปรเอาต์พุต
• บันทึกกิจกรรมและข้อผิดพลาด
• จัดการข้อผิดพลาด
• ออบเจ็กต์เหตุการณ์ Workspace Studio
• Codelab: สร้างขั้นตอนเริ่มต้นและขั้นตอนการดำเนินการของ Workspace Studio ที่กำหนดเอง