Bu belgede, Gmail API ile anlık bildirimlerin nasıl yönetileceği açıklanmaktadır.
Gmail API, Gmail posta kutularındaki değişiklikleri izlemenizi sağlayan sunucu push bildirimleri sunar. Uygulamanızın performansını artırmak için bu özelliği kullanın. Kaynakların değişip değişmediğini belirlemek için kaynakları yoklamanın ek ağ ve işlem maliyetlerini ortadan kaldırır. Bir posta kutusu her değiştiğinde Gmail API, arka uç sunucusu uygulamanıza bildirim gönderir.
İlk Cloud Pub/Sub kurulumu
Gmail API, push bildirimlerini iletmek 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 kullanarak bildirim alabilirsiniz.
Ön koşullar
Bu kurulumu tamamlamak için Cloud Pub/Sub ön koşullarını karşılayın ve ardından Cloud Pub/Sub istemcisi oluşturun.
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 (örneğin, projects/myproject/topics/* ile eşleşme, burada myproject, Google Cloud Console'da projeniz için listelenen proje kimliğidir).
Abonelik oluşturma
Oluşturduğunuz konuya abonelik ayarlamak için Cloud Pub/Sub abonelik türü kılavuzunu inceleyin. Abonelik türünü webhook push (yani HTTP POST geri araması) veya çekme (yani uygulamanız tarafından başlatılan) 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.
Bunu yapmak için publish ayrıcalıklarını gmail-api-push@system.gserviceaccount.com'e verin. Bu işlemi, Google Cloud Console'daki Cloud Pub/Sub izinleri konsolunu kullanarak ve erişim denetimi talimatlarını uygulayarak yapabilirsiniz.
Kuruluşunuzun alan adıyla 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 kurulumunu tamamladı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 yöntemini çağırın. Bu, diğer tüm Gmail API çağrılarına benzer. Oluşturduğunuz konu adını ve watch isteğinizdeki diğer seçenekleri (ör. labels) filtrelemek için sağlayın. Örneğin, gelen kutusunda değişiklik olduğunda bildirim almak için aşağıdaki isteği kullanın:
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ı izleme
watch isteği başarılı olursa aşağıdaki gibi bir yanıt alırsınız:
{
"historyId": "1234567890",
"expiration": "1431990098200"
}
Yanıt, kullanıcının mevcut posta kutusunu historyId içerir. Müşteriniz, historyId tarihinden sonraki tüm değişikliklerle ilgili bildirimler alır. Bu historyId tarihinden önce değişiklikleri işlemeniz gerekiyorsa İstemcileri Gmail ile senkronize etme başlıklı makaleyi inceleyin.
Ayrıca, başarılı bir watch çağrısı, Cloud Pub/Sub konunuza anında bir bildirim gönderir.
watch çağrısından hata alırsanız ayrıntılar sorunun kaynağını açıklar. Bu durum genellikle Cloud Pub/Sub konusu ve aboneliğinin kurulumuyla ilgili bir sorundur. 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
Kullanıcı için güncelleme almaya devam etmek istiyorsanız watch yöntemini en az 7 günde bir çağırmanız gerekir.
watch işlevinin günde bir kez çağrılmasını öneririz. watch yöntemi yanıtında ayrıca watch geçerlilik bitişi için zaman damgasının bulunduğu bir expiration alanı da yer alır.
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.
Anlık bildirim 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'dur ve gerçek Gmail bildirimi yükü message.data alanındadır. 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 yöntemini kullanarak kullanıcının bilinen son
historyId tarihinden itibaren yaptığı değişikliklerin ayrıntılarını alabilirsiniz. Bu işlem, İstemcileri Gmail ile senkronize etme başlıklı makalede açıklanmıştır.
Örneğin, ilk watch isteğiniz ile önceki örnekte paylaşılan bildirim mesajının alınması arasında meydana gelen değişiklikleri belirlemek için history.list yöntemini kullanın. 1234567890 öğesini history.list için startHistoryId olarak iletin. Ardından, gelecekteki kullanım alanlarında 9876543210 değerini bilinen son historyId olarak kalıcı hale getirebilirsiniz.
Bunun yerine çekme aboneliği yapılandırdıysanız mesaj alma hakkında daha fazla bilgi için Cloud Pub/Sub çekme abonelikleri kılavuzundaki kod örneklerine bakın.
Bildirimleri yanıtlama
Tüm bildirimleri onaylamanız gerekir. Webhook push delivery kullanıyorsanız başarılı bir şekilde yanıt vermek (örneğin, HTTP 200) bildirimi onaylar.
Çekme iletimini (REST çekme, RPC çekme, veya RPC akış çekme) kullanıyorsanız ileti alındılarını REST veya RPC ileti alındı yöntemiyle göndermeniz 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'ın pull subscriptions kılavuzundaki kod örneklerine bakın.
Bildirimleri onaylamazsanız (örneğin, webhook geri aramanız bir hata döndürürse veya zaman aşımına uğrarsa) Cloud Pub/Sub bildirimi daha sonra yeniden dener.
Posta kutusu güncellemelerini durdurma
Bir posta kutusuyla ilgili güncellemeleri almayı durdurmak için stop yöntemini çağırın. Tüm yeni bildirimler birkaç dakika içinde durdurulur.
Sınırlamalar
Sunucu push bildirimleriyle çalışmanın sınırlamaları şunlardır:
Maksimum bildirim sıklığı
İzlenen her Gmail kullanıcısı için maksimum bildirim sıklığı saniyede bir etkinliktir. Hizmet, bu oranı aşan kullanıcı bildirimlerini bırakır. Bildirimleri işlerken başka bir bildirimi tetiklememeye dikkat edin. Aksi takdirde bildirim döngüsü başlayabilir.
Güvenilirlik
Cloud Pub/Sub genellikle bildirimleri birkaç saniye içinde iletir. Ancak nadir durumlarda bildirimler gecikebilir veya bırakılabilir. Uygulamanız push mesajları almasa bile uygulamanın senkronize olmaya devam etmesi için bu olasılığı düzgün bir şekilde ele alın. Örneğin, bir kullanıcıya bildirim gönderilmeyen bir sürenin ardından history.list yöntemini 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, API'nin fiyatlandırma ve kotalar belgelerinde ayrıntılı olarak açıklanmıştır.