إعداد الإشعارات الفورية وتلقّيها

يمكنك استخدام الطرق الواردة في مجموعة المراقبات لتلقّي إشعارات عند تغيير البيانات في النماذج. تقدّم هذه الصفحة نظرة عامة على المفاهيم الأساسية وإرشادات حول إعداد رسائل التحذير المفاجئة وتلقّيها.

نظرة عامة

تتيح ميزة الإشعارات الفورية في Google Forms API للتطبيقات الاشتراك في الإشعارات عند تغيير البيانات في النماذج. يتم إرسال الإشعارات إلى موضوع Cloud Pub/Sub، عادةً في غضون دقائق من التغيير.

لتلقّي إشعارات فورية، عليك إعداد موضوع Cloud Pub/Sub و تقديم اسم هذا الموضوع عند إنشاء مراقبة لنوع الحدث المناسب.

في ما يلي تعريفات للمفاهيم الرئيسية المستخدَمة في هذه المستندات:

• الهدف هو المكان الذي يتم إرسال الإشعارات إليه. الوجهة الوحيدة المتوافقة هي موضوع Cloud Pub/Sub.
• نوع الحدث هو فئة من الإشعارات التي يمكن لتطبيق تابع لجهة خارجية الاشتراك فيها.
• المُراقبة هي عبارة عن إرشادات مُرسَلة إلى واجهة برمجة التطبيقات Forms API لإرسال إشعارات بشأن نوع حدث معيّن في نموذج معيّن إلى هدف معيّن.

بعد إنشاء مراقبة لنوع حدث في نموذج معيّن، يتلقّى هدف المراقبة (وهو موضوع Cloud Pub/Sub) إشعارات من تلك الأحداث في ذلك النموذج إلى أن تنتهي صلاحية المراقبة. تستمر صلاحية ساعتك لمدة أسبوع، ولكن يمكنك تمديدها في أي وقت قبل انتهاء صلاحيتها من خلال تقديم طلب إلى watches.renew().

لا يتلقّى موضوع Cloud Pub/Sub إشعارات إلا عن النماذج التي يمكنك عرضها باستخدام بيانات الاعتماد التي تقدّمها. على سبيل المثال، إذا ألغى المستخدم الإذن من تطبيقك أو فقد إذن التعديل في نموذج تمت مراقبته، لن يتم إرسال الإشعارات بعد ذلك.

أنواع الأحداث المتاحة

توفّر Google Forms API حاليًا فئتين من الأحداث:

• EventType.SCHEMA، الذي يرسل إشعارات بشأن التعديلات التي يتم إجراؤها على محتوى النموذج وإعداداته.
• EventType.RESPONSES، الذي يرسل إشعارًا عند إرسال الردود على النماذج (سواء كانت جديدة أو معدَّلة).

الردود على الإشعارات

يتم ترميز الإشعارات باستخدام تنسيق JSON وتتضمّن ما يلي:

• رقم تعريف النموذج المشغِّل
• رقم تعريف الساعة التي أدّت إلى تشغيل الميزة
• نوع الحدث الذي أدّى إلى ظهور الإشعار
• الحقول الأخرى التي تحدّدها خدمة Cloud Pub/Sub، مثل messageId وpublishTime

لا تحتوي الإشعارات على بيانات تفصيلية عن النموذج أو الردود. بعد تلقّي كل إعلام، يجب إجراء طلب بيانات منفصل من واجهة برمجة التطبيقات لاسترجاع بيانات جديدة. اطّلِع على الاستخدام المقترَح لمعرفة كيفية إجراء ذلك.

يوضّح المقتطف التالي نموذج إشعار لتغيير في المخطّط:

{
  "attributes": {
    "eventType": "SCHEMA",
    "formId": "18Xgmr4XQb-l0ypfCNGQoHAw2o82foMr8J0HPHdagS6g",
    "watchId": "892515d1-a902-444f-a2fe-42b718fe8159"
  },
  "messageId": "767437830649",
  "publishTime": "2021-03-31T01:34:08.053Z"
}

يوضّح المقتطف التالي نموذج إشعار للاستجابة الجديدة:

{
  "attributes": {
    "eventType": "RESPONSES",
    "formId": "18Xgmr4XQb-l0ypfCNGQoHAw2o82foMr8J0HPHdagS6g",
    "watchId": "5d7e5690-b1ff-41ce-8afb-b469912efd7d"
  },
  "messageId": "767467004397",
  "publishTime": "2021-03-31T01:43:57.285Z"
}

إعداد موضوع Cloud Pub/Sub

يتم إرسال الإشعارات إلى مواضيع Cloud Pub/Sub. من Cloud Pub/Sub، يمكنك تلقّي إشعارات على أحد أدوات الربط على الويب، أو من خلال الاستعلام عن نقطة نهاية الاشتراك.

لإعداد موضوع Cloud Pub/Sub، اتّبِع الخطوات التالية:

1. أكمِل خطوات متطلبات Cloud Pub/Sub الأساسية.
2. إعداد عميل Cloud Pub/Sub
3. راجِع أسعار Cloud Pub/Sub، وفعِّل الفوترة لمشروعك على Developer Console.

4. يمكنك إنشاء موضوع Cloud Pub/Sub بطريقتَين:

   • باستخدام Play Console (الأكثر سهولة)
   • باستخدام أداة سطر الأوامر (للاستخدام الآلي البسيط) أو
   • باستخدام Cloud Pub/Sub API.
   ملاحظة: لا يسمح Cloud Pub/Sub إلا بتسجيل عدد محدود من المواضيع، لذا باستخدام موضوع واحد لتلقّي جميع إشعاراتك، يمكنك تجنُّب المشاكل المتعلّقة بالتوسّع إذا أصبح تطبيقك رائجًا.

5. أنشئ اشتراكًا في Cloud Pub/Sub لإعلام Cloud Pub/Sub بطريقة إرسال إشعاراتك.

6. أخيرًا، قبل إنشاء عمليات مراقبة تستهدف موضوعك، عليك منح الإذن لحساب خدمة إشعارات "نماذج Google" ([e-mail]) للنشر في موضوعك.

إنشاء ساعة

بعد أن يكون لديك موضوع يمكن لحساب خدمة الإشعارات الفورية Forms API النشر فيه، يمكنك إنشاء إشعارات باستخدام الأسلوب watches.create(). تتحقّق هذه الطريقة من أنّه يمكن لحساب خدمة الإشعارات الفورية الوصول إلى موضوع Cloud Pub/Sub المقدَّم، وتنتهي بحالة خطأ إذا تعذّر عليه الوصول إلى الموضوع، على سبيل المثال، إذا لم يكن الموضوع متوفّرًا أو إذا لم يتم منح حساب الخدمة إذن النشر في هذا الموضوع.

PythonNode.js

forms/snippets/create_watch.py

العرض على GitHub

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secret.json", SCOPES)
  creds = tools.run_flow(flow, store)

service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

watch = {
    "watch": {
        "target": {"topic": {"topicName": "<YOUR_TOPIC_PATH>"}},
        "eventType": "RESPONSES",
    }
}

form_id = "<YOUR_FORM_ID>"

# Print JSON response after form watch creation
result = service.forms().watches().create(formId=form_id, body=watch).execute()
print(result)

forms/snippets/create_watch.js

العرض على GitHub

'use strict';

const path = require('path');
const google = require('@googleapis/forms');
const {authenticate} = require('@google-cloud/local-auth');

const formID = '<YOUR_FORM_ID>';

async function runSample(query) {
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const forms = google.forms({
    version: 'v1',
    auth: authClient,
  });
  const watchRequest = {
    watch: {
      target: {
        topic: {
          topicName: 'projects/<YOUR_TOPIC_PATH>',
        },
      },
      eventType: 'RESPONSES',
    },
  };
  const res = await forms.forms.watches.create({
    formId: formID,
    requestBody: watchRequest,
  });
  console.log(res.data);
  return res.data;
}

if (module === require.main) {
  runSample().catch(console.error);
}
module.exports = runSample;

حذف ساعة

PythonNode.js

forms/snippets/delete_watch.py

العرض على GitHub

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secret.json", SCOPES)
  creds = tools.run_flow(flow, store)
service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

form_id = "<YOUR_FORM_ID>"
watch_id = "<YOUR_WATCH_ID>"

# Print JSON response after deleting a form watch
result = (
    service.forms().watches().delete(formId=form_id, watchId=watch_id).execute()
)
print(result)

forms/snippets/delete_watch.js

العرض على GitHub

'use strict';

const path = require('path');
const google = require('@googleapis/forms');
const {authenticate} = require('@google-cloud/local-auth');

const formID = '<YOUR_FORM_ID>';
const watchID = '<YOUR_FORMS_WATCH_ID>';

async function runSample(query) {
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const forms = google.forms({
    version: 'v1',
    auth: authClient,
  });
  const res = await forms.forms.watches.delete({
    formId: formID,
    watchId: watchID,
  });
  console.log(res.data);
  return res.data;
}

if (module === require.main) {
  runSample().catch(console.error);
}
module.exports = runSample;

التفويض

مثل جميع طلبات البيانات من Forms API، يجب أن تتم الموافقة على طلبات البيانات من watches.create() باستخدام رمز مميّز للموافقة. يجب أن يتضمّن الرمز المميّز نطاقًا يمنح إذن قراءة للوصول إلى البيانات المتعلّقة بالإشعارات التي يتم إرسالها.

• بالنسبة إلى تغييرات المخطط، يعني ذلك أي نطاق يمنح إذن الوصول للقراءة إلى forms باستخدام forms.get().
• بالنسبة إلى الردود، يعني ذلك أي نطاق يمنح إذن الوصول للقراءة إلى الردود على النماذج، على سبيل المثال باستخدام forms.responses.list().

لكي يتم إرسال الإشعارات، يجب أن يحتفظ التطبيق بمنح OAuth من المستخدم المفوَّض بالنطاقات المطلوبة. إذا أوقف المستخدم ربط التطبيق، ستتوقف الإشعارات وقد يتم تعليق الساعة مع ظهور خطأ. لاستئناف تلقّي الإشعارات بعد استعادة التفويض، يُرجى الاطّلاع على مقالة تجديد اشتراك في خدمة "مراقبة الصحة".

إدراج ساعات النموذج

PythonNode.js

forms/snippets/list_watches.py

العرض على GitHub

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secrets.json", SCOPES)
  creds = tools.run_flow(flow, store)
service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

form_id = "<YOUR_FORM_ID>"

# Print JSON list of form watches
result = service.forms().watches().list(formId=form_id).execute()
print(result)

forms/snippets/list_watches.js

العرض على GitHub

'use strict';

const path = require('path');
const google = require('@googleapis/forms');
const {authenticate} = require('@google-cloud/local-auth');

const formID = '<YOUR_FORM_ID>';

async function runSample(query) {
  const auth = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/forms.responses.readonly',
  });
  const forms = google.forms({
    version: 'v1',
    auth: auth,
  });
  const res = await forms.forms.watches.list({formId: formID});
  console.log(res.data);
  return res.data;
}

if (module === require.main) {
  runSample().catch(console.error);
}
module.exports = runSample;

تجديد اشتراك في ساعة

PythonNode.js

forms/snippets/renew_watch.py

العرض على GitHub

from apiclient import discovery
from httplib2 import Http
from oauth2client import client, file, tools

SCOPES = "https://www.googleapis.com/auth/drive"
DISCOVERY_DOC = "https://forms.googleapis.com/$discovery/rest?version=v1"

store = file.Storage("token.json")
creds = None
if not creds or creds.invalid:
  flow = client.flow_from_clientsecrets("client_secrets.json", SCOPES)
  creds = tools.run_flow(flow, store)
service = discovery.build(
    "forms",
    "v1",
    http=creds.authorize(Http()),
    discoveryServiceUrl=DISCOVERY_DOC,
    static_discovery=False,
)

form_id = "<YOUR_FORM_ID>"
watch_id = "<YOUR_WATCH_ID>"

# Print JSON response after renewing a form watch
result = (
    service.forms().watches().renew(formId=form_id, watchId=watch_id).execute()
)
print(result)

forms/snippets/renew_watch.js

العرض على GitHub

'use strict';

const path = require('path');
const google = require('@googleapis/forms');
const {authenticate} = require('@google-cloud/local-auth');

const formID = '<YOUR_FORM_ID>';
const watchID = '<YOUR_FORMS_WATCH_ID>';

async function runSample(query) {
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const forms = google.forms({
    version: 'v1',
    auth: authClient,
  });
  const res = await forms.forms.watches.renew({
    formId: formID,
    watchId: watchID,
  });
  console.log(res.data);
  return res.data;
}

if (module === require.main) {
  runSample().catch(console.error);
}
module.exports = runSample;

التقييد

يتمّ الحدّ من عدد الإشعارات التي يتمّ إرسالها، إذ يمكن أن تتلقّى كلّ ساعة إشعارًا واحدًا كحدّ أقصى كلّ ثلاثين ثانية. يخضع هذا الحدّ الأدنى لعدد مرّات الظهور للتغيير.

بسبب الحدّ من عدد الإشعارات، قد يرتبط إشعار واحد بأحداث متعدّدة. بعبارة أخرى، يشير الإشعار إلى وقوع حدث واحد أو أكثر منذ الإشعار الأخير.

الحدود

في أي وقت، يمكن أن يتضمّن كل مشروع على Cloud Console ، لنموذج ونوع حدث معيّنين، ما يلي:

• ما يصل إلى 20 ساعة في المجمل
• ساعة واحدة كحد أقصى لكل مستخدم نهائي

بالإضافة إلى ذلك، يقتصر كل نموذج في أي وقت على 50 ساعة لكل نوع حدث في المجموع على مستوى جميع مشاريع Cloud Console.

ترتبط الساعة بمستخدم نهائي عند إنشائها أو تجديدها باستخدام بيانات اعتماد هذا المستخدم. يتم تعليق المراقبة إذا فقد المستخدم النهائي المرتبط إمكانية الوصول إلى النموذج أو ألغى إذن وصول التطبيق إلى النموذج.

الموثوقية

يتم إرسال إشعار إلى كل ساعة مرة واحدة على الأقل بعد كل حدث في جميع الحالات باستثناء الظروف الاستثنائية. في الغالبية العظمى من الحالات، يتم إرسال إشعار في غضون دقائق من وقوع الحدث.

الأخطاء

إذا تعذّر باستمرار تسليم الإشعارات لساعة، تصبح حالة الساعة SUSPENDED ويتم ضبط الحقل errorType للساعة. لإعادة ضبط حالة الساعة المعلّقة إلى ACTIVE واستئناف تلقّي الإشعارات، يُرجى الاطّلاع على مقالة تجديد ساعة.

الاستخدام المقترَح

• استخدِم موضوعًا واحدًا في Cloud Pub/Sub كهدف للعديد من عمليات المراقبة.
• عند تلقّي إشعار بشأن موضوع معيّن، يتم تضمين معرّف النموذج في ملف حمولة الإشعار. استخدِم هذا المقياس مع نوع الحدث لمعرفة البيانات التي يجب جلبها والنموذج الذي يجب جلبها منه.
• لجلب البيانات المعدَّلة بعد تلقّي إشعار يتضمّن EventType.RESPONSES، يمكنك استدعاء forms.responses.list().
  • اضبط الفلتر في الطلب على timestamp > timestamp_of_the_last_response_you_fetched.
• لجلب البيانات المعدَّلة بعد إشعار يتضمّن EventType.SCHEMA، يمكنك استدعاء forms.get().