يوضّح هذا المستند كيفية إنشاء أداة تفعيل تسمح لتطبيقك أو خدمتك بإرسال إشعار إلى Google Workspace Studio عند وقوع حدث وبدء تنفيذ مسار. في واجهة برمجة التطبيقات، تُعرف أدوات التفعيل باسم workflowTriggers.
تبدأ أداة التفعيل مسارًا، بينما الخطوة هي مهمة واحدة في تسلسل المهام التي تشمل مسارًا. من خلال إنشاء أداة تفعيل، يمكنك السماح للمستخدمين بإعداد مسارات آلية تتفاعل مع الأحداث في الوقت الفعلي من تطبيقك أو خدمتك.
يتضمّن إنشاء أداة تفعيل الإعلان عنها في ملف بيان الإضافة وتنفيذ عمليات معاودة الاتصال بدورة الحياة في "برمجة تطبيقات Google"، أو تفعيل الأداة من خلال نشر حمولات بيانات إلى نقطة نهاية Google Workspace Studio API.
المتطلبات الأساسية
- حساب Google يمكنه الوصول إلى Workspace Studio
- مشروع Google Cloud
تفعيل واجهة برمجة التطبيقات
في مشروع على السحابة الإلكترونية على Google Cloud، فعِّل واجهة برمجة تطبيقات الاستوديو في Google Workspace Studio:
التبديل إلى مشروع Google Cloud عادي (برمجة تطبيقات Google فقط)
تستخدم مشاريع "برمجة تطبيقات Google" تلقائيًا مشروعًا تلقائيًا على السحابة الإلكترونية لا يتيح تفعيل واجهات برمجة التطبيقات أو ضبط شاشات طلب الموافقة المتعلّقة ببروتوكول OAuth. إذا كنت تنشئ أداة التفعيل باستخدام "برمجة تطبيقات Google"، عليك التبديل إلى مشروع Google Cloud عادي:
- في محرّر "برمجة تطبيقات Google"، انقر على إعدادات المشروع .
- ضمن مشروع Google Cloud Platform (GCP)، انقر على تغيير المشروع.
- أدخِل رقم مشروعك العادي على السحابة الإلكترونية وانقر على ضبط المشروع.
- بعد التبديل بين المشاريع، أعِد تفويض النص البرمجي من خلال تشغيل أي دالة في المحرّر ومنح الأذونات المطلوبة.
لمزيد من المعلومات، يُرجى الاطّلاع على مقالة التبديل إلى مشروع Google Cloud عادي.
ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth
للتواصل مع نقطة نهاية Workspace Studio API، يجب أن تتم مصادقة تطبيقك أو خدمتك باستخدام OAuth 2.0. اضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth لمشروعك وأضِف نطاق OAuth المخصّص التالي:
https://www.googleapis.com/auth/workspace.studio.trigger
يمنح هذا النطاق التطبيق إذن استدعاء Workspace Studio API وتفعيل المسارات التي ضبطها المستخدم لأداة التفعيل هذه.
لمعرفة التفاصيل، يُرجى الانتقال إلى مقالة ضبط شاشة طلب الموافقة لبروتوكول OAuth واختيار النطاقات.
التشغيل بلا إنترنت والرموز المميّزة لإعادة التحميل
بما أنّ أدوات التفعيل تُرسل إشعارًا إلى Workspace Studio بشكل غير متزامن عند وقوع حدث في الخدمة الخارجية، قد تحتاج خدمتك إلى تقديم رمز دخول صالح لبروتوكول OAuth 2.0 عند استدعاء نقطة نهاية واجهة برمجة التطبيقات، وقد يحدث ذلك بعد ساعات أو أيام أو أشهر من ضبط المستخدم لمسار.
إنّ رمز الدخول الذي تقدّمه Google في عنصر حدث الإضافة (مثل أثناء ضبط أداة التفعيل أو طلبات الاستدعاء في إحدى مراحل النشاط) قصير الأمد وصالح لمدة ساعة واحدة فقط. ولا يكفي لتفعيل أحداث أداة التفعيل بشكل غير متزامن في المستقبل. لاستدعاء Workspace Studio API بمرور الوقت، تحتاج خدمتك إلى رمز مميّز لإعادة التحميل بلا إنترنت لإنشاء رموز دخول جديدة عند الطلب.
تعتمد طريقة التعامل مع التفويض والحصول على رمز مميّز لإعادة التحميل على وقت تشغيل الإضافة:
الإضافات المستندة إلى HTTP (أوقات التشغيل البديلة): بالنسبة إلى الإضافات المستندة إلى HTTP، يجب أن تنفّذ خدمة الخلفية سير عمل منفصلاً لتفويض OAuth 2.0 بشكل مستقل عن تفويض الإضافة المضمّن لطلب التشغيل بلا إنترنت (
access_type=offline) وتلقّي الرمز المميز لإعادة التحميل.يمكنك مطالبة المستخدمين بتفويض هذا الاتصال من خلال عرض بطاقة تسجيل دخول أو تفويض عندما يضبط المستخدم أداة التفعيل في Workspace Studio. لمزيد من المعلومات حول عرض بطاقات التفويض والتعامل مع سير عمل OAuth، يُرجى الاطّلاع على مقالة ربط إضافة Google Workspace بخدمة خارجية (التعامل مع Google Workspace كخدمة خارجية يتم الربط بها).
يجب أن تخزّن خدمة الخلفية الرمز المميّز لإعادة التحميل بشكل آمن (على سبيل المثال، في قاعدة بيانات خدمتك بجانب
triggerId) واستخدامه لاسترداد رمز دخول جديد كلما وقع حدث قبل إرسال الطلبات إلىnotifyUriلأداة التفعيل أو نقطة نهاية واجهة برمجة التطبيقاتtriggers.fire.إضافات "برمجة تطبيقات Google": يمكن للإضافات المستندة إلى "برمجة تطبيقات Google" التي تستخدم مشغّلات مجدولة (مستندة إلى الوقت) للتحقّق من الأحداث بشكل دوري تخطّي تنفيذ سير عمل OAuth مستقل. بما أنّ المشغّلات المجدولة تعمل مباشرةً ضمن بيئة وقت تشغيل "برمجة تطبيقات Google"، تدير "برمجة تطبيقات Google" تلقائيًا رموز OAuth المميّزة وتُعيد تحميلها باستخدام النطاقات المُعلَن عنها في البيان. يمكنك استرداد رمز دخول OAuth باستخدام
ScriptApp.getOAuthToken().
تحديد أداة التفعيل في ملف البيان
لتحديد أداة تفعيل، أضِفها إلى ملف بيان الإضافة (appsscript.json) ضِمن كتلة addOns.studio.flows.workflowElements. هذا الإعداد مطلوب لكل من أوقات تشغيل "برمجة تطبيقات Google" وHTTP (أوقات التشغيل البديلة). اضبط العنصر على أنّه workflowTrigger بدلاً من workflowAction (الذي يُستخدَم عند تحديد خطوة). لمزيد من المعلومات، يُرجى الاطّلاع على مقالة
بنية البيان لإضافات
Google Workspace.
ضِمن كتلة workflowTrigger، حدِّد ما يلي:
inputs: المتغيّرات التي يضبطها المستخدم في بطاقة الإعداد (مثل اسم المشروع أو فلتر الموارد أو غير ذلك)outputs: المتغيّرات التي يمكن أن تُرجعها أداة التفعيل إلى الخطوات اللاحقة في المسارonConfigFunction: اسم دالّة رد الاتصال التي تعرض واجهة إعداد المستخدمonManageFunction: اسم دالّة رد الاتصال التي تستدعيها Google للتعامل مع إنشاء اشتراك أداة التفعيل وحذفه.
تعرض عيّنة تعليمات برمجية التالية مثالاً على تعريف البيان لأداة تفعيل الأحداث:
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 المُعلَن عنها في البيان.
عنصر حدث يتم في مراحل النشاط
تتلقّى دالّة رد الاتصال 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 فريدة لمثال الاشتراك الذي يجب تنظيفه
دورة حياة الاشتراك في أوقات التشغيل البديلة (HTTP API)
بالنسبة إلى الإضافات التي تم إنشاؤها باستخدام أوقات تشغيل بديلة، يتم إرسال إشعارات مراحل نشاط الاشتراك باستخدام طلبات POST إلى عنوان URL لنقطة نهاية HTTP الذي تم ضبطه للإضافة مع اسم الإجراء الذي تحدّده دالّة رد الاتصال onManageFunction. تتطابق حمولة البيانات مع تمثيل JSON لـ WorkflowEventObject.
لمزيد من المعلومات حول أوقات التشغيل البديلة، يُرجى الاطّلاع على مقالة إنشاء إضافة في Google Workspace باستخدام نقاط نهاية HTTP.
تنفيذ الاستدعاءات في إحدى مراحل النشاط في "برمجة تطبيقات Google"
يوضّح مثال "برمجة تطبيقات Google" التالي كيفية ضبط بطاقة واجهة المستخدم، والتعامل مع أحداث دورة حياة الاشتراك باستخدام onManageTrigger، وإعادة تفعيل طلب أداة التفعيل إلى Google عند وقوع حدث.
برمجة التطبيقات
/**
* 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 الإصدار 4) يتضمّن ما يصل إلى 36 حرفًا من أحرف ASCII لضمان عدم تكرار واجهة برمجة التطبيقات عند إعادة المحاولة
الردّ
يعرض الردّ عنصر JSON فارغًا {} عند النجاح.
حصص Workspace Studio API
يتم تقييد عدد الزيارات المُرسَلة إلى خدمة workspacestudio.googleapis.com لمنع زيادة التحميل على النظام وتشجيع الاستخدام العادل للموارد وحماية الأداء العام لـ Google Workspace.
يتم فرض الحصص التالية:
| نوع الحصة | Quota |
|---|---|
| في الدقيقة لكل مشروع | 1,000 طلب لأداة التفعيل |
| في الدقيقة لكل مستخدم | 100 طلب لأداة التفعيل |
أنواع الحصص هي:
- في الدقيقة لكل مشروع: يحدّ من العدد التراكمي لأحداث أداة التفعيل التي يتم تفعيلها من مشروع Google Cloud لمطوّر واحد إلى 1,000 طلب في الدقيقة على مستوى جميع المستخدمين الذين يشغّلون أدوات التفعيل.
- في الدقيقة لكل مستخدم: يحدّ من عمليات استدعاء إجراء التفعيل التراكمية لأي مستخدم نهائي في مشروع على السحابة الإلكترونية معيّن إلى 100 طلب في الدقيقة.
التعامل مع أخطاء الحصة المستندة إلى الوقت
إذا تجاوزت هذه الحصص، ستعرض واجهة برمجة التطبيقات رمز خطأ HTTP 429 Too Many Requests (أو 429 Resource Exhausted) يشير إلى أنّه تم تجاوز الحصة المسموح بها.
لحلّ هذه الأخطاء، يجب أن يرصد الرمز الاستثناء ويستخدم إستراتيجية التراجع الدليلي المقتطع. تُعيد إستراتيجية التراجع الدليلي محاولة إرسال الطلبات التي تعذّر تنفيذها باستخدام حالات تأخير أطول تدريجيًا بين المحاولات، بما في ذلك التغيير العشوائي (إعادة احتساب التأخير العشوائي في كل تكرار) لمنع مزامنة عملاء متعددين وإعادة المحاولة في الوقت نفسه:
- أرسِل طلبًا إلى Workspace Studio API.
- إذا تعذّر تنفيذ الطلب وظهر الخطأ
429، انتظِر1 second + random_number_millisecondsوأعِد المحاولة. - إذا تعذّر تنفيذ الطلب مرة أخرى، انتظِر
2 seconds + random_number_millisecondsوأعِد المحاولة. - إذا تعذّر تنفيذ الطلب مرة أخرى، انتظِر
4 seconds + random_number_millisecondsوأعِد المحاولة. - واصِل هذه الحلقة، مع مضاعفة التأخير حتى الوصول إلى حدّ
maximum_backoff(عادةً 32 أو 64 ثانية). - عند الوصول إلى الحد الأقصى لمدة التراجع، أعِد المحاولة باستخدام هذا التأخير الثابت إلى أن يتم الوصول إلى الحد الأقصى لعدد المحاولات، ثم توقّف وسجِّل الخطأ.
أفضل الممارسات
عند تصميم أداة تفعيل وتنفيذها، ننصحك باتّباع أفضل الممارسات التالية:
إرسال أحداث فردية بدلاً من قوائم مجمّعة
صمِّم أداة التفعيل لإرسال حدث فردي لكل حالة مختلفة (مثل سجلّ واحد تم تعديله أو رسالة جديدة تم نشرها أو مهمة تم إسنادها) بدلاً من إرسال حدث واحد يحتوي على مجموعة أو قائمة من العناصر:
- الاتساق مع أدوات التفعيل المضمّنة: في Workspace Studio، يتم تفعيل أدوات التفعيل المضمّنة في Google Workspace (مثل تلقّي رسالة إلكترونية في Gmail أو انضمام مستخدم إلى مساحة في Google Chat) عند وقوع حدث واحد. يتوافق إرسال أحداث عنصر واحد مع هذا السلوك ويوفر تجربة متسقة ويمكن توقّعها للمستخدمين على مستوى جميع أدوات التفعيل.
- إعداد أسهل للمسار: تعالج الخطوات اللاحقة في المسار عادةً عنصرًا واحدًا في كل مرة. يتيح إرسال أحداث عنصر واحد للمستخدمين ربط المتغيّرات مباشرةً بدون إضافة خطوات معقّدة للتكرار على مستوى المصفوفات أو تحليل القوائم.
- التعامل مع عمليات التحقّق من البيانات بشكل دوري والتغييرات المجمّعة بشكل فردي: إذا كانت خدمة الخلفية تتحقّق من واجهة برمجة تطبيقات خارجية بشكل دوري ورصدت عدة عناصر متغيرة خلال فترة التحقّق من البيانات بشكل دوري، فعِّل حدث أداة تفعيل فردي لكل عنصر بدلاً من تجميعها في حدث واحد مجمّع.
- إدارة معدّل الأحداث والحصص: بما أنّ تفعيل أحداث فردية لـ
عدة عناصر تم تغييرها يمكن أن يؤدي إلى حدوث زيادة مفاجئة في الطلبات، تأكَّد من أنّ خدمتك
تلتزم بـ حصص Workspace Studio API
(مثل الحدّ الأقصى البالغ 100 طلب في الدقيقة لكل مستخدم). إذا كانت دورة التحقّق من البيانات بشكل دوري تؤدي إلى ظهور عدد كبير من العناصر (على سبيل المثال، أكثر من 100 سجلّ تم تغييره)، يمكنك إبطاء عمليات إرسال الأحداث أو تقليلها بمرور الوقت لتجنُّب أخطاء
429 Too Many Requests.
السلوكيات الأساسية والحالات القصوى
عند دمج أدوات التفعيل، على المطوّرين التعامل مع سلوكيات أخطاء وميزات وقت التشغيل معيّنة:
- لا يتوفّر الدعم لعمليات التشغيل التجريبية: لا يتيح Workspace Studio عمليات التشغيل التجريبية لأدوات التفعيل.
- عدم التكرار ومنع إعادة التشغيل: على الرغم من أنّه ليس مطلوبًا بشكل صارم، ننصحك بتضمين
requestIdفريد (مثل UUID) في حمولة بيانات HTTP أو "برمجة تطبيقات Google". يضمن تقديمrequestIdعدم التكرار من خلال السماح لواجهة برمجة التطبيقات برصد الإشعارات المكرّرة وتجاهلها، ما يمنع تشغيل المسار عدة مرات لحدث واحد. المسارات التي تم إيقافها وإعادة تفعيلها: عندما يتم إيقاف مسار يحتوي على أداة التفعيل في Workspace Studio، تُرسِل Google حدث يتم في مراحل النشاط
triggerDeletionإلى دالة معاودة الاتصالonManageFunction. بالإضافة إلى ذلك، تعرض أي طلبات للطريقة المرتبطةFireTriggerرمز استجابة للخطأ404 Not Found(Requested entity was not found.). يجب أن تتفاعل خدمتك مع أخطاء404من خلال إيقاف عمليات إرسال إشعار برصد حدث المستقبلية لمعرّف مثال إجراء التفعيل هذا.إذا أعاد المستخدم تفعيل المسار لاحقًا، تبدأ Google دورة حياة اشتراك جديدة من خلال استدعاء دالة معاودة الاتصال
onManageFunctionباستخدام حدثtriggerCreationجديد يحتوي علىtriggerIdوnotifyUriجديدَين. يتم إيقافtriggerIdالسابق نهائيًا ولا تتم إعادة تفعيله، لذا يجب ألا تتحقّق خدمتك من ما إذا تمت إعادة تفعيل مثال مشغِّل قديم أو تتحقّق من ذلك بشكل دوري. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة التعامل مع دورة حياة اشتراك أداة التفعيل.حذف الاشتراك بدون تكرار: يجب أن تتعامل دالة معاودة الاتصال
onManageFunctionمع طلبات حذف أداة التفعيل من Google بدون تكرار. إذا استدعت Google خطاف الحذف عدة مرات لـtriggerIdنفسه (على سبيل المثال، أثناء عمليات إعادة المحاولة بسبب فقدان الاتصال المؤقت)، يجب أن تعرض الدالة النجاح.حصص المسار: بالإضافة إلى حصص Workspace Studio API، تخضع مسارات المستخدمين لعناصر تحكّم إضافية في الحصص الداخلية. قد تتجاوز الحلقات المتكرّرة أو العدد الكبير من الأحداث الحدود الآمنة، ما يؤدي إلى إيقاف المسار تلقائيًا.
تم رفض الإذن (403) عند تفعيل المشغِّل: إذا كانت عمليات استدعاء نقطة نهاية
triggers.fireتعرض403 PERMISSION_DENIEDمع حالة الخطأSERVICE_DISABLED، تأكَّد مما يلي:- تفعيل Google Workspace Studio API في مشروع Google Cloud
- إذا كنت تستخدم "برمجة تطبيقات Google"، يجب أن يكون مشروعك مرتبطًا بمشروع عادي على السحابة الإلكترونية بدلاً من مشروع "برمجة تطبيقات Google" التلقائي على السحابة الإلكترونية.
- يتضمّن رمز دخول OAuth النطاق
https://www.googleapis.com/auth/workspace.studio.trigger.
المواضيع ذات الصلة
- إنشاء خطوة
- ربط إضافة Google Workspace بخدمة خارجية
- متغيّرات الإدخال
- متغيّرات الناتج
- تسجيل النشاط والأخطاء
- التعامل مع الأخطاء
- عناصر أحداث Workspace Studio
- درس تطبيقي حول الترميز: إنشاء خطوات مخصّصة لأداة التفعيل والإجراء في Workspace Studio
- درس تطبيقي حول الترميز: إنشاء خطوات مخصّصة لأداة التفعيل والإجراء في Workspace Studio باستخدام Node.js