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

การดูที่จำกัด: การขยาย Google Workspace Studio ด้วยส่วนเสริมอยู่ในการดูที่จำกัด ดูข้อมูลเพิ่มเติม

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

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

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

ข้อกำหนดเบื้องต้นและการให้สิทธิ์ OAuth

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

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

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

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

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

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

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

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

  คุณสามารถแจ้งให้ผู้ใช้ให้สิทธิ์การเชื่อมต่อนี้ได้โดยแสดงการ์ดลงชื่อเข้าใช้หรือ การให้สิทธิ์เมื่อผู้ใช้กำหนดค่าเงื่อนไขเริ่มต้นใน 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

สำหรับส่วนเสริมที่สร้างขึ้นโดยใช้รันไทม์อื่น ระบบจะส่งการแจ้งเตือนวงจรการสมัครใช้บริการ โดยใช้คำขอ HTTP POST ไปยัง URL ปลายทาง HTTP ที่กำหนดค่าไว้ของส่วนเสริม พร้อมชื่อการดำเนินการที่ระบุโดยonManageFunctionฟังก์ชัน Callback เพย์โหลดตรงกับ การแสดง 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;
    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());
  }
}

ใช้ 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 จะลองส่งคำขอที่ไม่สำเร็จอีกครั้ง โดยใช้การหน่วงเวลาที่นานขึ้นเรื่อยๆ ระหว่างการลองแต่ละครั้ง รวมถึง Jitter แบบสุ่ม (คำนวณการหน่วงเวลาแบบสุ่มใหม่ในแต่ละการทำซ้ำ) เพื่อ ป้องกันไม่ให้ไคลเอ็นต์หลายรายซิงโครไนซ์และลองอีกครั้งในเวลาเดียวกัน

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 สูงสุด ให้ลองอีกครั้งโดยใช้การหน่วงเวลาคงที่นั้น จนกว่าจะถึงขีดจำกัดการลองใหม่สูงสุด จากนั้นให้หยุดและบันทึกข้อผิดพลาด

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

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

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

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

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

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

พฤติกรรมหลักและกรณีสุดโต่ง

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

• ไม่รองรับการทดสอบ: 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คอลแบ็กพร้อมกับเหตุการณ์triggerCreationใหม่ที่มี triggerId และ notifyUri ใหม่ เราจะเลิกใช้งาน triggerId ก่อนหน้านี้อย่างถาวรและจะไม่เปิดใช้งานอีกครั้ง ดังนั้นบริการของคุณจึงไม่ควรสำรวจหรือตรวจสอบว่ามีการเปิดใช้ทริกเกอร์อินสแตนซ์เก่าอีกครั้งหรือไม่ ดูข้อมูลเพิ่มเติมได้ที่จัดการวงจรการสมัครใช้บริการเริ่มต้น

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

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

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

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