Google Classroom eklentileri artık geliştiricilerin genel kullanımına sunuldu! Daha fazla bilgi edinmek için lütfen eklenti belgelerini inceleyin.

Classroom API'deki push bildirimleri

Classroom'da veriler değiştiğinde bildirim almak için Registrations koleksiyonundaki yöntemleri kullanabilirsiniz.

Bu makalede, push bildirimleri almaya başlama konusunda basit talimatların yanı sıra kavramsal bir genel bakış sunulmaktadır.

Classroom push bildirimlerine genel bakış

Classroom API push bildirimleri özelliği, Classroom API'yi kullanan uygulamaların Classroom'daki veriler değiştiğinde bildirimlere abone olmasına olanak tanır. Bildirimler, değişikliğin yapılmasından genellikle birkaç dakika sonra Cloud Pub/Sub konusuna gönderilir.

Push bildirimi almak için Cloud Pub/Sub konusu oluşturmanız ve uygun bildirim feed'i için kayıt oluştururken bu konunun adını sağlamanız gerekir.

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

Hedef, bildirimlerin gönderildiği yerdir.
Feed, üçüncü taraf uygulamalarının abone olabileceği bir bildirim türüdür. Örneğin, "1234 numaralı kursun öğrenci listesindeki değişiklikler".
Kayıt, Classroom API'ye belirli bir feed'den gelen bildirimleri bir hedefe iletme talimatıdır.

Bir feed için kayıt oluşturduğunuzda, bu kaydın Cloud Pub/Sub konusu, geçerliliği sona erene kadar feed'den bildirim alır. Kaydınız bir hafta sürer ancak süresi dolmadan önce registrations.create() adresine aynı isteği göndererek süreyi uzatabilirsiniz.

Cloud Pub/Sub konunuz yalnızca kayıt oluştururken sağladığınız kimlik bilgileriyle görüntüleyebileceğiniz kaynaklarla ilgili bildirimleri alır. Örneğin, kullanıcı uygulamanızdan izni iptal ederse veya öğretmen olarak kaldırılırsa bildirimler artık gönderilmez.

Feed türleri

Classroom API üç tür feed sunar:

Her alanın alanda öğrenci listesi değişiklikleri feed'i vardır. Bu feed, öğrenciler ve öğretmenler ilgili alandaki derslere katıldığında ve derslerden ayrıldığında bildirimleri gösterir.
Her kursta, öğrencilerin ve öğretmenlerin kursa katılması ve kurstan ayrılması durumunda bildirimleri gösteren bir kurstaki öğrenci listesi değişiklikleri feed'i bulunur.
Her kursta, kursla ilgili sınıf çalışması değişiklikleri feed'i bulunur. Bu feed, ilgili kursta herhangi bir sınıf çalışması veya öğrenci gönderimi nesnesi oluşturulduğunda ya da değiştirildiğinde bildirimleri gösterir.

Cloud Pub/Sub konusu oluşturma

Bildirimler Cloud Pub/Sub konularına iletilir. Cloud Pub/Sub'dan, bir webhook'ta veya bir abonelik uç noktası yoklanarak bildirim alabilirsiniz.

Cloud Pub/Sub konusu oluşturmak için aşağıdakileri yapmanız gerekir:

Cloud Pub/Sub Ön Koşulları'nı karşıladığınızdan emin olun.
Cloud Pub/Sub istemcisi ayarlayın.
Cloud Pub/Sub fiyatlandırmasını inceleyin ve Developer Console projeniz için faturalandırmayı etkinleştirin.
Developer Console'da (en kolay yöntem), komut satırı aracıyla (basit programatik kullanım için) veya Cloud Pub/Sub API'yi kullanarak Cloud Pub/Sub konusu oluşturun. Cloud Pub/Sub'ın yalnızca sınırlı sayıda konuya izin verdiğini unutmayın. Bu nedenle, tüm bildirimlerinizi almak için tek bir konu kullanmak, uygulamanız popüler hale gelirse ölçeklendirme sorunlarıyla karşılaşmamanızı sağlar.
Cloud Pub/Sub'a bildirimlerinizi nasıl ileteceğini söylemek için Cloud Pub/Sub'da bir abonelik oluşturun.
Son olarak, anlık bildirimlere kaydolmadan önce Anlık Bildirimler hizmet hesabına (classroom-notifications@system.gserviceaccount.com) konunuza yayınlama izni vermeniz gerekir.

Uygulamanızı bildirimler için kaydetme

Classroom API push bildirimleri hizmet hesabının yayınlayabileceği bir konu belirledikten sonra registrations.create() yöntemini kullanarak bildirimlere kaydolabilirsiniz. registrations.create() yöntemi, sağlanan Cloud Pub/Sub konusuna anlık bildirim hizmet hesabı tarafından erişilebildiğini doğrular. Anlık bildirim hizmet hesabı konuya ulaşamıyorsa yöntem başarısız olur. Örneğin, konu mevcut değilse veya bu konuda yayınlama izni vermediyseniz.

Yetkilendirme

Classroom API'ye yapılan tüm çağrılar gibi, registrations.create() çağrıları da yetkilendirme jetonuyla registrations.create() yetkilendirilmelidir. Bu kimlik doğrulama jetonu, Push Notifications kapsamını (https://www.googleapis.com/auth/classroom.push-notifications) ve hangi bildirimlerin gönderildiğiyle ilgili verileri görüntülemek için gereken tüm kapsamları içermelidir.

Kadro değişikliği feed'leri için bu, Kadrolar kapsamı veya (ideal olarak) bunun salt okunur varyantı (https://www.googleapis.com/auth/classroom.rosters.readonly veya https://www.googleapis.com/auth/classroom.rosters) anlamına gelir.
Sınıf çalışması değişiklik feed'leri için bu, sınıf çalışması kapsamının "öğrenci" sürümleri veya (ideal olarak) salt okunur varyantı anlamına gelir (https://www.googleapis.com/auth/classroom.coursework.students.readonly veya https://www.googleapis.com/auth/classroom.coursework.students).

Bildirimlerin gönderilebilmesi için uygulamanın, yetkili kullanıcıdan gerekli kapsamlarla bir OAuth erişim izni alması gerekir. Kullanıcı uygulamanın bağlantısını keserse bildirimler durdurulur. Bu amaçla şu anda alan genelinde yetki devrinin desteklenmediğini unutmayın. Yalnızca alan genelinde yetki devri kullanarak bildirimlere kaydolmaya çalışırsanız @MissingGrant hatası alırsınız.

Bildirimleri alma

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

Değişen kaynağı içeren koleksiyonun adı. Program değişiklikleriyle ilgili bildirimler için bu değer courses.students veya courses.teachers olur. Sınıf çalışması değişiklikleri için bu değer courses.courseWork veya courses.courseWork.studentSubmissions'dir.
Değişen kaynağın tanımlayıcıları (harita biçiminde). Bu harita, argümanları uygun kaynağın get yöntemiyle eşleştirmek için tasarlanmıştır. Sınıf listesi değişiklikleriyle ilgili bildirimlerde courseId ve userId alanları doldurulur ve değiştirilmeden courses.students.get() veya courses.teachers.get()'e gönderilebilir. Benzer şekilde, courses.courseWork koleksiyonundaki değişikliklerde courseId ve id alanları bulunur. Bu alanlar değiştirilmeden courses.courseWork.get()'e gönderilebilir. courses.courseWork.studentSubmissions koleksiyonundaki değişikliklerde ise courseId, courseWorkId ve id alanları bulunur. Bu alanlar değiştirilmeden courses.courseWork.studentSubmissions.get()'e gönderilebilir.

Aşağıdaki kod snippet'inde örnek bir bildirim gösterilmektedir:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

Bildirimlerde, bildirime neden olan kaydın tanımlayıcısını içeren bir registrationId mesaj özelliği de bulunur. Bu özellik, bildirim kaydını silmek için registrations.delete() ile birlikte kullanılabilir.