LinkedIn
Instagram
WhatsApp
Telegram
Gmail
Perspektywy
Kalendarz Google
Dołącz do społeczności SlackGmail API Powiadomienia push: Kompletny przewodnik po Pub/Sub, Watch i Historii (2026)
Skonfiguruj powiadomienia push Gmail API end-to-end: utwórz temat Pub/Sub, zarejestruj punkt końcowy watch, dekoduj ładunki webhook, uzgodnij zmiany z użytkownicy.historia.lista, zautomatyzować odnawianie watchy i pominąć całą konfigurację GCP dzięki ujednoliconej alternatywie webhook.
// 1. Zarejestruj watch Gmail przez Unipile
const res = czekać fetch('https://api8.unipile.com:13815/api/v1'
+ '/konta/{id}/obserwuj', {
method: 'POST',
headers: {
'Klucz API X': 'TWÓJ_KLUCZ_API',
'Content-Type': 'application/json'
},
body: JSON.stringify({
webhook_url: 'https://app.you.com/webhooks/gmail'
})
});
// 2. Odbierz ujednolicony ładunek webhook
aplikacja.stanowisko('/webhooks/gmail', (req, res) => {
const { zdarzenie, identyfikator_konta, adres_email } = req.body;
// zdarzenie: "nowa_wiadomosc" | zhistoriid=abstrahowano
obsłużNowyEmail(e-mail);
});Powiadomienia push Gmail API to mechanizm informowania aplikacji klienckiej o zmianach w skrzynce odbiorczej Gmail użytkownika. Zamiast ciągłego odpytywania serwerów Google o nowe wiadomości (polling), aplikacje mogą zarejestrować się do otrzymywania powiadomień w czasie rzeczywistym, gdy tylko coś się zmieni.
Przed wdrożeniem powiadomień push API Gmail w środowisku produkcyjnym warto dokładnie zrozumieć, czym są, czym różnią się od prostego odpytywania oraz jaka infrastruktura jest wymagana.
Powiadomienia push do interfejsu Gmail API to mechanizm dostarczania w czasie rzeczywistym, który wykorzystuje Google Cloud Pub/Sub do wysyłania zdarzeń zmian w skrzynce pocztowej do kontrolowanego przez dewelopera punktu końcowego HTTPS. Gdy przychodzi nowa wiadomość lub istniejąca wiadomość zostanie zmodyfikowana, Gmail publikuje powiadomienie zawierające zakodowane Identyfikator Historii do tematu Pub/Sub, który posiadasz, a następnie przekazuje to zdarzenie do Twojego webhooka. Twój serwer wywołuje użytkownicy.historia.lista aby pobrać faktyczne zmiany.
Powiadomienia push Gmail API eliminują potrzebę wielokrotnego wywoływania Wiadomości.lista terminowo. Zdarzenia są dostarczane w ciągu kilku sekund od zmiany w skrzynce pocztowej, co zmniejsza opóźnienia i wykorzystanie limitu API.
Kanał dostarczania to Google Cloud Pub/Sub, a nie bezpośrednie wywołanie zwrotne HTTP z Gmail. Zwiększa to trwałość: jeśli Twój punkt końcowy jest tymczasowo niedostępny, Pub/Sub może ponawiać próbę dostarczenia zgodnie z terminem potwierdzenia subskrypcji.
Punkt końcowy nasłuchiwania Gmail API wygasa po 7 dniach. Twoja aplikacja musi go proaktywnie odnawiać za pomocą codziennego zadania cron, aby uniknąć cichego pominięcia zdarzeń. Jest to kluczowy szczegół operacyjny omówiony w sekcji Odnawianie.
Powiadomienia push Gmail API dostarczają zdarzenia w ciągu 1-10 sekund od zmiany. Brak ciągłego odpytywania oznacza niższe zużycie limitów Gmail API i szybszy czas reakcji dla Twojej aplikacji. Idealne do każdego zastosowania w czasie rzeczywistym na poziomie skrzynki odbiorczej: synchronizacja CRM, systemy zgłoszeń, automatyzacja przepływu pracy.
Sondaż Wiadomości.lista co 60 sekund jest prostsze w konfiguracji, ale wprowadza sztuczne opóźnienia, marnuje limit przy pustych odpowiedziach i słabo skaluje się przy dużej liczbie uwierzytelnionych kont użytkowników. Akceptowalne tylko dla prototypów o niskim natężeniu ruchu.
Architektura: watch + Pub/Sub + historyId w jednym przepływie
Powiadomienia push interfejsu API Gmail obejmują cztery odrębne warstwy pracujące sekwencyjnie. Zrozumienie każdej warstwy przed napisaniem kodu pozwala uniknąć najczęstszych błędów implementacji.
POSTujesz do https://gmail.googleapis.com/gmail/v1/users/me/watch z nazwą Twojego tematu Pub/Sub i opcjonalnie filtrem etykiet. Gmail zwraca Identyfikator Historii i a wygaśnięcie Znacznik czasu Unix. Przechowuj oba. Ten zegarek wygasa za 7 dni.
Gdy nastąpi jakakolwiek zmiana w obserwowany skrzynce pocztowej (nowa wiadomość, zmiana etykiety, przełączenie odczytu/nieodczytu), Gmail publikuje powiadomienie JSON w twoim temacie Cloud Pub/Sub. Ładunek to zakodowany w base64 obiekt zawierający adres e-mail użytkownika i nowy Identyfikator Historii.
Twoja subskrypcja Pub/Sub przekazuje wiadomość do zarejestrowanego punktu końcowego push HTTPS. Jest to Twój adres URL webhook, który musi odpowiedzieć kodem HTTP 200-299 w ciągu terminu potwierdzenia (domyślnie 10-600 sekund). Odpowiedź inna niż 2xx spowoduje automatyczne ponowienia.
Zdekoduj dane wiadomości Pub/Sub z bazy64. Wyodrębnij nowe Identyfikator Historii. Porównaj to z ostatniIdHistorii przechowywane w Twojej bazie danych dla tego użytkownika.
Zadzwoń użytkownicy.historia.lista z startIdHistorii ustawiona na wartość przechowywaną. Gmail zwraca wszystkie zmiany (nowe wiadomości, dodane etykiety, usunięcia) między tymi dwoma identyfikatorami. Zaktualizuj przechowywany ostatniIdHistorii do nowej wartości. Nigdy nie używaj historyId z powiadomienia Pub/Sub jako startIdHistorii bezpośrednio.
Zaplanuj codzienne zadanie cron, które wywoła użytkownicy.oglądaj ponownie dla każdego uwierzytelnionego konta użytkownika. Monitorowanie odnowienia jest idempotentne: kolejne wywołanie zastępuje poprzednią datę wygaśnięcia. Zwrócony Identyfikator Historii staje się twoją nową podstawą.
Monotonicznie rosnąca liczba całkowita przypisana przez Gmail do każdej zmiany skrzynki pocztowej. Jest to Twój kursor do synchronizacji przyrostowej. Zawsze przechowuj najnowszy `historyId` dla każdego użytkownika w swojej bazie danych.
Punkt końcowy API Gmail, który rejestruje subskrypcję powiadomień push dla skrzynki pocztowej. Zwraca bazowy identyfikator historii i sygnaturę czasową wygaśnięcia w milisekundach Unix. Musi zostać odnowiony w ciągu 7 dni.
Punkt końcowy pojednania. Podając `startHistoryId`, zwraca wszystkie dodania, usunięcia i zmiany etykiet wiadomości, które nastąpiły po tym punkcie. Tutaj uzyskasz rzeczywiste dane wiadomości.
Wymagania wstępne: projekt GCP, temat Pub/Sub, uprawnienie IAM
Powiadomienia push Gmail API wymagają trzech zasobów po stronie GCP przed pierwszymi użytkownicy.oglądaj Największa część błędów implementacyjnych wynika z braku uprawnień IAM do tematu Pub/Sub, co jest krokiem, który programiści najczęściej pomijają.
W Konsoli Google Cloud utwórz lub wybierz istniejący projekt. Przejdź do API i usługi > Biblioteka i włącz Gmail API. Również potrzebujesz API Cloud Pub/Sub włączone w tym samym projekcie. Upewnij się, że poświadczenia klienta OAuth 2.0 zawierają https://www.googleapis.com/auth/gmail.readonly zakres (lub szerszy zakres, jeśli potrzebujesz uprawnień do zapisu). W przypadku aplikacji wieloużytkownikowych, zobacz nasz przewodnik dotyczący Integracja Gmail OAuth 2.0 i Weryfikacja aplikacji Google OAuth wymagania.
W konsoli GCP w obszarze Pub/Sub > Tematy, kliknij Utwórz temat. Nadaj mu nazwę, taką jak powiadomienia gmail. Pełna nazwa tematu będzie projects/TWOJE_ID_PROJEKTU/topics/powiadomienia-gmail. Przekażesz ten dokładny ciąg znaków do użytkownicy.oglądaj w NazwaTematu pole.
To jest krok, który większość programistów przeocza. Gmail używa zarządzanego przez Google konta usługi (gmail-api-push@system.gserviceaccount.comAby publikować powiadomienia w temacie Pub/Sub. Bez przyznania temu kontu Wydawca Pub/Sub rola w twoim temacie, użytkownicy.oglądaj zostanie pomyślnie wdrożony, ale żadne powiadomienia nigdy nie zostaną dostarczone. W Konsoli: Tematy > wybierz swój temat > Uprawnienia > Dodaj podmiot > wpisz gmail-api-push@system.gserviceaccount.com przypisać rolę Wydawca Pub/Sub.
Pod swoim tematem Pub/Sub utwórz Subskrypcja push. Ustaw punkt końcowy push na adres URL swojego webhooku HTTPS (wymagany ważny certyfikat TLS, certyfikaty samopodpisane są odrzucane). Opcjonalnie skonfiguruj nagłówek walidacji tokenu, aby punkt końcowy mógł weryfikować, czy żądania pochodzą z Google. Zanotuj nazwę subskrypcji, może być ona potrzebna do monitorowania metryk dostarczania w Cloud Monitoring.
Limit 100 użytkowników dla zweryfikowanych aplikacji: Jeśli Twój ekran zgody OAuth ma status "W trakcie testowania", tylko 100 kont Gmail może autoryzować Twoją aplikację. Ten limit dotyczy wszystko Zakresy OAuth, w tym punkt końcowy watch. W przypadku wdrożeń produkcyjnych z ponad 100 użytkownikami musisz przejść proces weryfikacji Google. Zobacz nasz pełny przewodnik na temat Limit 100 użytkowników i ścieżka weryfikacji.
Brak tematu Pub/Sub. Brak uprawnienia IAM. Brak zadania cron odnawiającego obserwację co 7 dni. Zbuduj powiadomienia push Gmail za pomocą jednego adresu URL webhook.
Krok po kroku: utwórz temat, subskrypcja i użytkownik.watch
Posiadając spełnione wymagania GCP, oto kompletny kod do zarejestrowania punktu końcowego Gmail API watch w Node.js i Python, przy użyciu biblioteki klienta Google API.
const { google } = require('googleapis');
// Zakłada, że klient OAuth2 jest już autoryzowany ważnym tokenem dostępu
// Zobacz: https://www.unipile.com/gmail-oauth-20-integration-complete-guide/
async function zarejestrujGmailWatch(auth, userId = 'ja') {
const gmail = google.gmail({ wersja: 'v1', auth });
const response = czekać gmail.uzytkownicy.zegarek({
idUżytkownika,
requestBody: {
// Pełna nazwa Twojego tematu Pub/Sub
NazwaTematu: 'projects/TWOJE_ID_PROJEKTU/topics/powiadomienia-gmail',
// Opcjonalnie: filtrowanie do konkretnych etykiet
labelIds: ['SKRZYNKA'],
zachowaniefiltraetykiety 'ZAŁĄCZ'
}
});
const { historiaId, waznosc } = odpowiedz.dane;
// Przechowuj to na użytkownika w swojej bazie danych
czekać baza danych.upsert({
idUżytkownika,
lastHistoryId: historyId,
// wygaśnięcie to sygnatura czasowa Unix w milisekundach
watchExpiry: nowy Data(parseInt(wygaśnięcie)
});
konsola.log(`Obserwacja zarejestrowana. historyId: ${historyId}, wygasa: ${expiration}`);
return response.data;
}z googleapiclient.discovery import budować
z google.oauth2.credentials import Poświadczenia
def zarejestruj_gmail_obserwuj(dane logowania: Dane logowania, id_użytkownika: str = 'ja') -> dict:
"Zarejestruj powiadomienia push API Gmail dotyczące oglądania dla uwierzytelnionego użytkownika."
usługa = budować('gmail', 'v1', dane_uwierzytelniające=dane_uwierzytelniające)
ciało = {
'nazwaTematu': 'projects/TWOJE_ID_PROJEKTU/topics/powiadomienia-gmail',
'identyfikatoryEtykiet': ['SKRZYNKA'],
'zachowanieFiltrowaniaEtykiet': 'ZAŁĄCZ'
}
wynik = service.users().zegarek(userId=user_id, body=body).wykonaj()
# Przechowuj dane poszczególnych użytkowników w bazie danych
db_upsert(user_id=user_id,
last_history_id=wynik['identyfikatorHistorii'],
watch_expiry=int(wynik['wygaśnięcie']) // 1000)
return wynikObsługa ładunku powiadomień push Gmail API
Kiedy Gmail wysyła powiadomienie push, Twój punkt końcowy HTTPS otrzymuje komunikat push Pub/Sub. Rzeczywiste dane zmian Gmaila są podwójnie zakodowane: koperta Pub/Sub zawiera zakodowany w formacie base64 ciąg JSON, który sam w sobie zawiera adres e-mail użytkownika i identyfikator historii.
aplikacja.stanowisko('/webhooks/gmail', async (req, res) => {
// Potwierdź natychmiast: Pub/Sub ponawia próby w przypadku odpowiedzi innych niż 2xx
rez.status(200).koniec();
próbuj {
const wiadomosc = req.body.wiadomosc;
jeśli if (!message?.data) return;
// Dekodowanie pola danych Pub/Sub zakodowanego w Base64
const odkodowano =
Bufor.z(dane.wiadomości, 'base64').toString('utf-8');
const ładunek JSON.parsować(odkodowane);
// ładunek = { adresEmail: "user@gmail.com", identyfikatorHistorii: "12345" }
const { emailAddress, historyId } = payload;
// Roz pogodzenie kolejki (nie blokuj potwierdzenia)
czekać kolejka.dodać do kolejki({ emailAddress, historyId });
} catch (err) {
// Loguj, ale nie rzucaj ponownie: potwierdzenie zostało już wysłane
konsola.błąd('Błąd parsowania webhooka', err);
}
});import base64, json
z kieliszek import Flask, request, jsonify
aplikacja = Flaszka(__name__)
@aplikacja.trasa('/webhooks/gmail', methods=['POST'])
def gmail_webhook():
# Potwierdzić natychmiast
dane = żądanie.get_json(cichy=True) lub {}
wiadomosc = dane.uzyskać('wiadomość', {})
jeśli 'dane' w wiadomość:
# – Dekodowanie base64 i parsowanie JSON
surowe = base64.b64decodeWiadomość'dane'] + '==')
ładunek json.obciążenia(surowe)
# { "emailAddress": "user@gmail.com", "historyId": "12345" }
email = ładunek.uzyskać('adres email')
id_historii = ładunek.uzyskać('identyfikatorHistorii')
# – Dodanie do kolejki asynchronicznej synchronizacji
dodaj_do_kolejki_i_zsynchronizuj(email, identyfikator_historii)
return jsonify({}), 200Pogodzenie zmian z users.history.list
Powiadomienie Pub/Sub informuje Cię tylko coś się zmieniło. Nie mówi ci, czego. Musisz zadzwonić użytkownicy.historia.lista z twoimi zapisanymi ostatniIdHistorii jako kursor, aby uzyskać faktyczną deltę.
async function zgodaHistorii(autor, adresEmail, nowyIdHistorii) {
const gmail = google.gmail({ wersja: 'v1', auth });
// Pobierz nasz ostatni zapisany identyfikator historii dla tego użytkownika
const użytkownik = czekać baza danych.znajdźPoAdresieEmail(adresEmail);
const startHistoryId = user.ostatniIdHistorii;
próbuj {
const response = czekać gmail.users.history.list({
userId: 'ja',
// Użyj ZAPISANEGO IDENTYFIKATORA jako kursora: NIE nowego historyId powiadomienia
identyfikatorPoczątkuHistorii,
// Filtruj tylko do dodanych wiadomości (opcjonalnie)
typHistorii: ['wiadomośćDodana']
});
const historie = response.data.history || [];
dla (const kronika dziejów) {
dla (const added of (record.messagesAdded || [])) {
// dodano.wiadomość = { id, threadId, labelIds }
czekać przetwarzajNowąWiadomość(auth, added.message.id);
}
}
// Zaktualizuj kursor do nowego historyId z powiadomienia
czekać baza danych.aktualizujIdOstatniejHistorii(adresEmail, nowyIdHistorii);
} catch (err) {
jeśli (err.code === 404) {
// historyId jest za stary (> 7 dni). Zainicjuj ponownie z messages.list
czekać zainicjalizujPonownieZKomunikatów(autoryzacja, adresEmail);
} w przeciwnym razie {
rzucić błąd;
}
}
}historyId w powiadomieniu Pub/Sub to aktualny stan. startIdHistorii musi być poprzedni wartość, którą zapisałeś. Użycie bezpośrednio identyfikatora historii powiadomień jako identyfikatora historii początkowej oznacza pominięcie wszystkich zmian, które zaszły między ostatnim przetworzonym punktem a teraźniejszością.
Pub/Sub może dostarczyć to samo powiadomienie więcej niż raz. Twoja logika uzgadniania musi być idempotentna: przetwarzanie tego samego identyfikatora wiadomości dwukrotnie nie powinno wywoływać żadnych efektów. Użyj unikalnego ograniczenia na identyfikatory wiadomości w swojej bazie danych lub sprawdź istnienie przed wstawieniem.
Jeśli podasz identyfikator historii `startHistoryId` starszy niż 7 dni, interfejs API zwróci kod 404. W takim przypadku należy zastosować mechanizm wycofywania (fallback) do Wiadomości.lista aby zsynchronizować od nowa, następnie zadzwoń użytkownicy.oglądaj ponownie, aby uzyskać świeżą podstawę dla historyId.
Jeśli między Twoim ostatnim identyfikatorem historii a bieżącym momentem zaszło wiele zmian, odpowiedź `history.list` może być stronicowana. Zawsze postępuj zgodnie z tokenNastępnejStrony do wyczerpania przed aktualizacją zapamiętanego kursora.
Strategia odnawiania subskrypcji: problem 7-dniowego terminu ważności
Ustawienie Gmail API typu "watch" wygasa po 7 dniach bez żadnego powiadomienia. Nie ma automatycznego odnowienia ani ostrzeżenia. Jeśli Twój cron ulegnie awarii, nowe wiadomości e-mail nadal przychodzą, ale Twoja aplikacja nic nie otrzymuje - bez żadnych błędów po obu stronach. To sprawia, że odnowienie jest kluczowym elementem operacyjnym każdej implementacji powiadomień push Gmail.
Odnowić codziennie, nie co 7 dni. Uruchamiaj automatyczne odnawianie co 24 godziny (nie co 6 lub 7 dni). Monitorowanie odnowienia jest idempotentne - wywołanie użytkownicy.oglądaj ponownie po prostu resetuje 7-dniowy licznik. Dzienna częstotliwość zapewnia 6-dniowy bufor bezpieczeństwa przed przejściowymi awariami.
// 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 automatycznie obsługuje odnowienie zegarka w imieniu każdego uwierzytelnionego użytkownika. Nie potrzeba zadania cron.
Rozwiązywanie problemów z powiadomieniami push Gmail API
Oto cztery klasy błędów, które odpowiadają za prawie wszystkie błędy powiadomień push Gmail. Większość ma jedno podstawowe źródło, gdy już wiesz, czego szukać.
| Błąd / Objaw | Pierwotna przyczyna | Naprawić | Waga |
|---|---|---|---|
| 403 na users.watch | Konto usługi Gmail gmail-api-push@system.gserviceaccount.com nie przyznano roli wydawcy Pub/Sub dla tego tematu. |
W konsoli GCP: Pub/Sub > Tematy > Twój temat > Uprawnienia. Dodaj konto usługi z rolą Pub/Sub Publisher. | Bloker |
| zegarek działa, ale powiadomienia nie docierają | URL punktu końcowego wypychającego subskrypcji Pub/Sub nie jest zarejestrowany, odrzucony przez Google (nieprawidłowy TLS) lub typ subskrypcji wypychającej to "Pull" zamiast "Push". | Zweryfikuj, czy Twoja subskrypcja jest typu "Push", a adres URL webhooka jest punktem końcowym. Upewnij się, że certyfikat TLS jest ważny (nie jest podpisany samodzielnie). Punkt końcowy testowy zwraca 200. | Bloker |
| 404 na history.list - historyId zbyt stare | Twój magazyn ostatniIdHistorii jest starszy niż 7 dni. Gmail przechowuje historię tylko przez 7 dni. |
Cofnij się do Wiadomości.lista aby zsynchronizować ponownie. A następnie zadzwoń użytkownicy.oglądaj dla nowej historiiId jako podstawy. |
Do odzyskania |
| Token walidacji punktu końcowego skrótu odrzucony | Google wysyła nagłówek X-Goog-Channel-Token. Jeśli punkt końcowy go zweryfikuje, a token się nie zgadza, zwraca wynik inny niż 2xx, a Pub/Sub ponawia próbę w nieskończoność. | Wyłącz walidację tokenów podczas początkowej konfiguracji lub skonfiguruj tę samą wartość tokenu w ustawieniach subskrypcji GCP i w konfiguracji aplikacji. | Do odzyskania |
gmail-api-push@system.gserviceaccount.com nie przyznano roli Pub/Sub Publisher.Limity i limity szybkości dla powiadomień push Gmail API
Powiadomienia push Gmail API mają specyficzne ograniczenia kwot, które różnią się od standardowych zasobników kwot Gmail API. Kluczowym ograniczeniem jest przepustowość zdarzeń na użytkownika.
Maksymalna częstotliwość powiadomień Pub/Sub na uwierzytelnionego użytkownika. Krótkoterminowe skoki mogą tymczasowo przekroczyć ten limit, ale są ograniczane w czasie. Jeśli skrzynka pocztowa otrzymuje więcej niż 1 zmianę na sekundę przez dłuższy czas, powiadomienia zostaną połączone w partie lub opóźnione, a nie odrzucone.
Maksymalny termin wygaśnięcia zegarków. Wszystkie zegarki muszą zostać odnowione przed tym terminem. Gmail przechowuje historia.lista dane dla tego samego 7-dniowego okna - identyfikator historii starszy niż 7 dni zwraca 404.
Domyślny dzienny limit Gmail API na projekt. użytkownicy.historia.lista połączenie kosztuje 5 jednostek. użytkownicy.oglądaj kosztuje 100 jednostek za połączenie. Dostosuj odpowiednio swój wolumen uzgodnień.
Aby uzyskać bardziej szczegółowe informacje na temat limitów na metodę, limitów na użytkownika i procedur ubiegania się o zwiększenie limitów, zobacz naszą stronę dedykowaną Limitowanie żądań i limity kwot dla Gmail API.
Kompromisy: Pub/Sub vs IMAP IDLE vs polling vs zunifikowane webhooki
Wybór odpowiedniej strategii powiadomień push w Gmailu zależy od ograniczeń infrastrukturalnych, potrzeb w zakresie zasięgu dostawcy i tolerancji operacyjnej. Oto bezpośrednie porównanie czterech podejść.
| Podejście | Opóźnienie | Złożoność konfiguracji | Wielu dostawców | Narzut operacyjny |
|---|---|---|---|---|
| Monitorowanie Gmail Pub/Sub | 1-10s | Wysokie - GCP, IAM, cron | Tylko Gmail | 7-dniowe odnowienie cron |
| IMAP IDLE | 1-30s | Średnio - trwałe TCP | gmail + serwery IMAP | Zarządzanie połączeniem "keep-alive" |
| Sondaż | 30-300s opóźnienia | Niski | Każdy dostawca | Wysoki limit spalania |
| Ujednolicony webhook (Unipile) | 1-10s | Niski - 1 adres URL webhooka | Gmail + Outlook + IMAP | Nie dotyczy - zarządzany |
Zunifikowana Alternatywa dla Webhooków: Gmail + Outlook + IMAP z jednym endpointem
Jeśli potrzebujesz powiadomień push przez Gmail API plus zdarzeń w czasie rzeczywistym ze skrzynek pocztowych Outlook i IMAP – ze ujednoliconym formatem ładunku i bez infrastruktury GCP – Unipile's Gmail API abstrahuje całą warstwę Pub/Sub. Jako niezależny pośrednik techniczny, Unipile działa w imieniu każdego uwierzytelnionego użytkownika, dostarczając zdarzenia poczty e-mail za pośrednictwem jednego adresu URL webhooka, nad którym Twoja aplikacja już sprawuje kontrolę.
Brak tematu Pub/Sub do utworzenia, brak uprawnień IAM do skonfigurowania, brak projektu GCP do utrzymania. Rejestracja i odnawianie obserwacji odbywa się w infrastrukturze Unipile, a nie Twojej.
7-dniowe wygaśnięcie zegarka jest obsługiwane w imieniu każdego połączonego konta. Nigdy nie potrzebujesz zadania cron do odnawiania. Jeśli token odświeżania zostanie unieważniony, Unipile zamiast cicho pomijać zdarzenia, wyświetla webhook stanu konta.
Otrzymujesz sparsowany, znormalizowany obiekt wiadomości e-mail - nie surowy identyfikator historii. Nie ma potrzeby wywoływania użytkownicy.historia.lista albo zarządzać kursorami dla poszczególnych użytkowników. Unipile rozwiązuje deltę i dostarcza ustrukturyzowane dane wiadomości.
Ten sam punkt końcowy webhooka i ten sam schemat zdarzeń obejmują Gmail, Outlook (w tym Microsoft 365/Exchange Online) i IMAP. Brak logiki integracji specyficznej dla dostawcy, brak oddzielnych webhooków dla subskrypcji Microsoft Graph w porównaniu do powiadomień publikuj/subskrybuj Gmaila.
// 1. Połącz konto Gmail użytkownika (OAuth w imieniu uwierzytelnionego użytkownika)
// Zobacz: https://developer.unipile.com/docs/getting-started
// 2. Skonfiguruj swój webhook raz
const konfiguracja = czekać fetch('https://api8.unipile.com:13815/api/v1/webhooks', {
method: 'POST',
nagłówki: {
'Klucz API X': 'TWÓJ_KLUCZ_API',
'Content-Type': 'application/json'
},
body: JSON.stringify({
adres url 'https://app.you.com/webhooks/email',
wydarzenia: ['email.nowy']
})
});
// 3. Obsłuż ujednoliconą strukturę danych: taki sam kształt dla Gmail, Outlook, IMAP
aplikacja.stanowisko('/webhooks/email', (req, res) => {
const { zdarzenie, identyfikator_konta, adres_email } = req.body;
// zdarzenie: "email.nowy"
// email.provider: "gmail" | "outlook" | "imap"
// temat_emaila, .od, .do, .html_treści...
// Brak historyId. Brak base64. Brak kursora do zarządzania.
przetwarzajEmailPrzychodzący(e-mail);
rez.status(200).koniec();
});Unipile nie tworzy równoległego archiwum poczty e-mail ani nie przechowuje treści wiadomości niezależnie. Dostęp jest ograniczony do sesji każdego uwierzytelnionego użytkownika. Unipile pobiera dane poczty e-mail w imieniu każdego połączonego konta i dostarcza je do Twojego punktu końcowego webhook w czasie rzeczywistym. Żadne dane nie są przechowywane poza tym, co jest niezbędne do dostarczenia ładunku webhook.
Unipile jest niezależnym pośrednikiem technicznym. Działa w imieniu każdego uwierzytelnionego użytkownika, który autoryzował aplikację za pomocą OAuth. Unipile nie jest powiązany, wspierany ani sponsorowany przez Google. Korzysta z tych samych punktów końcowych Gmail API opisanych w tym przewodniku, na użytkownika, w ramach autoryzacji OAuth danego użytkownika. Dane uwierzytelniające nigdy nie są udostępniane między kontami. Wszystkie operacje są decyzją po stronie klienta delegowaną do infrastruktury Unipile.
Unipile przekazuje limity szybkości i ograniczenia kwotowe API Gmail do Twojej aplikacji poprzez własną warstwę zarządzania kwotami. Decyzje dotyczące liczby zdarzeń, częstotliwości odpytywania i obsługi wiadomości pozostają decyzją klienta. Unipile udostępnia błędy kwotowe API Gmail jako ustrukturyzowane zdarzenia webhook, dzięki czemu Twoja aplikacja może odpowiednio zareagować.
Połącz swoje pierwsze konto Gmail w kilka minut. Bez projektu GCP. Bez rozliczeń Pub/Sub. Bez resetowania odnowienia przez cron. Zobacz nasze Przewodnik po integracji z Gmail API i Przegląd dostawców API e-mail aby poznać wszystkich obsługiwanych dostawców.
Powiadomienia Push Gmail API - FAQ
Odpowiedzi na najczęstsze pytania dotyczące powiadomień push API Gmail, konfiguracji Pub/Sub, identyfikatora historycznego, odnawiania usługi "watch" oraz alternatyw dla synchronizacji wiadomości e-mail w czasie rzeczywistym.
Powiadomienia push w Gmail API Google Cloud Pub/Sub aby dostarczać zdarzenia zmiany skrzynki pocztowej w czasie rzeczywistym do Twojego webhooka HTTPS. Rejestrujesz punkt końcowy obserwacji za pośrednictwem użytkownicy.oglądaj, łącząca skrzynkę Gmail z należącym do Ciebie tematem Pub/Sub. Gdy wystąpi zmiana - nowa wiadomość, zmiana etykiety - Gmail publikuje powiadomienie w tym temacie, który przekazuje je do Twojego webhooka push. Twój webhook następnie wywołuje użytkownicy.historia.lista z zapisanym Identyfikator Historii kursor do pobrania faktycznej delty wiadomości. Sama powiadomienie Pub/Sub zawiera jedynie adres e-mail użytkownika i nowy identyfikator historii — brak treści wiadomości.
użytkownicy.oglądaj rejestruje subskrypcję powiadomień push dla skrzynki pocztowej Gmail i zwraca identyfikator historii jako bazę. Jest to punkt wejścia, który łączy Gmail z Twoim tematem Pub/Sub. użytkownicy.historia.lista endpoint uzgadniania, który wywołujesz po otrzymaniu powiadomienia push z Gmaila, aby uzyskać faktyczne zmiany (dodania, usunięcia wiadomości, zmiany etykiet), które nastąpiły od czasu ostatniego zapisanego kursora historyId. Watch mówi Gmailowi, gdzie wysyłać alerty. History mówi ci, co faktycznie się zmieniło.
kończą ważność po 7 dni. Najlepszą praktyką jest uruchomienie codzienny cron job zamiast co 6 lub 7 dni, zapewniając tym samym wielodniowy bufor przed przejściowymi awariami. Odnowienie zasobu jest idempotentne: nowe użytkownicy.oglądaj Wywołanie po prostu resetuje licznik i zwraca nowy identyfikator historii (historyId) jako punkt odniesienia. Wygasanie odbywa się bezszelestnie - nie ma powiadomienia ostrzegawczego, więc nieudane zadanie cron oznacza pominięte zdarzenia bez żadnych błędów po żadnej ze stron.
Najczęstszą przyczyną jest brak uprawnienia IAM. Gmail korzysta z konta usługi gmail-api-push@system.gserviceaccount.com aby opublikować w wątku Pub/Sub. Bez Wydawca Pub/Sub rola na Twój temat dla tego konta, użytkownicy.oglądaj powodzenia, ale żadne powiadomienia nigdy nie są dostarczane. Inne przyczyny: typ subskrypcji to "Pull" zamiast "Push", nieprawidłowy certyfikat TLS w punkcie końcowym webhooka lub punkt końcowy zwraca odpowiedzi inne niż 2xx, powodując zaprzestanie dostarczania przez Pub/Sub.
The Identyfikator Historii jest monotonicznie rosnącą liczbą całkowitą, którą Gmail przypisuje do każdego zdarzenia zmiany skrzynki pocztowej. Działa ona jako przyrostowy kursor synchronizacji. Kiedy rejestrujesz użytkownicy.oglądaj, Gmail zwraca identyfikator historii (historyId) jako punkt odniesienia reprezentujący bieżący stan. Kolejne powiadomienia push z Gmaila zawierają nowy identyfikator historii. Przekazujesz swój zapisany (poprzedni) identyfikator historii jako startIdHistorii do użytkownicy.historia.lista aby uzyskać wszystkie zmiany między dwoma punktami. Musisz przechowywać najnowszy identyfikator historii na uwierzytelnionego użytkownika w swojej bazie danych. Identyfikatory historii starsze niż 7 dni zwracają błąd 404.
Nie bezpośrednio przez Gmail API – Pub/Sub to wymagany kanał dostarczania dla powiadomień push Gmail. Możesz jednak całkowicie pominąć infrastrukturę GCP, korzystając z jednolitego API poczty e-mail, takiego jak Unipile, która działa jako niezależny pośrednik techniczny w imieniu każdego uwierzytelnionego użytkownika, abstrahuje warstwę Pub/Sub i dostarcza powiadomienia push z Gmaila do Twojego webhooka ze znormalizowanym ładunkiem. Nie jest wymagany żaden projekt GCP, żadne uprawnienie IAM ani odnawianie zadań cron.
Uruchom codzienny cron job że woła użytkownicy.oglądaj dla wszystkich aktywnych uwierzytelnionych użytkowników. Zapisz zwrócone historyId jako nową bazę i zaktualizuj zapisany znacznik czasu wygaśnięcia. Obsłuż błędy dla poszczególnych użytkowników bez przerywania zadania wsadowego: kod 401 oznacza, że token odświeżania OAuth został unieważniony (użytkownik musi ponownie autoryzować), kod 404 oznacza, że obserwacja już wygasła. Nigdy nie czekaj do 7-dniowego terminu wygaśnięcia, aby odnowić – traktuj codzienny bieg jako konserwację, a nie reaktywną poprawkę.
Powiadomienia push Gmail API są ograniczone do około 1 zdarzenie na sekundę na uwierzytelnionego użytkownika. Przebicia powyżej tego progu są grupowane lub opóźniane, nie odrzucane. użytkownicy.historia.lista połączenie kosztuje 5 jednostek kwoty i użytkownicy.oglądaj kosztuje 100 jednostek za wywołanie. Domyślny dzienny limit Google Workspace API wynosi 1 milion jednostek na projekt. Pełne zestawienie limitów dla poszczególnych metod i procedury zwiększania kwot można znaleźć w naszej dokumentacji. Przewodnik po limitach użycia Gmail API.
Potrzebujesz pomocy w skonfigurowaniu powiadomień push dla Gmail API w Twojej aplikacji? Nasz zespół może Ci w tym pomóc.
PL 
EN 
FR 
ES 
DE 
IT 
BR 
NL 
TR