LinkedIn
Instagram
WhatsApp
Telgraf
Gmail
Görünüm
Google Takvim
Slack Topluluğuna KatılınGmail API Anlık BildirimlerPub/Sub, Watch ve History (2026) için Tam Rehber
Gmail API anlık bildirimlerini uçtan uca ayarlayın: bir Pub/Sub konusu oluşturun, bir izleme uç noktası kaydedin, webhook yüklerini kodlayın, değişiklikleri şunlarla uyumlu hale getirin kullanıcıların.geçmişi.listesi, izleme yenilemesini otomatikleştirin ve birleşik bir webhook alternatifi ile tüm GCP kurulumunu atlayın.
// 1. Unipile aracılığıyla Gmail'i izlemeyi kaydet
const Res = bekliyor fetch('https://api8.unipile.com:13815/api/v1'
+ '/hesaplar/{id}/izle', {
method: 'POST',
headers: {
'X-API-ANAHTARI': 'SENİN_API_ANAHTARIN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
webhook_url: 'https://app.you.com/webhooks/gmail'
})
});
// 2. Birleşik webhook yükünü al
uygulama.POST('/webhooks/gmail', (istek, yanıt) => {
const { olay, hesap_id, eposta } = req.body;
// olay: "yeni_e-posta" | geçmişId soyutlandı
yeniEpostaUygula(e-posta);
});Gmail API anlık bildirimleri nedir?
Gmail API'nin anlık bildirimlerini üretime almadan önce, tam olarak ne olduklarını, basit yoklamadan nasıl farklılaştıklarını ve ne tür altyapı gerektirdiklerini anlamak faydalıdır.
Gmail API anlık bildirimleri, Google Cloud Pub/Sub kullanarak geliştirici tarafından kontrol edilen bir HTTPS uç noktasına posta kutusu değişiklik olaylarını gönderen gerçek zamanlı bir teslimat mekanizmasıdır. Yeni bir ileti geldiğinde veya mevcut bir ileti değiştirildiğinde, Gmail kodlanmış bir içerik içeren bir bildirim yayınlar. tarihKimliği kendi sahip olduğunuz bir Pub/Sub konusuna, bu da olayı webhook'unuza iletir. Sunucunuz çağırır kullanıcıların.geçmişi.listesi gerçek değişiklikleri almak için.
Gmail API anlık bildirimleri, tekrarlı sorgu ihtiyacını ortadan kaldırır mesajlar.liste zamanlanmış bir şekilde. E-posta kutusu değişikliğinden saniyeler içinde olaylar teslim edilir, bu da gecikme süresini ve API kota kullanımını azaltır.
Teslimat kanalı, Gmail'den doğrudan bir HTTP geri çağrısı yerine Google Cloud Pub/Sub'dur. Bu, dayanıklılık katar: uç noktanız geçici olarak kullanılamıyorsa, Pub/Sub abonelik onay son teslim süresine göre teslimatı yeniden deneyebilir.
Bir Gmail API izleme uç noktası 7 gün sonra sona erer. Uygulamanız bunu günlük bir cron işiyle proaktif olarak yenilemeli, aksi takdirde olayları sessizce kaçırma riskiyle karşı karşıya kalırsınız. Bu, Yenileme bölümünde ele alınan kritik bir operasyonel ayrıntıdır.
Gmail API anlık bildirimleri, değişiklikler gerçekleştikten sonraki 1-10 saniye içinde olayları iletir. Sürekli sorgulama olmaması, Gmail API'si kotası kullanımını düşürür ve uygulamanızın tepki süresini hızlandırır. Herhangi bir gelen kutusu seviyesinde gerçek zamanlı kullanım senaryosu için idealdir: CRM senkronizasyonu, biletleme sistemleri, iş akışı otomasyonu.
Oylama mesajlar.liste Her 60 saniyede bir kurmak daha basit olsa da, yapay gecikme yaratır, boş yanıtlar için kota israf eder ve çok sayıda kimliği doğrulanmış kullanıcı hesabı arasında kötü ölçeklenir. Sadece düşük hacimli prototipler için kabul edilebilirdir.
Mimari: izleme + Pub/Sub + historyId tek bir akışta
Gmail API anlık bildirimleri, sıralı olarak çalışan dört farklı katmandan oluşur. Her katmanı kod yazmadan önce anlamak, en yaygın uygulama hatalarını önler.
POST yaparsınız https://gmail.googleapis.com/gmail/v1/users/me/watch Pub/Sub konu adınız ve isteğe bağlı bir etiket filtresiyle. Gmail bir şey döndürür tarihKimliği ve bir son kullanma tarihi Unix zaman damgası. İkisini de saklayın. Bu saat 7 gün içinde sona erecek.
İzlenen posta kutusunda herhangi bir değişiklik olduğunda (yeni mesaj, etiket değişikliği, okunmuş/okunmamış geçişi), Gmail Cloud Pub/Sub konunuza bir JSON bildirimi yayınlar. Yük, kullanıcının e-posta adresini ve yeni bir bilgiyi içeren base64 ile kodlanmış bir nesnedir. tarihKimliği.
Pub/Sub aboneliğiniz mesajı kayıtlı bir HTTPS anlık iletme uç noktasına iletir. Bu, webhook URL'nizdir ve kabul süresi sonu (varsayılan 10-600 saniye) içinde HTTP 200-299 ile yanıt vermesi gerekir. 2xx dışı bir yanıt otomatik yeniden denemeleri tetikler.
Base64 Pub/Sub mesaj verilerini çözerek yeni
tarihKimliği. Buna karşılaştırı sonGeçmişKimliği bu kullanıcı için veritabanınızda saklanır.
Ara kullanıcıların.geçmişi.listesi ile başlangıçTarihId saklanan değere ayarla. Gmail, iki kimlik arasındaki tüm değişiklikleri (yeni mesajlar, etiket eklemeler, silmeler) döndürür. Saklanan değeri güncelle sonGeçmişKimliği yeni değere. Pub/Sub bildirimindeki historyId'yi asla kullanmayın başlangıçTarihId doğrudan.
Her gün bir cron işi zamanla kullanıcılar.izle yeniden her kimlik doğrulanmış kullanıcı hesabı için. İzleme yenileme değişmezdir: yeni bir çağrı önceki süreyi geçersiz kılar. Döndürülen tarihKimliği yeni temeliniz olur.
Her posta kutusu değişikliği için Gmail tarafından atanan, monoton artan bir tam sayı. Artımlı senkronizasyon için imlecinizdir. Her zaman kullanıcının en son historyId'sini veritabanınızda saklayın.
Bir posta kutusu için bir anlık bildirim aboneliği kaydeden Gmail API uç noktası. Bir historyId temel çizgisi ve bir Unix milisaniye cinsinden sona erme zaman damgası döndürür. 7 gün içinde yenilenmelidir.
Uzlaştırma uç noktası. Belirtilen başlangıç geçmiş kimliğinden sonra meydana gelen tüm mesaj eklemelerini, silmelerini ve etiket değişikliklerini döndürür. Gerçek mesaj verilerini buradan alırsınız.
Gereksinimler: GCP projesi, Pub/Sub konusu, IAM yetkisi
Gmail API anlık bildirimleri, ilk bildiriminizden önce GCP tarafında üç kaynağa ihtiyaç duyar kullanıcılar.izle Çağrı. Çoğu uygulama hatası, geliştiricilerin en sık atladığı adım olan Pub/Sub konusundaki eksik bir IAM izninden kaynaklanmaktadır.
Google Cloud Console'da bir proje oluşturun veya mevcut bir projeyi seçin. Aşağıdaki konuma gidin API'ler ve Hizmetler > Kitaplık ve etkinleştir Gmail API. Ayrıca şuna da ihtiyacın var Cloud Pub/Sub API aynı projede etkinleştirildi. OAuth 2.0 istemci kimlik bilgilerinizin şunları içerdiğinden emin olun https://www.googleapis.com/auth/gmail.readonly kapsam (veya yazma erişimine ihtiyacınız varsa daha geniş bir kapsam). Çok kullanıcılı uygulamalar için kılavuzumuza bakın Gmail OAuth 2.0 entegrasyonu ve Google OAuth uygulama doğrulaması gereksinimler.
GCP Konsolu'nda altında Pub/Sub > Konular, tıklayın Konu Oluştur. Adını şöyle verin gmail bildirimleri. Tam konu adı projects/YOUR_PROJECT_ID/topics/gmail-bildirimleri. Bu tam dizeyi şuna ileteceksiniz kullanıcılar.izle içinde konuAdı alan.
Bu, çoğu geliştiricinin gözden kaçırdığı adımdır. Gmail, Google tarafından yönetilen bir hizmet hesabı kullanır (gmail-api-push@system.gserviceaccount.com) bildirimleri Pub/Sub konunuza yayınlamak için. Bu hesaba ... vermeden (yetki vermeden) Pub/Sub Yayıncı konunuzdaki rolünüz, kullanıcılar.izle başarılı olacak ancak hiçbir bildirim gönderilmeyecek. Konsol'da: Konular > konunuzu seçin > İzinler > Ana;'>
Kullanıcı ekle > girin gmail-api-push@system.gserviceaccount.com rol ata Pub/Sub Yayıncı.
Pub/Sub konusunun altında, bir tane oluştur Bildirim aboneliği. Yayın uç noktasını HTTPS webhook URL'nize ayarlayın (geçerli bir TLS sertifikası kullanmalı, kendi kendine imzalanan sertifikalar reddedilir). Uç noktanızın isteklerin Google'dan geldiğini doğrulayabilmesi için isteğe bağlı olarak bir jeton doğrulama başlığı yapılandırın. Abonelik adını not edin, bu adı Tespit İzleme'de teslimat metriklerini izlemeniz gerekebilir.
Doğrulanmamış uygulamalar için 100 kullanıcı sınırı: OAuth onay ekranınız "Test" durumundaysa, yalnızca 100 Gmail hesabı uygulamanıza yetki verebilir. Bu sınır şunlar için geçerlidir tüm OAuth kapsamları, izleme uç noktası dahil. 100'den fazla kullanıcısı olan üretim dağıtımları için Google'ın doğrulama sürecini tamamlamanız gerekir. Tam kılavuzumuz için bkz. 100 kullanıcı sınırı ve doğrulama yolu.
Pub/Sub konusu yok. IAM izni yok. 7 günlük izleme yenileme cron'u yok. Tek bir webhook URL'si ile Gmail anlık bildirimleri oluşturun.
Adım adım: konu oluştur, abonelik oluştur ve kullanıcılar.izle
GCP ön koşulları yerine getirildikten sonra, Node.js ve Python'da Google API istemci kütüphanesini kullanarak bir Gmail API izleme uç noktası kaydetmek için eksiksiz kod aşağıdadır.
const { google } require('googleapis');
// OAuth2 istemcisinin geçerli bir erişim belirteciyle zaten yetkilendirildiği varsayılır
// Bakınız: https://www.unipile.com/gmail-oauth-20-integration-complete-guide/
async function Gmail'e kaydol(yetkilendirme, userId = 'ben') {
const gmail = google.gmail({ sürüm: 'v1', auth });
const response = bekliyor gmail.kullanıcıları.saat({
kullanıcıId,
requestBody: {
// Tam Yayınlama/Abonelik konu adınız
konuAdı: 'projects/YOUR_PROJECT_ID/topics/gmail-bildirimleri',
// İsteğe bağlı: yalnızca belirli etiketlere göre filtrele
labelIds: ['GELEN KUTUSU'],
etiketFiltreDavranışı: 'İÇER'
}
});
const { historyId, expiration } = response.data;
// Kullanıcı başına veritabanınızda saklayın
bekliyor Veritabanı.ekleme/güncelleme({
kullanıcıId,
sonGeçmişId: geçmişId,
// son kullanma tarihi Unix ms zaman damgasıdır
saatBitiş yeni Tarih(parseInt(son kullanma tarihi))
});
konsol.log(`İzleme kaydı oluşturuldu. historyId: ${historyId}, geçerlilik süresi: ${expiration}`);
return yanıt.veri;
}itibaren googleapiclient.discovery İthalat inşa etmek
itibaren google.oauth2.kimlik bilgileri İthalat Kimlik Bilgileri
fonksiyon gmail_izleme_kaydıkimlik bilgileri: Kimlik Bilgileri, kullanıcı_id: dizi = 'ben') -> dict:
"Kimliği doğrulanmış bir kullanıcı için Gmail API anlık bildirim izlemesini kaydedin."
hizmet = inşa etmek('gmail', 'v1', kimlik bilgileri=kimlik_bilgileri)
gövde = {
'KonuAdı': 'projects/YOUR_PROJECT_ID/topics/gmail-bildirimleri',
'etiketKimlikleri': ['GELEN KUTUSU'],
'etiketFiltreDavranışı': 'İÇER'
}
sonuç = servis.kullanıcılar().saat(kullanıcıId=user_id, gövde=body).yürüt()
# Veritabanınızda kullanıcı başına depolayın
db_ekle_veya_güncelle(user_id=user_id,
son_geçmiş_kimliği=sonuç['tarihKimliği'],
izlenme_süresi_doldu=int(sonuç['son kullanma tarihi']) // 1000)
return sonuçGmail API anlık bildirim webhook yükünü işleme
Gmail bir anlık bildirim gönderdiğinde, HTTPS uç noktanız bir Pub/Sub anlık iletisi alır. Gerçek Gmail değişiklik verileri çift kodlanmıştır: Pub/Sub zarfı, kendi içinde kullanıcı e-postasını ve historyId'yi içeren base64 ile kodlanmış bir JSON dizesi içerir.
uygulama.POST('/webhooks/gmail', async (req, res) => {
// Publication/Subscribe, 2xx olmayan yanıtlarda yeniden dener: Hemen onayla
res.durum(200).son();
denemek {
const mesaj = req.body.mesaj;
eğer (!message?.data) döndür;
// Base64 ile kodlanmış Pub/Sub veri alanını kod çöz
const çözüldü =
Tampon.itibaren(mesaj.veri, 'base64').toString('utf-8');
const yük JSON.ayrıştırmak(çözülmüş);
// yük = { epostaAdresi: "user@gmail.com", geçmişKimliği: "12345" }
const { emailAdresi, geçmişId } = yük;
// Kuyruk uzlaştırması (onayı engellemeyin)
bekliyor kuyruk.sıraya ekle({ emailAdresi, geçmişId });
} catch (hata) {
// Kaydettik ama yeniden fırlatmıyoruz: ack zaten gönderildi
konsol.hata('Webhook ayrıştırma hatası', hata);
}
});İthalat base64, json
itibaren şişe İthalat Flask, request, jsonify
uygulama = Flask(__adı__)
@uygulama.rota('/webhooks/gmail', yöntemler=['POST'])
fonksiyon gmail_cobook():
# Hemen onaylayın
veri = istek.get_json(sessiz=True) veya {}
mesaj = veri.olsun('mesaj', {})
eğer 'veri' içinde Mesaj:
#: Base64 kodunu çöz ve JSON'u ayrıştır
ham = taban64.b64decode(mesaj['veri'] + '==')
yük json.yükler(ham)
# { "emailAddress": "user@gmail.com", "historyId": "12345" }
email = yük.olsun('e-posta adresi')
history_id = payload.olsun('tarihKimliği')
# Asenkron mutabakatı kuyruğa ekle
uzlaşmayı sıraya koy(e-posta, geçmiş_kimliği)
return json'a dönüştür({}), 200Kullanıcıların geçmişiyle değişiklikleri uzlaştırma.liste
Pub/Sub bildirimi size yalnızca şunu söyler bir şey değişti. Ne olduğunu söylemiyor. Aramalısın kullanıcıların.geçmişi.listesi kaydedilmiş seninle sonGeçmişKimliği gerçek farkı almak için imleç olarak.
async function Geçmişi Uzlaştır(yetki, epostaAdresi, yeniGeçmişId) {
const gmail = google.gmail({ sürüm: 'v1', auth });
// Bu kullanıcı için saklanan sonHistoryId'mizi al
const Kullanıcı = bekliyor Veritabanı.E-postaylaBul(e-postaAdresi);
const baslangicGecmisId = kullanici.sonGecmisId;
denemek {
const response = bekliyor gmail.users.history.list({
userId: 'ben',
// İmleci depolanan kimlik olarak kullanın: yeni bildirim geçmiş kimliği değil
başlangıçTarihId,
// Sadece mesaj eklemelerini filtrele (isteğe bağlı)
geçmişTipleri: ['mesajEklendi']
});
const geçmişler = response.data.history || [];
için (const (tarih kayıtları) {
için (const added of (record.messagesAdded || [])) {
// eklenen.mesaj = { id, threadId, labelIds }
bekliyor YeniMesajıİşle(auth, eklenen.mesaj.id);
}
}
// Güncellemeyi bildirimdeki yeni historyId'ye taşıma
bekliyor Veritabanı.SonGeçmişKimliğiniGüncelle(emailAdresi, yeniGeçmişId);
} catch (hata) {
eğer (err.code === 404) {
// historyId çok eski (> 7 gün). messages.list'ten yeniden başlat
bekliyor mesajlardan yeniden başlat(yetki, epostaAdresi);
} başka {
at hata;
}
}
}Pub/Sub bildirimindeki historyId şudur şimdiki devlet. Senin başlangıçTarihId olmalı önceki kaydettiğiniz değer. notification historyId'sini doğrudan startHistoryId olarak kullanmak, daha önce işlediğiniz nokta ile şimdi arasındaki tüm değişiklikleri kaçırmanıza neden olacaktır.
Pub/Sub aynı bildirimi birden fazla kez gönderebilir. Uzlaştırma mantığınızın tekrarlanamaz olmaması gerekir: aynı mesaj kimliğini iki kez işlemek hiçbir şey yapmamak anlamına gelmelidir. Veritabanınızda mesaj kimlikleri üzerinde benzersiz bir kısıtlama kullanın veya eklemeden önce varlığını kontrol edin.
7 günden eski bir başlangıç geçmişi kimliği geçirirseniz API 404 hatası döndürür. Bu durumda şuna geri dön: mesajlar.liste sıfırdan yeniden senkronize etmek için, ardından şunu çağırın kullanıcılar.izle yeni bir historyId tabanı elde etmek için tekrar.
Son historyId'niz ile şu an arasında çok sayıda değişiklik olduysa, history.list yanıtı sayfalara ayrılmış olabilir. Her zaman şu şekilde devam edin sonrakiSayfaBelirteci depolanan imlecinizi güncellemeden önce tükenene kadar.
İzleme yenileme stratejisi: 7 günlük geçerlilik sorunu
Gmail API'sinin izlemesi 7 gün sonra sessizce sona erer. Otomatik yenileme veya uyarı bildirimi yoktur. Cron işiniz başarısız olursa, yeni e-postalar gelir ancak uygulamanız hiçbir şey alamaz - her iki tarafta da hata olmaz. Bu, yenilemeyi Gmail anlık bildirimleri uygulamasının operasyonel olarak en kritik parçası haline getirir.
Her 7 günde bir değil, her gün yenileyin. Yenileme cron'unuzu her 24 saatte bir çalıştırın (her 6 veya 7 günde bir değil). İzleme yenilemesi idempotenttir - çağrılması kullanıcılar.izle Tekrar etmek, 7 günlük zamanlayıcıyı sıfırlar. Günlük bir düzen, geçici hatalara karşı size 6 günlük bir güvenlik payı sağlar.
// Daily cron: 0 3 * * * (runs at 3am daily)
async function renewAllWatches() {
// Get all authenticated users from your database
const users = await db.getAllActiveUsers();
for (const user of users) {
try {
// Refresh the access token if needed
const auth = await getAuthClient(user.id);
const gmail = google.gmail({ version: 'v1', auth });
const res = await gmail.users.watch({
userId: 'me',
requestBody: {
topicName: 'projects/YOUR_PROJECT_ID/topics/gmail-notifications',
labelIds: ['INBOX']
}
});
// Update historyId baseline : new watch returns a fresh historyId
await db.update(user.id, {
lastHistoryId: res.data.historyId,
watchExpiry: new Date(parseInt(res.data.expiration))
});
} catch (err) {
if (err.code === 401) {
// Refresh token revoked : user needs to re-authorize
await db.markUserDisconnected(user.id);
} else if (err.code === 404) {
// Watch expired : call watch again (already doing this, so 404 = retry next run)
console.warn(`Watch already expired for ${user.email}, will retry`);
} else {
// Log and continue : don't abort the entire cron for one user
console.error(`Watch renewal failed for ${user.email}`, err);
}
}
}
}Unipile, kimliği doğrulanmış her kullanıcı adına saat yenilemeyi otomatik olarak halleder. Cron işine gerek yok.
Gmail API anlık bildirimlerinde sorun giderme
Bunlar, Gmail anlık bildirim hatalarının neredeyse tamamına yol açan dört hata sınıfıdır. Aradığınızı bildiğinizde çoğunun tek bir temel nedeni vardır.
| Hata / Belirti | Temel Neden | Düzelt | Şiddet |
|---|---|---|---|
| 403 kullanıcıların izlemesinde | Gmail hizmet hesabı gmail-api-push@system.gserviceaccount.com Konu üzerinde Pub/Sub Yayıncı rolü verilmedi. |
GCP Console'da: Pub/Sub > Konular > konuşmanız > İzinler. Pub/Sub Yayıncısı rolüyle hizmet hesabını ekleyin. | Engelleyici |
| Saat başarılı ama bildirim alınmıyor | Pub/Sub aboneliği gönderme uç noktası URL'si kayıtlı değil, Google tarafından reddedildi (geçersiz TLS) veya gönderme aboneliği türü "Çek" yerine "Gönder" olarak ayarlanmış. | Aboneliğinizin "Push" türünde olduğunu ve webhook URL'nizin uç nokta olarak ayarlandığını doğrulayın. TLS sertifikasının geçerli olduğundan (kendinden imzalı olmadığından) emin olun. Test uç noktasının 200 döndürdüğünü kontrol edin. | Engelleyici |
| 404 tarih.listede - historyId çok eski | Kaydedildi sonGeçmişKimliği 7 günden eski. Gmail sadece 7 günlük geçmişi saklar. |
Geri çekil mesajlar.liste yeniden senkronize etmek için. Ardından çağırın kullanıcılar.izle yeni bir historyId temel çizgisi için. |
Geri yüklenebilir |
| Push uç noktası doğrulama belirteci reddedildi | Google bir X-Goog-Channel-Token üst bilgisi gönderir. Uç noktanız bunu doğrularsa ve belirteç eşleşmezse, 2xx olmayan bir yanıt döndürür ve Pub/Sub süresiz olarak yeniden dener. | İlk kurulum sırasında jeton doğrulamasını devre dışı bırakın ya da hem GCP abonelik ayarlarında hem de uygulama yapılandırmanızda aynı jeton değerini ayarlayın. | Geri yüklenebilir |
gmail-api-push@system.gserviceaccount.com Yayıncı Pub/Sub verilmedi.Gmail API anlık bildirimleri için kotalar ve hız sınırları
Gmail API anlık bildirimlerinin, standart Gmail API kota gruplarından farklı olarak özel kota kısıtlamaları vardır. Ana kısıtlama, kullanıcı başına olay işlem hızıdır.
Kimliği doğrulanmış kullanıcı başına maksimum Pub/Sub bildirim oranı. Ani yükselmeler geçici olarak bunu aşabilir ancak zamanla dengelenir. Bir posta kutusu sürekli olarak saniyede 1'den fazla değişiklik alırsa, bildirimler atlanmaz, gruplandırılır veya ertelenir.
Maksimum izleme süresi dolumu. Tüm izlemeler bu son tarihten önce yenilenmelidir. Gmail şunları saklar tarih.liste 7 günlük pencere için aynı verilere - 7 günden eski bir historyId 404 döndürür.
Proje başına varsayılan Gmail API günlük kota. Her kullanıcıların.geçmişi.listesi aramalar 5 birim tutar. kullanıcılar.izle her çağrı için 100 birimdir. Mutabakat hacminizi buna göre planlayın.
Yöntem başına kota, kullanıcı başına sınır ve kota artış talebi prosedürlerinin daha ayrıntılı bir dökümü için, özel bölümümüzü inceleyin. Gmail API hız sınırlamaları ve kotalar kılavuzu.
Takaslar: Pub/Sub, IMAP IDLE, yoklama ve birleşik webhook karşılaştırması
Doğru Gmail anında bildirim stratejisini seçmek, altyapı kısıtlamalarınıza, sağlayıcı kapsamı ihtiyaçlarınıza ve operasyonel toleransınıza bağlıdır. İşte dört yaklaşımın doğrudan bir karşılaştırması.
| Yaklaşım | Gecikme | Kurulum karmaşıklığı | Çoklu sağlayıcı | Ops yükü |
|---|---|---|---|---|
| Gmail Pub/Sub izleme | 1-10s | Yüksek - GCP, IAM, cron | Yalnız Gmail | 7 günlük yenileme cron |
| IMAP BOŞTA | 1-30s | Orta - kalıcı TCP | Gmail + IMAP sunucuları | Bağlantı tutma yönetimi |
| Oylama | 30-300 s gecikme | Düşük | Herhangi bir sağlayıcı | Yüksek kota yakımı |
| Birleşik webhook (Unipile) | 1-10s | Düşük - 1 webhook URL'si | Gmail + Outlook + IMAP | Yok - yönetildi |
Tek Bir Uç Noktada Gmail + Outlook + IMAP ile Birleşik Webhook Alternatifi
Gmail API anlık bildirimleri ve Outlook ile IMAP posta kutularından gelen gerçek zamanlı olaylar için, birleşik bir yük biçimiyle ve GCP altyapısı olmadan ihtiyacınız varsa, Unipile'ın sunduğu çözümler... Gmail API Tüm Pub/Sub katmanını özetler. Bağımsız bir teknik aracı olarak Unipile, kimliği doğrulanmış her kullanıcı adına, uygulamanızın zaten kontrol ettiği tek bir webhook URL'si aracılığıyla e-posta olaylarını iletmek üzere hareket eder.
Hiçbir Pub/Sub konusu oluşturulmayacak, IAM rolü yapılandırılmayacak, GCP projesi bakımı yapılmayacak. İzleme kaydı ve yenileme sizin değil, Unipile'ın altyapısı içinde gerçekleşir.
7 günlük izleme süresi, her bir bağlı hesap adına halledilir. Asla bir yenileme cron işine ihtiyacınız olmaz. Bir yenileme belirteci iptal edilirse, Unipile olayları sessizce düşürmek yerine bir hesap durumu webhook'u sunar.
Ayrıştırılmış, normalleştirilmiş bir e-posta nesnesi alırsınız - raw historyId değil. Çağırmaya gerek yok kullanıcıların.geçmişi.listesi veya kullanıcı başına imleçleri yönetmek. Unipile, farkı çözer ve yapılandırılmış mesaj verileri sunar.
Aynı webhook uç noktası ve aynı olay şeması Gmail, Outlook (Microsoft 365 / Exchange Online dahil) ve IMAP'ı kapsar. Sağlayıcı başına entegrasyon mantığı yok, Microsoft Graph abonelikleri ile Gmail yayınla-abone ol bildirimleri için ayrı webhook'lar yok.
// 1. Kullanıcının Gmail hesabını bağla (Kimliği doğrulanmış kullanıcı adına OAuth)
// Bkz: https://developer.unipile.com/docs/getting-started
2. Webhook'unuzu bir kez yapılandırın
const ayarlar = bekliyor fetch('https://api8.unipile.com:13815/api/v1/webhooks', {
method: 'POST',
headers: {
'X-API-ANAHTARI': 'SENİN_API_ANAHTARIN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
url 'https://app.you.com/webhooks/email',
etkinlikler: ['e-posta.yeni']
})
});
// 3. Birleşik ana yükü işleme: Gmail, Outlook, IMAP için aynı şekil
uygulama.POST('/webhooks/email', (req, res) => {
const { olay, hesap_kimliği, e_posta } = req.body;
// olay: "email.new"
// email.provider: "gmail" | "outlook" | "imap"
// e-posta.konu, .kimden, .kime, .govde_html...
// historyId yok. base64 yok. yönetilecek imleç yok.
GelenE-postaİşle(e-posta);
res.durum(200).son();
});Unipile paralel bir e-posta arşivi oluşturmaz veya mesaj içeriğini bağımsız olarak saklamaz. Erişimi, her kimliği doğrulanmış kullanıcının oturumuna göre kısıtlanmıştır. Unipile, her bağlı hesap adına e-posta verilerini alır ve bunları gerçek zamanlı olarak webhook uç noktanıza iletir. Webhook yükünü iletmek için gerekenden başka veri saklanmaz.
Unipile bağımsız bir teknik aracıdır. OAuth aracılığıyla uygulamanızın yetkilendirdiği her doğrulanmış kullanıcı adına hareket eder. Unipile, Google ile bağlantılı değildir, tarafından onaylanmamıştır veya sponsor edilmemiştir. Her kullanıcının kendi OAuth yetkilendirmesi altında, bu kılavuzda açıklanan aynı Gmail API uç noktalarını kullanır. Kimlik bilgileri hesaplar arasında asla paylaşılmaz. Tüm işlemler, Unipile'ın altyapısına devredilen müşteri tarafı bir karardır.
Unipile, Gmail API hız sınırlarını ve kota kısıtlamalarını kendi kota yönetim katmanı aracılığıyla uygulamanıza aktarır. Etkinlik hacmi, yoklama sıklığı ve mesaj işleme ile ilgili kararlar müşteri tarafında alınan kararlar olarak kalır. Unipile, Gmail API kota hatalarını yapılandırılmış webhook etkinlikleri olarak yüzeye çıkarır, böylece uygulamanız uygun şekilde yanıt verebilir.
Dakikalar içinde ilk Gmail hesabınızı bağlayın. GCP projesi gerekmez. Pub/Sub faturalandırması gerekmez. Yenileme süresini takip eden cron gerekmez. Bizimkini görün Gmail API entegrasyon kılavuzu ve E-posta API Sağlayıcısı Genel Bakış desteklenen tüm sağlayıcıları keşfetmek için.
Gmail API Anlık Bildirimleri - SSS
Gmail API anlık bildirimleri, Pub/Sub kurulumu, historyId, izleme yenileme ve gerçek zamanlı e-posta senkronizasyon alternatifleri hakkında en sık sorulan soruların yanıtları.
Gmail API anlık bildirimleri kullanır Google Cloud Pub/Sub Gerçek zamanlı posta kutusu değişikliği olaylarını HTTPS webhook'unuza iletmek için, bir izleme uç noktası kaydedersiniz kullanıcılar.izle, Sahip olduğunuz bir Pub/Sub konusuna bir Gmail posta kutusu bağlayan yeni bir mesaj, etiket değişikliği gibi bir değişiklik meydana geldiğinde Gmail o konuya bir bildirim yayınlar, bu da onu push webhook'unuza iletir. Ardından webhook'unuz şu şekilde çağrılır kullanıcıların.geçmişi.listesi depolanmış bir şekilde tarihKimliği gerçek mesaj farkını almak için imleç. Pub/Sub bildirimi yalnızca kullanıcı e-postasını ve yeni bir historyId'yi içerir; ileti içeriğini içermez.
kullanıcılar.izle Gmail kutusu için bir anlık bildirim aboneliği kaydeder ve bir historyId temel çizgisi döndürür. Gmail'i Pub/Sub konunuza bağlayan giriş noktasıdır. kullanıcıların.geçmişi.listesi historyId imlecinizden bu yana oluşan değişiklikleri (mesaj ekleme, silme, etiket değişiklikleri) almak için Gmail anlık bildirimini aldıktan sonra çağırdığınız uzlaştırma uç noktasıdır. Watch, Gmail'e uyarıları nereye göndereceğini bildirir. History ise neyin gerçekten değiştiğini size anlatır.
Gmail API izleme uç noktaları süresi dolar 7 gün. en iyi uygulama çalıştırmaktır. günlük cron işi her 6 veya 7 günde bir yerine, geçici arızalara karşı çok günlük bir tamponunuz olur. İzleme yenileme idempotenttir: yeni bir kullanıcılar.izle çağrısı zamanlayıcıyı sıfırlar ve yeni bir historyId tabanı döndürür. Süresi dolma sessizce gerçekleşir - uyarı bildirimi yoktur, bu nedenle başarısız bir cron, her iki tarafta da hata olmadan olayların kaçırılması anlamına gelir.
En yaygın nedeni bir eksik IAM izni. Gmail hizmet hesabını kullanır gmail-api-push@system.gserviceaccount.com yayınlamak için. Olmadan Pub/Sub Yayıncı Bu hesap için konunuzdaki rolünüz, kullanıcılar.izle başarılı oluyor ancak bildirimler hiçbir zaman teslim edilmiyor. Diğer nedenler: abonelik türü "Push" yerine "Pull", webhook uç noktanızda geçersiz TLS sertifikası veya uç noktanız 2xx olmayan yanıtlar döndürdüğü için Pub/Sub'ın teslimatı durdurması.
Bu tarihKimliği monotonically artan bir tamsayıdır ve Gmail her posta kutusu değişikliği olayı için bunu atar. Artımlı bir senkronizasyon imleci görevi görür. Kayıt olduğunuzda kullanıcılar.izle, Gmail mevcut durumu temsil eden bir historyId temelini döndürür. Sonraki Gmail anlık bildirimleri yeni bir historyId içerir. Sakladığınız (önceki) historyId'yi şuna geçirirsiniz: başlangıçTarihId için kullanıcıların.geçmişi.listesi iki nokta arasındaki tüm değişiklikleri almak için. Veritabanınızda kimliği doğrulanmış her kullanıcı için en son historyId'yi saklamalısınız. 7 günden eski historyId'ler 404 hatası döndürür.
Doğrudan Gmail API aracılığıyla değil - Gmail anlık bildirimleri için Pub/Sub gerekli teslimat kanalıdır. Ancak, bunun yerine birleşik bir e-posta API'si kullanarak GCP altyapısını tamamen atlayabilirsiniz Unipile, kimliği doğrulanmış her kullanıcı adına bağımsız bir teknik aracı görevi görerek Pub/Sub katmanını soyutlar ve Gmail anlık bildirimlerini normalleştirilmiş bir yük ile webhook'unuza teslim eder. GCP projesi, IAM izni veya izleme yenileme cron'u gerektirmez.
Koş günlük cron işi buna çağırır kullanıcılar.izle tüm aktif kimliği doğrulanmış kullanıcılar için. Döndürülen historyId'yi yeni temel çizgi olarak saklayın ve saklanan son kullanma zaman damgasını güncelleyin. Kullanıcı başına hataları toplu işlemi durdurmadan işleyin: 401, OAuth yenileme jetonunun iptal edildiği anlamına gelir (kullanıcının yeniden yetkilendirmesi gerekir), 404, izlemenin zaten süresinin dolmuş olduğu anlamına gelir. Yenilemek için asla 7 günlük sona erme tarihine kadar beklemeyin - günlük çalıştırmayı reaktif bir düzeltme olarak değil, bir bakım olarak ele alın.
Gmail API anlık bildirimleri yaklaşık olarak sınırlandırılmıştır Kimliği doğrulanmış kullanıcı başına saniyede 1 olay. Bunun üzerindeki ani yükselişler gruplandırılmış veya geciktirilmiş olup, düşürülmemiştir. kullanıcıların.geçmişi.listesi çağrı 5 kota birimi tutar ve kullanıcılar.izle çağrı başına 100 birimdir. Varsayılan Gmail API günlük kota proje başına 1 milyon birimdir. Yöntem başına limitler ve kota artırma prosedürlerinin tam bir dökümü için lütfen Gmail API hız sınırları kılavuzu.
Uygulamanız için Gmail API anlık bildirimlerini ayarlama konusunda yardıma mı ihtiyacınız var? Ekibimiz size bu konuda yardımcı olabilir.
TR 
EN 
FR 
ES 
DE 
IT 
BR 
NL 
PL