הגדרה וקבלה של התראות

אפשר להשתמש בשיטות באוסף Watches כדי לקבל התראות כשנתונים בטפסים משתנים. בדף הזה מופיעה סקירה כללית של מושגים והוראות להגדרה ולקבלת התראות פוש.

סקירה כללית

התכונה 'התראות בדחיפה' ב-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

ההתראות לא מכילות נתונים מפורטים של טפסים או תשובות. אחרי שמתקבלת כל הודעה, צריך לשלוח קריאה נפרדת ל-API כדי לאחזר נתונים עדכניים. הסבר איך לעשות זאת מופיע במאמר הצעות לשימוש.

בקטע הקוד הבא מוצגת דוגמה להתראה על שינוי בסכימה:

{
  "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, אפשר לקבל התראות ב-webhook, או על ידי שליחת שאילתות לנקודת קצה של מינוי.

כדי להגדיר נושא ב-Cloud Pub/Sub:

1. משלימים את הדרישות המוקדמות ל-Cloud Pub/Sub.
2. הגדרת לקוח Cloud Pub/Sub
3. מעיינים בתמחור של Cloud Pub/Sub ומפעילים את החיוב בפרויקט במסוף Google Cloud.

4. אפשר ליצור נושא ב-Cloud Pub/Sub באחת משלוש דרכים:

   • באמצעות מסוף Google Cloud
   • באמצעות כלי שורת הפקודה (לשימוש תוכניתי פשוט) או
   • באמצעות Cloud Pub/Sub API.
   הערה: ב-Cloud Pub/Sub אפשר להשתמש רק במספר מוגבל של נושאים, ולכן שימוש בנושא אחד לקבלת כל ההתראות מבטיח שלא תיתקלו בבעיות בהרחבת המערכת אם האפליקציה שלכם תהפוך לפופולרית.

5. יצירת מינוי ב-Cloud Pub/Sub כדי להגדיר ל-Cloud Pub/Sub איך לשלוח את ההתראות.

6. לבסוף, לפני שיוצרים שעונים שמכוונים לנושא, צריך להעניק הרשאה לחשבון השירות של התראות ב-Forms ‏([e-mail]) לפרסום בנושא.

יצירת שעון

אחרי שיש לכם נושא שחשבון השירות של שירות ההתראות של Forms API יכול לפרסם בו, אתם יכולים ליצור התראות באמצעות השיטה watches.create(). בשיטה הזו מתבצעת אימות של נושא Cloud Pub/Sub שסופק, כדי לוודא שחשבון השירות של שירות ההתראות בדחיפה יכול לגשת אליו. אם אין אפשרות לגשת לנושא, למשל אם הנושא לא קיים או שלא הענקתם לו הרשאת פרסום בנושא, האימות ייכשל.

Python

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)

Node.js

forms/snippets/create_watch.js

הצגת הקוד ב-GitHub

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';

/**
 * Creates a watch on a form to get notifications for new responses.
 */
async function createWatch() {
  // Authenticate with Google and get an authorized client.
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth: authClient,
  });

  // The request body to create a watch.
  const watchRequest = {
    watch: {
      target: {
        topic: {
          // TODO: Replace with a valid Cloud Pub/Sub topic name.
          topicName: 'projects/<YOUR_TOPIC_PATH>',
        },
      },
      // The event type to watch for. 'RESPONSES' is the only supported type.
      eventType: 'RESPONSES',
    },
  };

  // Send the request to create the watch.
  const result = await formsClient.forms.watches.create({
    formId: formID,
    requestBody: watchRequest,
  });

  console.log(result.data);
  return result.data;
}

מחיקת שעון

Python

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)

Node.js

forms/snippets/delete_watch.js

הצגת הקוד ב-GitHub

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';
// TODO: Replace with a valid watch ID.
const watchID = '<YOUR_FORMS_WATCH_ID>';

/**
 * Deletes a watch from a form.
 */
async function deleteWatch() {
  // Authenticate with Google and get an authorized client.
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth: authClient,
  });

  // Send the request to delete the watch.
  const result = await formsClient.forms.watches.delete({
    formId: formID,
    watchId: watchID,
  });

  console.log(result.data);
  return result.data;
}

אישור

בדומה לכל הקריאות ל-Forms API, הקריאות ל-watches.create() חייבות להיות מאושרות באמצעות אסימון הרשאה. האסימון צריך לכלול היקף הרשאות שמעניק גישת קריאה לנתונים שקשורים להודעות שנשלחות.

• במקרה של שינויים בסכימה, הכוונה היא לכל היקף שמעניק גישת קריאה לטפסים באמצעות forms.get().
• לגבי תגובות, המשמעות היא כל היקף שמעניק גישת קריאה לתגובות בטופס, למשל באמצעות forms.responses.list().

כדי שההתראות יועברו, האפליקציה צריכה לשמור מענק הרשאות OAuth מהמשתמש המורשה עם ההיקפים הנדרשים. אם המשתמש מנתק את האפליקציה, ההתראות מפסיקות והשעון עשוי להיות מושעה עם שגיאה. כדי לחדש את ההרשאה ולהמשיך לקבל התראות, אפשר לעיין במאמר בנושא חידוש הרשאה לצפייה.

הצגת רשימת הצפיות בטופס

Python

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)

Node.js

forms/snippets/list_watches.js

הצגת הקוד ב-GitHub

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';

/**
 * Lists the watches for a given form.
 */
async function listWatches() {
  // Authenticate with Google and get an authorized client.
  const auth = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/forms.responses.readonly',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth,
  });

  // Get the list of watches for the form.
  const result = await formsClient.forms.watches.list({
    formId: formID,
  });

  console.log(result.data);
  return result.data;
}

חידוש של שעון

Python

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)

Node.js

forms/snippets/renew_watch.js

הצגת הקוד ב-GitHub

import path from 'node:path';
import {authenticate} from '@google-cloud/local-auth';
import {forms} from '@googleapis/forms';

// TODO: Replace with a valid form ID.
const formID = '<YOUR_FORM_ID>';
// TODO: Replace with a valid watch ID.
const watchID = '<YOUR_FORMS_WATCH_ID>';

/**
 * Renews a watch on a form.
 */
async function renewWatch() {
  // Authenticate with Google and get an authorized client.
  const authClient = await authenticate({
    keyfilePath: path.join(__dirname, 'credentials.json'),
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Forms API client.
  const formsClient = forms({
    version: 'v1',
    auth: authClient,
  });

  // Send the request to renew the watch.
  const result = await formsClient.forms.watches.renew({
    formId: formID,
    watchId: watchID,
  });

  console.log(result.data);
  return result.data;
}

ויסות נתונים (throttle)

ההתראות מוגבלות – כל שעון יכול לקבל לכל היותר התראה אחת כל שלושים שניות. סף התדירות הזה עשוי להשתנות.

בגלל ההגבלה, התראה אחת יכולה להתייחס לכמה אירועים. במילים אחרות, התראה מציינת שהתרחשו אירוע אחד או יותר מאז ההתראה האחרונה.

מגבלות

בכל שלב, לכל פרויקט במסוף Cloud, עבור טופס וסוג אירוע נתונים, יכולים להיות:

• עד 20 צפיות בסך הכול
• עד צפייה אחת לכל משתמש קצה

בנוסף, בכל שלב, כל טופס מוגבל ל-50 צפיות לכל סוג אירוע בסך הכול בכל הפרויקטים ב-Cloud Console.

שעון משויך למשתמש קצה כשהוא נוצר או מחודש עם אישורים של אותו משתמש. הצפייה מושעית אם משתמש הקצה המשויך מאבד את הגישה לטופס או מבטל את הגישה של האפליקציה לטופס.

אמינות

כל שעון מקבל התראה לפחות פעם אחת אחרי כל אירוע, אלא אם מדובר בנסיבות חריגות. ברוב המקרים, ההתראה מועברת תוך דקות ספורות מהאירוע.

שגיאות

אם אי אפשר לשלוח התראות לשעון באופן עקבי, מצב השעון הופך לSUSPENDED והשדה errorType של השעון מוגדר. כדי לאפס את המצב של שעון מושעה ל-ACTIVE ולהמשיך לקבל התראות, אפשר לעיין במאמר חידוש שעון.

שימוש מומלץ

• אפשר להשתמש בנושא אחד ב-Cloud Pub/Sub כיעד של הרבה שעונים.
• כשמקבלים התראה בנושא מסוים, מזהה הטופס נכלל במטען הייעודי (Payload) של ההתראה. משתמשים בו עם סוג האירוע כדי לדעת אילו נתונים צריך לאחזר ומאיזה טופס לאחזר אותם.
• כדי לאחזר נתונים מעודכנים אחרי קבלת התראה עם EventType.RESPONSES, צריך להפעיל את forms.responses.list().
  • מגדירים את המסנן בבקשה ל-timestamp > timestamp_of_the_last_response_you_fetched.
• כדי לאחזר נתונים מעודכנים אחרי קבלת התראה עם EventType.SCHEMA, צריך להתקשר אל forms.get().