ตั้งค่าและรับข้อความ Push

คุณสามารถใช้วิธีการในคอลเล็กชัน Watches เพื่อ รับการแจ้งเตือนเมื่อข้อมูลในแบบฟอร์มมีการเปลี่ยนแปลง หน้านี้ให้ภาพรวมเชิงแนวคิดและวิธีการตั้งค่าและรับการแจ้งเตือนแบบพุช

ภาพรวม

ฟีเจอร์ข้อความ Push ของ Google Forms API ช่วยให้แอปพลิเคชันสมัครรับการแจ้งเตือนได้เมื่อมีการเปลี่ยนแปลงข้อมูลในแบบฟอร์ม ระบบจะส่งการแจ้งเตือนไปยังหัวข้อ Cloud Pub/Sub โดยปกติภายในไม่กี่นาทีหลังจากการเปลี่ยนแปลง

หากต้องการรับการแจ้งเตือนแบบพุช คุณต้องตั้งค่าหัวข้อ Cloud Pub/Sub และ ระบุชื่อหัวข้อนั้นเมื่อสร้างการดูสำหรับประเภทเหตุการณ์ที่เหมาะสม

ด้านล่างนี้คือคำจำกัดความของแนวคิดหลักที่ใช้ในเอกสารนี้

• เป้าหมายคือที่ที่ระบบส่งการแจ้งเตือน เป้าหมายที่รองรับมีเพียงหัวข้อ Cloud Pub/Sub เท่านั้น
• ประเภทเหตุการณ์คือหมวดหมู่ของการแจ้งเตือนที่แอปพลิเคชันของบุคคลที่สาม สามารถสมัครรับข้อมูลได้
• การดูคือคำสั่งที่ส่งไปยัง Forms API เพื่อส่งการแจ้งเตือนสำหรับประเภทเหตุการณ์ที่เฉพาะเจาะจงในแบบฟอร์มที่เฉพาะเจาะจงไปยังเป้าหมาย

เมื่อสร้างการดูประเภทเหตุการณ์ในแบบฟอร์มหนึ่งๆ แล้ว เป้าหมายของการดูนั้น (ซึ่งเป็นหัวข้อ Cloud Pub/Sub) จะได้รับการแจ้งเตือนจากเหตุการณ์เหล่านั้นในแบบฟอร์มนั้นจนกว่าการดูจะหมดอายุ โดยใบรับรองจะอยู่ได้ 1 สัปดาห์ แต่คุณขยายเวลาได้ทุกเมื่อก่อนที่ใบรับรองจะหมดอายุโดยส่งคำขอไปที่ watches.renew()

หัวข้อ Cloud Pub/Sub จะได้รับการแจ้งเตือนเกี่ยวกับแบบฟอร์มที่คุณดูได้ด้วยข้อมูลเข้าสู่ระบบที่คุณระบุเท่านั้น เช่น หากผู้ใช้เพิกถอน สิทธิ์จากแอปพลิเคชันของคุณหรือสูญเสียสิทธิ์เข้าถึงระดับแก้ไขในแบบฟอร์มที่ดูอยู่ ระบบจะไม่ส่งการแจ้งเตือนอีก

ประเภทเหตุการณ์ที่ใช้ได้

ปัจจุบัน Google Forms API มีเหตุการณ์ 2 หมวดหมู่ดังนี้

• 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 และเปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ Developer Console

4. สร้างหัวข้อ Cloud Pub/Sub ได้ 3 วิธีดังนี้

   • ใช้Developer Console (ง่ายที่สุด)
   • การใช้ เครื่องมือบรรทัดคำสั่ง (สำหรับการใช้งานแบบเป็นโปรแกรมอย่างง่าย) หรือ
   • โดยใช้ Cloud Pub/Sub API
   หมายเหตุ: Cloud Pub/Sub อนุญาตให้ใช้หัวข้อจำนวนจำกัดเท่านั้น ดังนั้น การใช้หัวข้อเดียวเพื่อรับการแจ้งเตือนทั้งหมดจะช่วยให้คุณไม่ พบปัญหาการปรับขนาดหากแอปพลิเคชันได้รับความนิยม

5. สร้างการสมัครใช้บริการใน Cloud Pub/Sub เพื่อบอก Cloud Pub/Sub วิธีส่งการแจ้งเตือน

6. สุดท้ายนี้ ก่อนที่จะสร้างการดูที่กำหนดเป้าหมายไปยังหัวข้อ คุณต้อง ให้สิทธิ์ แก่บัญชีบริการการแจ้งเตือนของฟอร์ม ([e-mail]) เพื่อเผยแพร่ไปยังหัวข้อ

สร้างการดู

เมื่อมีหัวข้อที่บัญชีบริการข้อความ Push ของ 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;
}

การควบคุม

ระบบจะจำกัดจำนวนการแจ้งเตือน โดยนาฬิกาแต่ละเรือนจะได้รับการแจ้งเตือนอย่างน้อย 1 รายการ ทุกๆ 30 วินาที เกณฑ์ความถี่นี้อาจมีการเปลี่ยนแปลง

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

จำกัดสูงสุด

โปรเจ็กต์ Cloud Console แต่ละโปรเจ็กต์ จะมีสิ่งต่อไปนี้ได้ทุกเมื่อสำหรับแบบฟอร์มและประเภทกิจกรรมที่กำหนด

• ดูได้สูงสุด 20 ครั้ง
• ดูได้สูงสุด 1 เครื่องต่อผู้ใช้ปลายทาง

นอกจากนี้ แต่ละแบบฟอร์มจะจำกัดการดู 50 ครั้งต่อประเภทเหตุการณ์ใน ทั้งหมดในโปรเจ็กต์ Cloud Console ทั้งหมดได้ทุกเมื่อ

ระบบจะเชื่อมโยงนาฬิกากับผู้ใช้ปลายทางเมื่อมีการสร้างหรือต่ออายุด้วย ข้อมูลเข้าสู่ระบบสำหรับผู้ใช้รายนั้น ระบบจะระงับนาฬิกาหากผู้ใช้ปลายทางที่เชื่อมโยง สูญเสียสิทธิ์เข้าถึงแบบฟอร์มหรือเพิกถอนสิทธิ์เข้าถึงแบบฟอร์มของแอป

ความน่าเชื่อถือ

นาฬิกาแต่ละเรือนจะได้รับการแจ้งเตือนอย่างน้อย 1 ครั้งหลังจากแต่ละเหตุการณ์ในทุกกรณี ยกเว้น สถานการณ์พิเศษ ในกรณีส่วนใหญ่ ระบบจะส่งการแจ้งเตือน ภายในไม่กี่นาทีหลังจากเกิดเหตุการณ์

ข้อผิดพลาด

หากระบบส่งการแจ้งเตือนไปยังนาฬิกาไม่สำเร็จอย่างต่อเนื่อง สถานะของนาฬิกาจะเปลี่ยนเป็น SUSPENDED และมีการตั้งค่าฟิลด์ errorType ของนาฬิกา หากต้องการรีเซ็ตสถานะของนาฬิกาที่ถูกระงับเป็น ACTIVE และรับการแจ้งเตือนต่อ โปรดดูต่ออายุนาฬิกา

การใช้งานที่แนะนำ

• ใช้หัวข้อ Cloud Pub/Sub เดียวเป็นเป้าหมายของการดูหลายรายการ
• เมื่อได้รับการแจ้งเตือนเกี่ยวกับหัวข้อหนึ่งๆ รหัสแบบฟอร์มจะรวมอยู่ใน เพย์โหลดการแจ้งเตือน ใช้กับประเภทเหตุการณ์เพื่อดูว่าควรดึงข้อมูลใด และดึงข้อมูลจากรูปแบบใด
• หากต้องการดึงข้อมูลที่อัปเดตหลังจากได้รับการแจ้งเตือนที่มี EventType.RESPONSES ให้เรียกใช้ forms.responses.list()
  • ตั้งค่าตัวกรองในคำขอเป็น timestamp > timestamp_of_the_last_response_you_fetched
• หากต้องการดึงข้อมูลที่อัปเดตแล้วหลังจากได้รับการแจ้งเตือนที่มี EventType.SCHEMA ให้เรียกใช้ forms.get()