Bu belgede, Gmail API'de push bildirimlerinin 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 getirdiği 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 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 bildirimler gönderilebilir.
Ö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/* eşleştirme, 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 erişim denetimi talimatlarını uygulayarak yapabilirsiniz.
Kuruluşunuzun alan adıyla kısıtlanmış 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 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 kullanın. Örneğin, gelen kutusunda değişiklik yapıldığında 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 API ile senkronize etme başlıklı makaleyi inceleyin.
Ayrıca, başarılı bir watch çağrısı, Cloud Pub/Sub konunuza anında bildirim gönderilmesine neden olur.
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ğunu onaylamak ve konu ile abonelik sorunlarını ayıklamak için Cloud Pub/Sub belgelerine bakın.
Posta kutusu izlemeyi yenileme
watch işlevini en az 7 günde bir çağırmanız gerekir. Aksi takdirde, kullanıcıyla ilgili güncellemeleri almayı durdurursunuz. watch işlevinin günde bir kez çağrılmasını öneririz. watch yöntemi yanıtında, watch sona erme zaman damgasını içeren bir expiration 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.
Anında bildirim aboneliği yapılandırdıysanız sunucunuza gönderilen webhook bildirimi PubsubMessage ile uyumludur:
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. 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, İstemcileri Gmail API ile senkronize etme bölümünde açıklandığı gibi, kullanıcının bilinen son history.list historyId tarihinden itibaren yaptığı değişikliklerin ayrıntılarını almak için yöntemi kullanabilirsiniz.
Örneğin, ilk history.list isteğiniz ile önceki örnekte paylaşılan bildirim mesajının alınması arasında meydana gelen değişiklikleri belirlemek için watch 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'ın çekme abonelikleri kılavuzundaki 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 (örneğin, HTTP 200) bildirimi onaylar.
Çekme teslimatı (REST Pull, RPC Pull, veya RPC StreamingPull) kullanıyorsanız bir onaylama çağrısı (REST veya RPC) yapmanız 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. Bu oranı aşan tüm kullanıcı bildirimleri bırakılır. Bildirimleri işlerken başka bir bildirimi tetiklememeye dikkat edin. Aksi takdirde bildirim döngüsü başlayabilir.
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 alın. 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 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.