Menyiapkan dan menerima notifikasi push

Anda dapat menggunakan metode dalam koleksi Watches untuk menerima notifikasi saat data berubah dalam formulir. Halaman ini memberikan ringkasan konseptual dan petunjuk untuk menyiapkan dan menerima notifikasi push.

Ringkasan

Fitur notifikasi push Google Forms API memungkinkan aplikasi berlangganan notifikasi saat data berubah dalam formulir. Notifikasi dikirim ke topik Cloud Pub/Sub, biasanya dalam beberapa menit setelah perubahan.

Untuk menerima notifikasi push, Anda harus menyiapkan topik Cloud Pub/Sub dan memberikan nama topik tersebut saat membuat pengamatan untuk jenis peristiwa yang sesuai.

Berikut adalah definisi konsep utama yang digunakan dalam dokumentasi ini:

• Target adalah tempat notifikasi dikirim. Satu-satunya target yang didukung adalah topik Cloud Pub/Sub.
• Jenis peristiwa adalah kategori notifikasi yang dapat diikuti oleh aplikasi pihak ketiga.
• Pemantauan adalah petunjuk ke Forms API untuk mengirimkan notifikasi untuk jenis peristiwa tertentu pada formulir tertentu ke target.

Setelah Anda membuat pengamatan untuk jenis peristiwa pada formulir tertentu, target pengamatan tersebut (yang merupakan topik Cloud Pub/Sub) akan menerima notifikasi dari peristiwa tersebut pada formulir tersebut hingga pengamatan berakhir. Masa berlaku smartwatch Anda adalah satu minggu, tetapi Anda dapat memperpanjangnya kapan saja sebelum masa berlakunya berakhir dengan membuat permintaan ke watches.renew().

Topik Cloud Pub/Sub Anda hanya menerima notifikasi tentang formulir yang dapat Anda lihat dengan kredensial yang Anda berikan. Misalnya, jika pengguna mencabut izin dari aplikasi Anda atau kehilangan akses edit ke formulir yang dipantau, notifikasi tidak akan dikirim lagi.

Jenis acara yang tersedia

Google Forms API saat ini menawarkan dua kategori peristiwa:

• EventType.SCHEMA, yang memberi tahu tentang pengeditan pada konten dan setelan formulir.
• EventType.RESPONSES, yang memberikan notifikasi saat jawaban formulir (baru dan diperbarui) dikirimkan.

Respons notifikasi

Notifikasi dienkode dengan JSON dan berisi:

• ID formulir pemicu
• ID pengamatan pemicu
• Jenis peristiwa yang memicu notifikasi
• Kolom lain yang ditetapkan oleh Cloud Pub/Sub, seperti messageId dan publishTime

Notifikasi tidak berisi data formulir atau respons yang mendetail. Setelah setiap notifikasi diterima, panggilan API terpisah diperlukan untuk mengambil data baru. Lihat Penggunaan yang disarankan untuk mengetahui cara melakukannya.

Cuplikan berikut menunjukkan contoh notifikasi untuk perubahan skema:

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

Cuplikan berikut menunjukkan contoh notifikasi untuk respons baru:

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

Menyiapkan topik Cloud Pub/Sub

Notifikasi dikirim ke topik Cloud Pub/Sub. Dari Cloud Pub/Sub, Anda dapat menerima notifikasi di webhook, atau dengan melakukan polling pada endpoint langganan.

Untuk menyiapkan topik Cloud Pub/Sub, lakukan hal berikut:

1. Selesaikan Prasyarat Cloud Pub/Sub.
2. Siapkan klien Cloud Pub/Sub.
3. Tinjau harga Cloud Pub/Sub, dan aktifkan penagihan untuk project Konsol Developer Anda.

4. Buat topik Cloud Pub/Sub dengan salah satu dari tiga cara:

   • menggunakan Konsol Developer (paling mudah)
   • menggunakan alat command line (untuk penggunaan terprogram sederhana) atau
   • menggunakan Cloud Pub/Sub API.
   Catatan: Cloud Pub/Sub hanya mengizinkan sejumlah topik terbatas, jadi menggunakan satu topik untuk menerima semua notifikasi memastikan Anda tidak mengalami masalah penskalaan jika aplikasi Anda menjadi populer.

5. Buat Langganan di Cloud Pub/Sub untuk memberi tahu Cloud Pub/Sub cara mengirimkan notifikasi Anda.

6. Terakhir, sebelum membuat watch yang menargetkan topik, Anda perlu memberikan izin ke akun layanan notifikasi Formulir ([e-mail]) untuk memublikasikan ke topik Anda.

Membuat smartwatch

Setelah memiliki topik yang dapat dipublikasikan oleh akun layanan notifikasi push Forms API, Anda dapat membuat notifikasi menggunakan metode watches.create(). Metode ini memvalidasi bahwa topik Cloud Pub/Sub yang diberikan dapat dijangkau oleh akun layanan push notification, dan akan gagal jika tidak dapat menjangkau topik; misalnya, jika topik tidak ada atau Anda belum memberikan izin publikasikan pada topik tersebut.

Python

forms/snippets/create_watch.py

Lihat di 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

Lihat di GitHub

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

const formID = '<YOUR_FORM_ID>';

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

Menghapus smartwatch

Python

forms/snippets/delete_watch.py

Lihat di 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

Lihat di GitHub

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

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

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

Otorisasi

Seperti semua panggilan ke Forms API, panggilan ke watches.create() harus diotorisasi dengan token otorisasi. Token harus menyertakan cakupan yang memberikan akses baca ke data tentang notifikasi yang dikirim.

• Untuk perubahan skema, hal ini berarti cakupan apa pun yang memberikan akses baca ke formulir menggunakan forms.get().
• Untuk respons, ini berarti cakupan apa pun yang memberikan akses baca ke respons formulir, misalnya menggunakan forms.responses.list().

Agar notifikasi dapat dikirim, aplikasi harus mempertahankan pemberian OAuth dari pengguna yang berwenang dengan cakupan yang diperlukan. Jika pengguna memutuskan koneksi aplikasi, notifikasi akan berhenti dan smartwatch dapat ditangguhkan dengan error. Untuk melanjutkan notifikasi setelah mendapatkan kembali otorisasi, lihat Memperbarui smartwatch.

Mencantumkan smartwatch formulir

Python

forms/snippets/list_watches.py

Lihat di 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

Lihat di GitHub

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

const formID = '<YOUR_FORM_ID>';

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

Memperpanjang masa berlaku smartwatch

Python

forms/snippets/renew_watch.py

Lihat di 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

Lihat di GitHub

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

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

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

Throttling

Notifikasi dibatasi—setiap smartwatch dapat menerima paling banyak satu notifikasi setiap tiga puluh detik. Nilai minimum frekuensi ini dapat berubah.

Karena pembatasan, satu notifikasi dapat sesuai dengan beberapa peristiwa. Dengan kata lain, notifikasi menunjukkan bahwa satu atau beberapa peristiwa telah terjadi sejak notifikasi terakhir.

Batas

Setiap saat, untuk jenis formulir dan peristiwa tertentu, setiap project Konsol Cloud dapat memiliki:

• hingga total 20 sesi tonton
• hingga satu smartwatch per pengguna akhir

Selain itu, setiap formulir dibatasi hingga 50 pengamatan per jenis peristiwa secara total di semua project Konsol Cloud kapan saja.

Smartwatch dikaitkan dengan pengguna akhir saat dibuat atau diperpanjang dengan kredensial untuk pengguna tersebut. Smartwatch ditangguhkan jika pengguna akhir terkait kehilangan akses ke formulir atau mencabut akses aplikasi ke formulir.

Keandalan

Setiap smartwatch diberi tahu setidaknya sekali setelah setiap acara dalam semua keadaan, kecuali keadaan luar biasa. Dalam sebagian besar kasus, notifikasi dikirimkan dalam hitungan menit setelah peristiwa terjadi.

Error

Jika notifikasi untuk smartwatch terus gagal dikirim, status smartwatch akan menjadi SUSPENDED dan kolom errorType smartwatch akan disetel. Untuk mereset status smartwatch yang ditangguhkan ke ACTIVE dan melanjutkan notifikasi, lihat Memperbarui masa berlaku smartwatch.

Penggunaan yang disarankan

• Gunakan satu topik Cloud Pub/Sub sebagai target banyak pengamatan.
• Saat menerima notifikasi tentang suatu topik, ID formulir disertakan dalam payload notifikasi. Gunakan dengan jenis peristiwa untuk mengetahui data yang akan diambil dan formulir yang akan diambil.
• Untuk mengambil data yang diperbarui setelah notifikasi dengan EventType.RESPONSES, panggil forms.responses.list().
  • Tetapkan filter pada permintaan ke timestamp > timestamp_of_the_last_response_you_fetched.
• Untuk mengambil data yang diperbarui setelah notifikasi dengan EventType.SCHEMA, panggil forms.get().