Push Bildirimleri

Genel bakış

Gmail API'si, Gmail posta kutularında yapılan değişiklikleri izlemenize olanak tanıyan sunucu push bildirimleri sağlar. Bu özelliği, uygulamanızın performansını iyileştirmek için kullanabilirsiniz. Değişip değişmediklerini belirlemek için yoklama kaynaklarıyla ilişkili ek ağ ve işlem maliyetlerini ortadan kaldırmanızı sağlar. Bir posta kutusu 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, webhook'lar ve tek bir abonelik uç noktasında yoklama da dahil olmak üzere çeşitli yöntemler aracılığıyla bildirim alabilirsiniz.

Ön koşullar

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

Konu oluşturma

Cloud Pub/Sub istemcinizi kullanarak, Gmail API'nin bildirim göndermesi gereken konuyu oluşturun. Konu adı, projenizde seçtiğiniz herhangi bir ad olabilir.Örneğin, projects/myproject/topics/* ile eşleşen bir ad olabilir. Burada myproject, Google Developers Console'da projeniz için listelenen Proje Kimliğidir.

Konu sayısındaki Cloud Pub/Sub sınırları nedeniyle, uygulamanızdaki tüm Gmail API push bildirimleri için tek bir konu kullanmanızı öneririz.

Abonelik oluşturma

Oluşturduğunuz konuya abonelik oluşturmak için Cloud Pub/Sub Abone Kılavuzu'ndaki adımları uygulayın. Abonelik türünü webhook aktarması (ör. HTTP POST geri çağırması) veya pull (uygulamanız tarafından başlatılacak) olacak şekilde yapılandırın. Uygulamanız, güncellemelerle ilgili bildirimleri bu şekilde alır.

Konunuzla ilgili yayın hakları verin

Cloud Pub/Sub, konunuza bildirim yayınlamak için Gmail ayrıcalıkları vermenizi gerektirir.

Bunu yapmak için publish için gmail-api-push@system.gserviceaccount.com ayrıcalıkları vermeniz gerekir. Bu işlemi kaynak düzeyinde erişim kontrolü talimatlarını uygulayarak Cloud Pub/Sub Geliştirici Konsolu izinleri arayüzünü kullanarak yapabilirsiniz.

Gmail posta kutusu güncellemelerini alma

İlk Cloud Pub/Sub kurulumu tamamlandıktan sonra, Gmail hesaplarını posta kutusu güncellemeleri için 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 diğer Gmail API çağrılarına benzer şekilde Gmail kullanıcı posta kutusunda watch çağrısı yapmanız yeterlidir. Bunu yapmak için, yukarıda oluşturulan konu adını ve watch isteğinizde diğer seçenekleri (ör. labels) sağlayın. Örneğin, Gelen Kutusu'nda bir 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()

Yanıtı izle

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

{
  historyId: 1234567890
  expiration: 1431990098200
}

kullanıcının geçerli posta kutusu historyId ile değiştirin. Bundan sonraki tüm değişiklikler historyId müşterinize bildirilir. Değişiklikleri bu historyId öncesinde işlemeniz gerekiyorsa senkronizasyon kılavuzuna bakın.

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

watch çağrısından bir hata alırsanız ayrıntılarda, sorunun kaynağı açıklanmalıdır. Bu, genellikle Cloud Pub/Sub konusu ve aboneliğinin kurulumunda yapılır. Kurulumun doğru olduğunu onaylamak ve konu ve abonelik sorunlarını giderme konusunda yardım almak için Cloud Pub/Sub belgelerine bakın.

Posta kutusu saati yenileniyor

watch'i en az 7 günde bir yeniden aramanız gerekir. Aksi takdirde, bu kullanıcı için güncelleme almazsınız. watch için günde bir kez arama yapmanızı öneririz. watch yanıtında, watch geçerlilik bitiş tarihi için zaman damgasıyla birlikte bir geçerlilik bitiş alanı da bulunur.

Bildirim alma

watch ürününüzle eşleşen bir posta kutusu güncellemesi gerçekleştiğinde, uygulamanız değişikliği açıklayan bir bildirim mesajı alır.

Push aboneliği yapılandırdıysanız sunucunuza yönelik bir webhook bildirimi şuna uygun olur: 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'dir ve gerçek Gmail bildirim 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 nesnesinin kodunu çözen, base64url kodlu bir dizedir:

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

Ardından history.list aracını, senkronizasyon rehberine uygun şekilde kullanıcının bilinen son geçmiş kimliğinden bu yana yapılan değişiklik ayrıntılarını almak için kullanabilirsiniz.

Bunun yerine bir pull 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 bildirimlerin onaylanması gerekir. Webhook push teslimatını kullanırsanız başarıyla yanıt verirseniz (ör. HTTP 200) bildirimi onaylar.

Pull teslimatı (REST Pull, RPC Pull veya RPC StreamingPull) kullanıyorsanız bir onay çağrısı (REST veya RPC) ile devam etmeniz gerekir. RPC tabanlı resmi istemci kitaplıklarını kullanarak mesajları eşzamansız veya eşzamanlı olarak onaylama hakkında daha fazla bilgi için Cloud Pub/Sub Abone Çekme Kılavuzu'ndaki kod örneklerine bakın.

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

Posta kutusu güncellemelerini durdurma

Bir posta kutusunda güncelleme almayı durdurmak için stop numaralı telefonu arayın. Tüm yeni bildirimler birkaç dakika içinde durdurulur.

Sınırlamalar

Maksimum bildirim oranı

İzlenen her Gmail kullanıcısının bildirim hızı, maksimum 1 etkinlik/sn. şeklindedir. Bu oranın üzerindeki tüm kullanıcı bildirimleri atlanır. Bildirimleri ele alırken başka bir bildirimi tetiklemediğinizden ve dolayısıyla bir bildirim döngüsü başlatmadığınızdan emin olmak için dikkatli olun.

Güvenilirlik

Genellikle tüm bildirimlerin birkaç saniye içinde gönderilmesi gerekir. Ancak, bazı ekstrem durumlarda bildirimler gecikebilir veya kaldırılabilir. Hiçbir push mesajı alınmasa bile uygulamanın senkronizasyona devam edebilmesi için bu olasılığı düzgün şekilde ele aldığınızdan emin olun. Örneğin, bir kullanıcıya bildirim gönderilmez ve belirli bir sürenin ardından düzenli olarak history.list çağrısı yapılabilir.

Cloud Pub/Sub Sınırlamaları

Cloud Pub/Sub API'nin de pricing ve quotas belgelerinde ayrıntılı olarak açıklanan kendi sınırlamaları vardır.