Push bildirimlerini ayarlama ve alma

Formlarda veri değişiklikleri olduğunda bildirim almak için Saatler koleksiyonundaki yöntemleri kullanabilirsiniz. Bu sayfada, push bildirimlerini ayarlamak ve almak için kavramsal bir genel bakış ve talimatlar sunulmaktadır.

Genel bakış

Google Formlar API'nin push bildirimleri özelliği, formlarda veri değişiklikleri olduğunda uygulamaların bildirimlere abone olmasına olanak tanır. Bildirimler, genellikle değişiklikten birkaç dakika sonra bir Cloud Pub/Sub konusuna gönderilir.

Push bildirimleri almak için bir Cloud Pub/Sub konusu oluşturmanız ve uygun etkinlik türü için bir saat oluşturduğunuzda bu konunun adını sağlamanız gerekir.

Bu dokümanlarda kullanılan temel kavramların tanımları aşağıda verilmiştir:

• Hedef, bildirimlerin gönderildiği bir yerdir. Desteklenen tek hedef bir Cloud Pub/Sub konusudur.
• Etkinlik türü, üçüncü taraf bir uygulamanın abone olabileceği bir bildirim kategorisidir.
• Saat, belirli bir formdaki belirli bir etkinlik türüne ilişkin bildirimleri bir hedefe göndermek için Formlar API'sine yönelik bir talimattır.

Belirli bir formda bir etkinlik türü için saat oluşturduğunuzda, bu saatin hedefi (bir Cloud Pub/Sub konusudur), saatin süresi dolana kadar bu formdaki etkinliklerden bildirimler alır. Kol saatinizin kullanım süresi bir haftadır ancak watches.renew() için istekte bulunarak geçerlilik süresini dolmadan önce dilediğiniz zaman uzatabilirsiniz.

Cloud Pub/Sub konunuz, yalnızca sağladığınız kimlik bilgileriyle görüntüleyebileceğiniz formlarla ilgili bildirimleri alır. Örneğin, kullanıcı, uygulamanızdaki izni iptal ederse veya izlenen bir forma düzenleme erişimini kaybederse bildirimler gönderilmez.

Kullanılabilir etkinlik türleri

Google Formlar API şu anda iki etkinlik kategorisi sunmaktadır:

• EventType.SCHEMA, bir formun içerik ve ayarlarında yapılan düzenlemeler hakkında bildirim gönderir.
• EventType.RESPONSES API'si, form yanıtları (hem yeni hem de güncellenmiş) gönderildiğinde bildirim alır.

Bildirim yanıtları

Bildirimler JSON ile kodlanır ve şunları içerir:

• Tetikleyen formun kimliği
• Tetikleyen saatin kimliği
• Bildirimi tetikleyen etkinliğin türü
• messageId ve publishTime gibi Cloud Pub/Sub tarafından ayarlanan diğer alanlar

Bildirimler, ayrıntılı form veya yanıt verileri içermez. Her bildirim alındıktan sonra, yeni verileri getirmek için ayrı bir API çağrısı gerekir. Bunun nasıl yapılacağını öğrenmek için Önerilen kullanım bölümüne bakın.

Aşağıdaki snippet'te, bir şema değişikliği için örnek bildirim gösterilmektedir:

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

Aşağıdaki snippet'te yeni bir yanıt için örnek bildirim gösterilmektedir:

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

Cloud Pub/Sub konusu oluşturma

Bildirimler, Cloud Pub/Sub konularına iletilir. Cloud Pub/Sub'dan bir web kancası üzerinde veya bir abonelik uç noktasını yoklayarak bildirim alabilirsiniz.

Cloud Pub/Sub konusu oluşturmak için aşağıdakileri yapın:

1. Cloud Pub/Sub Ön Koşulları'nı tamamlayın.
2. Cloud Pub/Sub istemcisi kurun.
3. Cloud Pub/Sub fiyatlandırmasını inceleyin ve Developer Console projeniz için faturalandırmayı etkinleştirin.

4. Aşağıdaki üç yöntemden birini kullanarak bir Cloud Pub/Sub konusu oluşturun:

   • Developer Console'u kullanarak (en kolay)
   • komut satırı aracını (basit programatik kullanım için) veya
   • Cloud Pub/Sub API'den yararlanın.
   Not: Cloud Pub/Sub'da yalnızca sınırlı sayıda konuya izin verilir. Bu nedenle, tüm bildirimlerinizi almak için tek bir konu kullanmanız, uygulamanız popüler hale geldiğinde ölçeklendirme sorunları yaşamamanızı sağlar.

5. Cloud Pub/Sub'a bildirimlerinizi nasıl ileteceğini bildirmek için Cloud Pub/Sub'da bir Abonelik oluşturun.

6. Son olarak, konunuzu hedefleyen saatler oluşturmadan önce, konunuza içerik yayınlamak için Formlar bildirimleri hizmet hesabına ([e-mail]) izin vermeniz gerekir.

Kol saati oluştur

Formlar API push bildirimleri hizmet hesabının yayınlayabileceği bir konu belirledikten sonra watches.create() yöntemini kullanarak bildirim oluşturabilirsiniz. Bu yöntem, sağlanan Cloud Pub/Sub konusuna push bildirimleri hizmet hesabı tarafından erişilebildiğini ve konunun konuya erişememesi durumunda (ör. konu yoksa veya bu konuda yayınlama izni vermediyseniz) başarısız olduğunu doğrular.

Python

forms/snippets/create_watch.py

GitHub'da göster

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'da göster

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

Kol saatini silme

Python

forms/snippets/delete_watch.py

GitHub'da göster

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

formlar/snippet'ler/delete_watch.js

GitHub'da göster

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

Yetkilendirme

Formlar API'ye yapılan tüm çağrılar gibi watches.create() çağrıları da bir yetkilendirme jetonuyla yetkilendirilmelidir. Jeton, hangi bildirimlerin gönderildiği ilgili verilere okuma erişimi veren bir kapsam içermelidir.

• Şema değişiklikleri için bu, forms.get() aracılığıyla formlara okuma erişimi veren tüm kapsamlar anlamına gelir.
• Yanıtlar için bu, form yanıtlarına (örneğin forms.responses.list() aracılığıyla) okuma erişimi veren tüm kapsamlar anlamına gelir.

Bildirimlerin teslim edilmesi için uygulamanın, yetkili kullanıcıdan gerekli kapsamlara sahip OAuth iznini saklaması gerekir. Kullanıcı uygulamanın bağlantısını keserse bildirimler durdurulur ve saat bir hata nedeniyle askıya alınabilir. Yetkilendirmeyi yeniden kazandıktan sonra bildirimleri devam ettirmek için Saati yenileme bölümüne bakın.

Bir formun izlenme sayısını listeleme

Python

formlar/snippet'ler/list_watches.py

GitHub'da göster

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

formlar/snippet'ler/list_watches.js

GitHub'da göster

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

Kol saatini yenileme

Python

forms/snippets/renew_watch.py

GitHub'da göster

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

formlar/snippet'ler/renew_watch.js

GitHub'da göster

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

Kısıtlama

Bildirimler kısıtlanır. Her saat her otuz saniyede en fazla bir bildirim alabilir. Bu sıklık eşiği değiştirilebilir.

Kısıtlama nedeniyle tek bir bildirim birden fazla etkinliğe karşılık gelebilir. Diğer bir deyişle bildirim, son bildirimden bu yana bir veya daha fazla etkinliğin gerçekleştiğini belirtir.

Sınırlar

Her Cloud Console projesi, belirli bir form ve etkinlik türü için herhangi bir zamanda şunları içerebilir:

• toplam 20 saate kadar
• son kullanıcı başına en fazla bir saat

Ayrıca herhangi bir zamanda, tüm Cloud Console projelerinde her form etkinlik türü başına toplam 50 izlemeyle sınırlıdır.

Kol saati, oluşturulduğunda veya bu kullanıcının kimlik bilgileriyle yenilendiğinde son kullanıcıyla ilişkilendirilir. İlişkili son kullanıcı forma erişimini kaybeder veya uygulamanın forma erişimini iptal ederse saat askıya alınır.

Güvenilirlik

Olağanüstü durumlar dışındaki tüm durumlarda, her etkinlikten sonra her kol saatine en az bir kez bildirim gönderilir. Vakaların büyük çoğunluğunda, bildirim bir etkinlikten dakika sonra teslim edilir.

Hatalar

Bir saatin bildirimleri kalıcı olarak teslim edilemezse saat durumu SUSPENDED olur ve kol saatinin errorType alanı ayarlanır. Askıya alınmış bir saatin durumunu ACTIVE olarak sıfırlamak ve bildirimleri devam ettirmek için Saati yenileme konusuna bakın.

Önerilen kullanım

• Çok sayıda saatin hedefi olarak tek bir Cloud Pub/Sub konusu kullanma.
• Bir konuyla ilgili bildirim alınırken, form kimliği bildirim yüküne dahil edilir. Hangi verilerin, hangi formdan getirileceğini bilmek için bunu etkinlik türüyle birlikte kullanın.
• EventType.RESPONSES ile gönderilen bir bildirimden sonra güncellenen verileri getirmek için forms.responses.list() çağrısı yapın.
  • İstekteki filtreyi timestamp > timestamp_of_the_last_response_you_fetched olarak ayarlayın.
• EventType.SCHEMA ile gönderilen bir bildirimden sonra güncellenen verileri getirmek için forms.get() çağrısı yapın.