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

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

ภาพรวม

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

หากต้องการรับข้อความ Push คุณต้องตั้งค่าหัวข้อ 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 คุณจะรับการแจ้งเตือนในเว็บฮุก หรือโดยการพูลข้อมูลปลายทางการสมัครรับข้อมูลได้

หากต้องการตั้งค่าหัวข้อ Cloud Pub/Sub ให้ทําดังนี้

1. ทําตามข้อกําหนดเบื้องต้นของ Cloud Pub/Sub ให้เสร็จสมบูรณ์
2. ตั้งค่าไคลเอ็นต์ Cloud Pub/Sub
3. ตรวจสอบราคาของ Cloud Pub/Sub และเปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ใน Developer Console

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

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

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

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

สร้างนาฬิกา

เมื่อคุณมีหัวข้อที่บัญชีบริการข้อความ Push ของ Forms API สามารถเผยแพร่ได้ คุณสามารถสร้างการแจ้งเตือนได้โดยใช้เมธอด watches.create() เมธอดนี้จะตรวจสอบว่าบัญชีบริการข้อความ Push สามารถเข้าถึงหัวข้อ 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;

การให้สิทธิ์

การเรียกใช้ watches.create() ต้องได้รับอนุญาตด้วยโทเค็นการให้สิทธิ์ เช่นเดียวกับการเรียกใช้ Forms API ทั้งหมด โทเค็นต้องมีขอบเขตที่ให้สิทธิ์การอ่านข้อมูลเกี่ยวกับการแจ้งเตือนที่ส่ง

• สำหรับการเปลี่ยนแปลงสคีมา หมายถึงขอบเขตที่ให้สิทธิ์การอ่านแบบฟอร์มโดยใช้ 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;

การควบคุม

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

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

จำกัดสูงสุด

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

• นาฬิกาทั้งหมดไม่เกิน 20 เครื่อง
• นาฬิกาสูงสุด 1 เครื่องต่อผู้ใช้ปลายทาง 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()