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

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

ภาพรวม

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

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

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

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

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

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

ประเภทเหตุการณ์ที่มีอยู่

ขณะนี้ Google ฟอร์ม 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 ด้วย 1 ใน 3 วิธีต่อไปนี้

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

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

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

สร้างนาฬิกา

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

'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;

ลบนาฬิกา

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

form/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() จะต้องได้รับอนุญาตด้วยโทเค็นการให้สิทธิ์ เช่นเดียวกับการเรียกฟอร์ม API ทั้งหมด โดยโทเค็นต้องมีขอบเขตที่ให้สิทธิ์ในการอ่านข้อมูลที่มีการส่งการแจ้งเตือน

• สําหรับการเปลี่ยนแปลงสคีมา การดำเนินการนี้จะหมายถึงขอบเขตที่ให้สิทธิ์อ่านแบบฟอร์มผ่าน forms.get()
• สําหรับคำตอบ การดำเนินการนี้หมายถึงขอบเขตที่ให้สิทธิ์อ่านการตอบกลับแบบฟอร์ม เช่น ผ่าน forms.responses.list()

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

แสดงรายการนาฬิกาของแบบฟอร์ม

Python

form/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

form/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;

ต่ออายุนาฬิกา

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

form/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()