Opis
Interfejs Gmail API udostępnia powiadomienia push na serwerze, dzięki którym możesz obserwować zmiany w skrzynkach pocztowych Gmaila. Możesz użyć tej funkcji, aby poprawić wydajność aplikacji. Pozwala wyeliminować dodatkowe koszty sieci i mocy obliczeniowej związane z zasobami odpytywania w celu określenia, czy się nie zmieniły. Po każdej zmianie skrzynki pocztowej interfejs Gmail API powiadamia aplikację serwera backendu.
Początkowa konfiguracja Cloud Pub/Sub
Interfejs Gmail API używa interfejsu Cloud Pub/Sub API do dostarczania powiadomień push. Umożliwia to przesyłanie powiadomień za pomocą różnych metod, w tym webhooków i ankiet w pojedynczym punkcie końcowym subskrypcji.
Wymagania wstępne
Aby dokończyć konfigurację, sprawdź, czy spełniasz wymagania wstępne Cloud Pub/Sub, a potem skonfiguruj klienta Cloud Pub/Sub.
Tworzenie tematu
Za pomocą klienta Cloud Pub/Sub utwórz temat, na który interfejs Gmail API ma wysyłać powiadomienia. Nazwa tematu może być dowolną nazwą projektu (tzn. odpowiadającą projects/myproject/topics/*, gdzie myproject to identyfikator projektu podany w Google Developers Console).
Ze względu na limity Cloud Pub/Sub dotyczące liczby tematów zalecamy używanie jednego tematu dla wszystkich powiadomień push z interfejsu Gmail API dla Twojej aplikacji.
Tworzenie subskrypcji
Postępuj zgodnie z przewodnikiem dla subskrybentów Cloud Pub/Sub, aby skonfigurować subskrypcję utworzonego tematu. Skonfiguruj typ subskrypcji jako webhooka push (tj. wywołanie zwrotne HTTP POST) albo pull (tj. przez aplikację). W ten sposób aplikacja będzie otrzymywać powiadomienia o aktualizacjach.
Przyznawanie uprawnień do publikowania na temat
Cloud Pub/Sub wymaga przyznania w Gmailu uprawnień do publikowania powiadomień dotyczących Twojego tematu.
Aby to zrobić, musisz przyznać uprawnienia publish użytkownikowi gmail-api-push@system.gserviceaccount.com. Aby to zrobić, skorzystaj z interfejsu uprawnień konsoli programisty Cloud Pub/Sub, postępując zgodnie z instrukcjami kontroli dostępu na poziomie zasobu.
Otrzymywanie aktualizacji skrzynki pocztowej Gmaila
Po zakończeniu wstępnej konfiguracji Cloud Pub/Sub skonfiguruj konta Gmail, aby wysyłać powiadomienia o aktualizacjach skrzynki pocztowej.
Prośba dotycząca zegarka
Aby skonfigurować wysyłanie powiadomień na temat Cloud Pub/Sub, użyj klienta Gmail API do wywołania watch ze skrzynki pocztowej użytkownika Gmaila, podobnie jak w przypadku jakiegokolwiek innego wywołania interfejsu Gmail API.
Aby to zrobić, wpisz utworzoną powyżej nazwę tematu i wszystkie inne opcje w żądaniu watch, np. labels, według których chcesz filtrować. Jeśli na przykład chcesz otrzymywać powiadomienia po wprowadzeniu zmian w skrzynce odbiorczej:
Protokół
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()
Obejrzyj odpowiedź
Jeśli żądanie watch zostanie zrealizowane, otrzymasz taką odpowiedź:
{
historyId: 1234567890
expiration: 1431990098200
}
z bieżącą skrzynką pocztową historyId dla użytkownika. O wszelkich późniejszych zmianach historyId otrzyma powiadomienie z klientem. Jeśli musisz wprowadzić zmiany
przed tym historyId, zapoznaj się z przewodnikiem na temat synchronizacji.
Dodatkowo udane wywołanie watch powinno spowodować natychmiastowe wysłanie powiadomienia do tematu Cloud Pub/Sub.
Jeśli podczas wywołania watch pojawi się błąd, szczegóły powinny wyjaśnić źródło problemu, co zwykle jest związane z konfiguracją tematu i subskrypcji Cloud Pub/Sub. W dokumentacji Cloud Pub/Sub znajdziesz informacje o tym, czy konfiguracja jest prawidłowa, i pomoc w rozwiązaniu problemów z tematem i subskrypcją.
Odnawiam zegarek skrzynki pocztowej
Musisz wywoływać watch co najmniej co 7 dni. W przeciwnym razie przestaniesz otrzymywać powiadomienia dotyczące tego użytkownika. Zalecamy używanie metody watch raz dziennie. Odpowiedź watch ma też pole daty ważności z sygnaturą czasową wygaśnięcia watch.
Otrzymywanie powiadomień
Za każdym razem, gdy nastąpi aktualizacja skrzynki pocztowej odpowiadająca watch, aplikacja otrzyma powiadomienie z opisem zmiany.
Jeśli masz skonfigurowaną subskrypcję push, powiadomienie webhooka na Twoim serwerze otrzyma postać 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"
}
Treść POST HTTP jest w formacie JSON, a rzeczywisty ładunek powiadomienia Gmaila znajduje się w polu message.data. To pole message.data jest ciągiem zakodowanym w base64url, który odkoduje do obiektu JSON zawierającego adres e-mail i nowy identyfikator historii skrzynki pocztowej użytkownika:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Następnie możesz użyć history.list, aby uzyskać szczegóły zmian użytkownika od momentu jego ostatniego znanego parametru historyId, zgodnie z przewodnikiem po synchronizacji.
Jeśli zamiast tego masz skonfigurowaną subskrypcję pull, zapoznaj się z przykładowym kodem w przewodniku dotyczącym pobierania wiadomości dla subskrybentów Cloud Pub/Sub, aby dowiedzieć się więcej o otrzymywaniu wiadomości.
Reagowanie na powiadomienia
Wszystkie powiadomienia muszą zostać potwierdzone. Jeśli korzystasz z przesyłania push webhooka, wtedy wysłanie odpowiedzi (np. HTTP 200) spowoduje potwierdzenie otrzymania powiadomienia.
Jeśli używasz dostawy pull (pobieranie REST, wyciąganie RPC lub RPC StreamingPull), musisz wywołać wywołanie potwierdzające (REST lub RPC). Więcej informacji na temat asynchronicznego lub synchronicznego potwierdzania wiadomości za pomocą oficjalnych bibliotek klienta opartych na RPC znajdziesz w przykładowym kodzie w przewodniku pobierania dla subskrybentów Cloud Pub/Sub.
Jeśli powiadomienia nie zostaną potwierdzone (np. wywołanie zwrotne webhooka zwróci błąd lub przekroczenie limitu czasu), Cloud Pub/Sub spróbuje ponownie wysłać powiadomienie później.
Zatrzymywanie aktualizacji skrzynki pocztowej
Aby nie otrzymywać już powiadomień do skrzynki pocztowej, zadzwoń pod numer stop. Wszystkie nowe powiadomienia powinny przestać się pojawiać w ciągu kilku minut.
Ograniczenia
Maksymalna częstotliwość powiadomień
Maksymalna częstotliwość powiadomień wysyłanych przez każdego obserwowanego użytkownika Gmaila wynosi 1 zdarzenie na sekundę. Wszystkie powiadomienia użytkownika powyżej tego częstotliwości będą usuwane. Zachowaj ostrożność podczas obsługi powiadomień, aby nie aktywować kolejnego powiadomienia, ponieważ mogłoby to spowodować zapętlenie powiadomień.
Niezawodność
Zazwyczaj wszystkie powiadomienia są dostarczane niezawodnie w ciągu kilku sekund. Jednak w niektórych skrajnych sytuacjach mogą one być opóźnione lub pominięte.
Uwzględnij tę możliwość w odpowiedni sposób, aby aplikacja nadal synchronizowała się, nawet jeśli nie otrzymano żadnych komunikatów push. Możesz na przykład co jakiś czas wywoływać metodę history.list po upływie okresu bez powiadomień od użytkownika.
Ograniczenia Cloud Pub/Sub
Interfejs Cloud Pub/Sub API ma też swoje ograniczenia, które szczegółowo opisujemy w dokumentacji pricing i quotas.