Halaman ini diterjemahkan oleh Cloud Translation API.

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 perlu menyiapkan topik Cloud Pub/Sub dan memberikan nama topik tersebut saat membuat pemantauan 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 masa berlaku pengamatan berakhir. Smartwatch Anda bertahan selama seminggu, 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 ditonton, notifikasi tidak akan lagi dikirim.

Jenis peristiwa 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 memberi tahu saat respons formulir (baru dan diperbarui) dikirimkan.

Respons notifikasi

Notifikasi dienkode dengan JSON dan berisi:

ID formulir pemicu
ID smartwatch yang memicu
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 web hook, atau dengan melakukan polling pada endpoint langganan.

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

Selesaikan Prasyarat Cloud Pub/Sub.
Menyiapkan klien Cloud Pub/Sub.
Tinjau harga Cloud Pub/Sub, dan aktifkan penagihan untuk project Developer Console Anda.
Buat topik Cloud Pub/Sub dengan salah satu dari tiga cara berikut:
- menggunakan Konsol Play (paling mudah)
- menggunakan alat command line (untuk penggunaan terprogram sederhana) atau
- menggunakan Cloud Pub/Sub API.
Catatan: Cloud Pub/Sub hanya mengizinkan jumlah topik terbatas, sehingga menggunakan satu topik untuk menerima semua notifikasi akan memastikan Anda tidak mengalami masalah penskalaan jika aplikasi Anda menjadi populer.
Buat Langganan di Cloud Pub/Sub untuk memberi tahu Cloud Pub/Sub cara mengirimkan notifikasi Anda.
Terakhir, sebelum membuat pengamatan yang menargetkan topik, Anda harus memberikan izin ke akun layanan notifikasi Formulir (forms-notifications@system.gserviceaccount.com) 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 disediakan dapat dijangkau oleh akun layanan notifikasi push, dan gagal jika tidak dapat menjangkau topik; misalnya, jika topik tidak ada atau Anda belum memberinya izin publikasi pada topik tersebut.

PythonNode.js

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)

forms/snippets/create_watch.js

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

Menghapus smartwatch

PythonNode.js

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)

forms/snippets/delete_watch.js

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

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 diberi otorisasi 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 Memperpanjang smartwatch.

Mencantumkan jam formulir

PythonNode.js

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)

forms/snippets/list_watches.js

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

Memperpanjang masa berlaku smartwatch

PythonNode.js

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)

forms/snippets/renew_watch.js

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

Throttling

Notifikasi dibatasi—setiap smartwatch dapat menerima maksimal satu notifikasi setiap tiga puluh detik. Nilai minimum frekuensi ini dapat berubah sewaktu-waktu.

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

Batas

Kapan saja, untuk jenis formulir dan peristiwa tertentu, setiap project Konsol Cloud dapat memiliki:

total hingga 20 sesi tonton
hingga satu smartwatch per pengguna akhir

Selain itu, setiap formulir dibatasi hingga 50 pengamatan per jenis peristiwa secara total di seluruh project Cloud Console.

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

Keandalan

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

Error

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

Saran penggunaan

Menggunakan satu topik Cloud Pub/Sub sebagai target dari banyak watch.
Saat menerima notifikasi tentang suatu topik, ID formulir akan disertakan dalam payload notifikasi. Gunakan dengan jenis peristiwa untuk mengetahui data yang akan diambil dan formulir tempat data 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().