Genel Bakış
Gmail API, Gmail posta kutularında yapılan değişiklikleri izlemenize olanak tanıyan sunucu push bildirimleri sağlar. Bu özelliği kullanarak uygulamanızın performansını artırabilirsiniz. Değişip değişmediklerini belirlemek için kaynakları yoklamakla ilgili ek ağ ve bilgi işlem maliyetlerini ortadan kaldırmanıza olanak tanır. Bir posta kutusu değiştiğinde Gmail API, arka uç sunucu uygulamanızı bilgilendirir.
İ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 anketler 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 oluşturun.
Konu oluşturma
Cloud Pub/Sub istemcinizi kullanarak Gmail API'nin bildirim göndermesi gereken konuyu oluşturun. Konu adı, projeniz kapsamında seçtiğiniz herhangi bir ad olabilir (ör. myproject, Google Developers Console'da projeniz için listelenen proje kimliği olan projects/myproject/topics/* ile eşleşen bir ad).
Konu sayısıyla ilgili Cloud Pub/Sub sınırlamaları nedeniyle, uygulamanız için 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'nu inceleyin. Abonelik türünü webhook push (ör. HTTP POST geri çağırma) veya pull (ör. uygulamanız tarafından başlatılan) olarak yapılandırın. Uygulamanız, güncellemelerle ilgili bildirimleri bu şekilde alır.
Konunuzla ilgili yayın 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'a publish ayrıcalıkları vermeniz gerekir. Bunu, kaynak düzeyinde erişim denetimi talimatlarını uygulayarak Cloud Pub/Sub Developer Console izin arayüzünü kullanarak yapabilirsiniz.
Gmail posta kutusu güncellemeleri 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 Gmail kullanıcı posta kutusunda watch işlevini çağırmanız yeterlidir. Bu işlem, diğer Gmail API çağrılarına benzer.
Bunu yapmak için yukarıda oluşturulan konu adını ve watch isteğinizde filtrelemek için labels gibi diğer seçenekleri 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()
Yanıtı izleme
watch isteği başarılı olursa şuna benzer 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şikliklerhistoryId müşterinize bildirilir. Bu historyId tarihinden önce yapılan değişiklikleri işlemeniz gerekiyorsa senkronizasyon kılavuzunu inceleyin.
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 hata alırsanız ayrıntılarda sorunun kaynağı açıklanır. Bu kaynak genellikle Cloud Pub/Sub konusunun ve aboneliğinin kurulumuyla ilgilidir. Kurulumun doğru olduğunu onaylamak ve konu ile abonelik sorunlarında hata ayıklama konusunda yardım almak için Cloud Pub/Sub dokümanlarına bakın.
Posta kutusu izlemeyi yenileme
watch işlevini en az 7 günde bir yeniden çağırmanız gerekir. Aksi takdirde kullanıcıyla ilgili güncelleme almazsınız. watch numaralı telefonu günde bir kez aramanızı öneririz. watch yanıtında, watch geçerlilik süresinin zaman damgasını içeren bir geçerlilik süresi alanı da bulunur.
Bildirim alma
watch ile eşleşen bir posta kutusu güncellemesi olduğunda, uygulamanıza değişikliği açıklayan bir bildirim mesajı gönderilir.
Push aboneliği yapılandırdıysanız sunucunuza gönderilen webhook bildirimi PubsubMessage biçiminde olur:
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 mesajı JSON biçimindedir 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 nesnesine kod çözme işlemi uygulanan base64url kodlu bir dizedir:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Ardından, senkronizasyon kılavuzuna göre bilinen son historyId değerinden itibaren kullanıcının değişiklik ayrıntılarını almak için history.list değerini kullanabilirsiniz.
Bunun yerine bir alma aboneliği yapılandırdıysanız mesaj alma hakkında daha fazla bilgi için Cloud Pub/Sub Abone Alma Kılavuzu'ndaki kod örneklerine bakın.
Bildirimleri yanıtlama
Tüm bildirimlerin onaylanması gerekir. Push yöntemiyle webhook kullanıyorsanız başarılı bir yanıt (ör. HTTP 200) vererek bildirimi onaylayabilirsiniz.
Çekme yayını (REST çekme, RPC çekme veya RPC StreamingPull) kullanıyorsanız bunu bir onay aramasıyla (REST veya RPC) takip 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 çağırma işleviniz 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üncelleme almayı durdurmak için stop numaralı telefonu arayın. Tüm yeni bildirimler birkaç dakika içinde durdurulur.
Sınırlamalar
Maksimum bildirim hızı
İzlenen her Gmail kullanıcısı için maksimum bildirim hızı saniyede 1 etkinliktir. Bu hızın üzerindeki kullanıcı bildirimleri atlanır. Bildirimleri işleme alırken başka bir bildirimi tetiklememeye ve böylece bildirim döngüsü başlatmamaya dikkat edin.
Güvenilirlik
Genellikle tüm bildirimler birkaç saniye içinde güvenilir bir şekilde gönderilir. Ancak bazı aşırı durumlarda bildirimler gecikebilir veya gönderilmeyebilir.
Push mesajı alınmasa bile uygulamanın senkronize olmaya devam etmesi için bu olasılığı düzgün bir şekilde ele almanız gerekir. Örneğin, bir kullanıcıya bildirim gelmeyen bir sürenin ardından history.list çağrısını düzenli olarak tekrarlayın.
Cloud Pub/Sub Sınırlamaları
Cloud Pub/Sub API'nin de kendi sınırlamaları vardır. Bu sınırlamalar özellikle fiyatlandırma ve kotalar belgelerinde ayrıntılı olarak açıklanmıştır.