Push Bildirimleri

Genel Bakış

Gmail API, Gmail posta kutularındaki değişiklikleri izlemenize olanak tanıyan sunucu push bildirimleri sağlar. Bu özelliği, uygulamanızın performansını artırmak için kullanabilirsiniz. Kaynakların değişip değişmediğini belirlemek için kaynakları yoklamayla ilişkili ek ağ ve bilgi işlem maliyetlerini ortadan kaldırmanıza olanak tanır. Bir posta kutusu her değiştiğinde Gmail API, arka uç sunucu uygulamanıza bildirim gönderir.

İlk Cloud Pub/Sub kurulumu

Gmail API, push bildirimleri göndermek için Cloud Pub/Sub API'yi kullanır. Bu sayede, tek bir abonelik uç noktasında webhook'lar ve yoklama dahil olmak üzere çeşitli yöntemler kullanılarak bildirim gönderilebilir.

Ön koşullar

Bu kurulumun geri kalanını tamamlamak için Cloud Pub/Sub Ön Koşulları'nı karşıladığınızdan emin olun ve ardından Cloud Pub/Sub istemcisini ayarlayın.

Konu oluşturma

Cloud Pub/Sub istemcinizi kullanarak Gmail API'nin bildirim göndermesi gereken konuyu oluşturun. Konu adı, projeniz altında seçtiğiniz herhangi bir ad olabilir (ör. projects/myproject/topics/* ile eşleşme, burada myproject, Google Developers Console'da projeniz için listelenen proje kimliğidir).

Abonelik oluşturma

Oluşturduğunuz konuya abonelik ayarlamak için Cloud Pub/Sub Abone Kılavuzu'nu izleyin. Abonelik türünü webhook push (ör. HTTP POST geri çağırma) veya çekme (ör. uygulamanız tarafından başlatılır) olarak yapılandırın. Uygulamanız, güncellemelerle ilgili bildirimleri bu şekilde alır.

Konunuzda yayınlama hakları verme

Cloud Pub/Sub, Gmail'e konunuzda bildirim yayınlama ayrıcalıkları vermenizi gerektirir.

Bunun için gmail-api-push@system.gserviceaccount.com'ye publish ayrıcalıkları vermeniz gerekir. Bu işlemi, Cloud Pub/Sub Developer Console izinleri arayüzünü kullanarak kaynak düzeyinde erişim kontrolü talimatlarını uygulayarak yapabilirsiniz.

Kuruluşunuzun alanla sınırlı paylaşım yapılandırması, yayınlama izni vermenizi engelleyebilir. Bu sorunu çözmek için bu hizmet hesabı için bir istisna yapılandırabilirsiniz.

Gmail posta kutusu güncellemelerini alma

İlk Cloud Pub/Sub kurulumu tamamlandıktan sonra, Gmail hesaplarını posta kutusu güncellemeleriyle ilgili bildirim gönderecek şekilde yapılandırın.

İzleme isteği

Gmail hesaplarını Cloud Pub/Sub konunuza bildirim gönderecek şekilde yapılandırmak için Gmail API istemcinizi kullanarak Gmail kullanıcı posta kutusunda watch'i diğer Gmail API çağrılarına benzer şekilde çağırın. Bunu yapmak için yukarıda oluşturulan konu adını ve watch isteğinizdeki diğer seçenekleri (ör. labels) sağlayın. Örneğin, gelen kutusunda değişiklik yapıldığında bildirim almak için:

Protokol

POST "https://www.googleapis.com/gmail/v1/users/me/watch"
Content-type: application/json

{
  topicName: "projects/myproject/topics/mytopic",
  labelIds: ["INBOX"],
  labelFilterBehavior: "INCLUDE",
}

Python

request = {
  'labelIds': ['INBOX'],
  'topicName': 'projects/myproject/topics/mytopic',
  'labelFilterBehavior': 'INCLUDE'
}
gmail.users().watch(userId='me', body=request).execute()

Saat yanıtı

watch isteği başarılı olursa şu gibi bir yanıt alırsınız:

{
  historyId: 1234567890
  expiration: 1431990098200
}

kullanıcının mevcut posta kutusu historyId ile. Bu tarihten sonraki tüm değişiklikler historyId müşterinize bildirilir. Bu tarihten historyId önce değişiklikleri işlemeniz gerekiyorsa senkronizasyon kılavuzuna bakın.

Ayrıca, başarılı bir watch çağrısı, Cloud Pub/Sub konunuza anında bir bildirim gönderilmesine neden olmalıdır.

watch çağrısından hata alırsanız ayrıntılarda sorunun kaynağı açıklanır. Bu kaynak genellikle Cloud Pub/Sub konusu ve aboneliğinin kurulumuyla ilgilidir. Kurulumun doğru olduğundan emin olmak ve konu ile abonelik sorunlarını ayıklama konusunda yardım almak için Cloud Pub/Sub belgelerine bakın.

Posta kutusu izlemeyi yenileme

watch en az 7 günde bir geri çağırmanız gerekir. Aksi takdirde kullanıcıyla ilgili güncellemeleri almayı durdurursunuz. Günde bir kez watch numaralı telefonu aramanızı öneririz. watch yanıtında, watch geçerlilik bitiş zaman damgasını içeren bir geçerlilik bitişi alanı da bulunur.

Bildirimleri alma

watch ile eşleşen bir posta kutusu güncellemesi olduğunda uygulamanız, değişikliği açıklayan bir bildirim mesajı alır.

Push aboneliği yapılandırdıysanız sunucunuza gönderilen webhook bildirimi PubsubMessage:

POST https://yourserver.example.com/yourUrl
Content-type: application/json

{
  message:
  {
    // This is the actual notification data, as base64url-encoded JSON.
    data: "eyJlbWFpbEFkZHJlc3MiOiAidXNlckBleGFtcGxlLmNvbSIsICJoaXN0b3J5SWQiOiAiMTIzNDU2Nzg5MCJ9",

    // This is a Cloud Pub/Sub message id, unrelated to Gmail messages.
    "messageId": "2070443601311540",

    // This is the publish time of the message.
    "publishTime": "2021-02-26T19:13:55.749Z",
  }

  subscription: "projects/myproject/subscriptions/mysubscription"
}

HTTP POST gövdesi JSON biçimindedir ve gerçek Gmail bildirimi yükü message.data alanındadır. Bu message.data alanı, kullanıcının e-posta adresini ve yeni posta kutusu geçmişi kimliğini içeren bir JSON nesnesine çözülen base64url kodlu bir dizedir:

{"emailAddress": "user@example.com", "historyId": "9876543210"}

Ardından, history.list kullanarak kullanıcının senkronizasyon kılavuzunda belirtildiği gibi bilinen son historyId'sinden bu yana yaptığı değişikliklerin ayrıntılarını alabilirsiniz.

Örneğin, ilk watch çağrınız ile önceki örnekte paylaşılan bildirim mesajının alınması arasında meydana gelen değişiklikleri belirlemek için history.list'ı kullanmak üzere 1234567890 değerini startHistoryId olarak history.list'a iletin. Daha sonra,9876543210 gelecekteki kullanım alanları için bilinen son historyId olarak kalıcı hale getirilebilir.

Bunun yerine çekme aboneliği yapılandırdıysanız mesaj alma hakkında daha fazla bilgi için Cloud Pub/Sub Abone Çekme Kılavuzu'ndaki kod örneklerine bakın.

Bildirimleri yanıtlama

Tüm bildirimler onaylanmalıdır. Webhook push delivery kullanıyorsanız başarılı bir şekilde yanıt vermek (ör. HTTP 200) bildirimi onaylar.

Çekme iletimi (REST Çekme, RPC Çekme veya RPC Akış Çekme) kullanıyorsanız bir onaylama çağrısı (REST veya RPC) ile devam etmeniz gerekir. Resmi RPC tabanlı istemci kitaplıklarını kullanarak mesajları eşzamansız veya eşzamanlı olarak onaylama hakkında daha fazla bilgi için Cloud Pub/Sub Subscriber Pull Guide'daki kod örneklerine bakın.

Bildirimler onaylanmazsa (ör. webhook geri aramanız hata döndürür veya zaman aşımına uğrarsa) Cloud Pub/Sub bildirimi daha sonra tekrar dener.

Posta kutusu güncellemelerini durdurma

Bir posta kutusuyla ilgili güncellemeleri almayı durdurmak için stop işlevini çağırın. Tüm yeni bildirimler birkaç dakika içinde durdurulur.

Sınırlamalar

Maksimum bildirim sıklığı

İzlenen her Gmail kullanıcısı için maksimum bildirim oranı 1 etkinlik/sn'dir. Bu oranı aşan kullanıcı bildirimleri bırakılır. Başka bir bildirimi tetiklememek ve bildirim döngüsü başlatmamak için bildirimleri dikkatli bir şekilde işleyin.

Güvenilirlik

Genellikle tüm bildirimler birkaç saniye içinde güvenilir bir şekilde teslim edilir. Ancak bazı durumlarda bildirimler gecikebilir veya bırakılabilir. Bu olasılığı düzgün bir şekilde ele aldığınızdan emin olun. Böylece, push mesajı alınmasa bile uygulama senkronize olmaya devam eder. Örneğin, bir kullanıcıya bildirim gönderilmeyen bir sürenin ardından history.list'ı düzenli olarak çağırmaya geri dönün.

Cloud Pub/Sub Sınırlamaları

Cloud Pub/Sub API'nin de kendi sınırlamaları vardır. Bu sınırlamalar, fiyatlandırma ve kotalar belgelerinde ayrıntılı olarak açıklanmıştır.