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öntemlerle 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 bir Cloud Pub/Sub istemcisi 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'ndaki adımları uygulayın. Abonelik türünü webhook push (ör. HTTP POST geri araması) 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 publish ayrıcalıklarını gmail-api-push@system.gserviceaccount.com'e vermeniz gerekir. Bu işlemi, kaynak düzeyinde erişim kontrolü talimatlarını uygulayarak Cloud Pub/Sub Developer Console 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ü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 her 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. Bundan sonraki tüm değişiklikler
historyId istemcinize 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ılar, sorunun kaynağını (genellikle Cloud Pub/Sub konusu ve aboneliğinin kurulumuyla ilgili) açıklar. 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ıyla ilgili güncellemeleri almaya devam etmek için watch işlevini en az 7 günde bir yeniden çağırmanız gerekir. watch işlevinin günde bir kez çağrılmasını öneririz. watch yanıtında, watch sona erme zaman damgasını içeren bir sona erme alanı da bulunur.
Bildirim 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.
Bildirimlere yanıt verme
Tüm bildirimlerin onaylanması gerekir. 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 Abone Çekme Kılavuzu'ndaki 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 numaralı telefonu arayı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ın üzerindeki kullanıcı bildirimleri bırakılır. Başka bir bildirimi tetiklememek ve böylece bildirim döngüsü başlatmamak için bildirimleri işlerken dikkatli olun.
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ğrılabilir.
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.