Z tego dokumentu dowiesz się, jak zarządzać powiadomieniami push za pomocą interfejsu Gmail API.
Interfejs Gmail API udostępnia powiadomienia push z serwera, które umożliwiają monitorowanie zmian w skrzynkach pocztowych Gmaila. Używaj tej funkcji, aby zwiększać wydajność aplikacji. Eliminuje to dodatkowe koszty sieciowe i obliczeniowe związane z odpytywaniem zasobów w celu sprawdzenia, czy uległy zmianie. Za każdym razem, gdy skrzynka pocztowa ulegnie zmianie, 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. Dzięki temu możesz otrzymywać powiadomienia różnymi metodami, w tym za pomocą webhooków i odpytywania w jednym punkcie końcowym subskrypcji.
Wymagania wstępne
Aby dokończyć konfigurację, spełnij wymagania wstępne dotyczące Cloud Pub/Sub, a następnie skonfiguruj klienta Cloud Pub/Sub.
Tworzenie tematu
Za pomocą klienta Cloud Pub/Sub utwórz temat, na który interfejs Gmail API będzie wysyłać powiadomienia. Nazwa tematu może być dowolną nazwą wybraną w projekcie (np. matching-projects/myproject/topics/*, gdzie myproject to identyfikator projektu podany w konsoli Google Cloud).
Tworzenie subskrypcji
Aby skonfigurować subskrypcję utworzonego tematu, postępuj zgodnie z instrukcjami w przewodniku Typ subskrypcji Cloud Pub/Sub. Skonfiguruj typ subskrypcji jako wysyłanie webhooka (czyli wywołanie zwrotne HTTP POST) lub pobieranie (czyli inicjowane przez Twoją aplikację). W ten sposób aplikacja otrzymuje powiadomienia o aktualizacjach.
Przyznawanie uprawnień do publikowania w temacie
Cloud Pub/Sub wymaga, aby przyznać Gmailowi uprawnienia do publikowania powiadomień w Twoim temacie.
Aby to zrobić, przyznaj uprawnienia publish do gmail-api-push@system.gserviceaccount.com. Możesz to zrobić w konsoli uprawnień Cloud Pub/Sub w konsoli Google Cloud, postępując zgodnie z tymi instrukcjami dotyczącymi kontroli dostępu.
Konfiguracja udostępniania z ograniczeniem do domeny w Twojej organizacji może uniemożliwiać przyznawanie uprawnień do publikowania. Aby rozwiązać ten problem, możesz skonfigurować wyjątek dla tego konta usługi.
Otrzymywanie aktualizacji skrzynki pocztowej Gmail
Po zakończeniu wstępnej konfiguracji Cloud Pub/Sub skonfiguruj konta Gmail, aby wysyłać powiadomienia o aktualizacjach skrzynki pocztowej.
Prośba o obejrzenie
Aby skonfigurować konta Gmail tak, aby wysyłały powiadomienia do tematu Cloud Pub/Sub, użyj klienta Gmail API, aby wywołać metodę watch w skrzynce pocztowej użytkownika Gmail. Działa to podobnie jak w przypadku każdego innego wywołania interfejsu Gmail API. W żądaniu watch podaj utworzoną nazwę tematu i inne opcje, np. labels, aby zastosować filtr. Na przykład użyj tego żądania, aby otrzymywać powiadomienia o każdej zmianie 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 odpowiedź podobną do tej:
{
"historyId": "1234567890",
"expiration": "1431990098200"
}
Odpowiedź zawiera bieżącą skrzynkę pocztową historyId użytkownika. Klient będzie otrzymywać powiadomienia o wszystkich zmianach po tym czasie historyId. Jeśli musisz przetworzyć zmiany przed tym terminem historyId, zapoznaj się z artykułem Synchronizowanie klientów z Gmailem.
Dodatkowo udane wywołanie watch natychmiast wysyła powiadomienie do tematu Cloud Pub/Sub.
Jeśli otrzymasz błąd z wywołania watch, szczegóły powinny wyjaśniać źródło problemu. Zwykle jest to problem z konfiguracją tematu i subskrypcji Cloud Pub/Sub. Aby sprawdzić, czy konfiguracja jest prawidłowa, i uzyskać pomoc w rozwiązywaniu problemów z tematami i subskrypcjami, zapoznaj się z dokumentacją Cloud Pub/Sub.
Odnawianie obserwowania skrzynki pocztowej
Musisz wywoływać metodę watch co najmniej raz na 7 dni, w przeciwnym razie przestaniesz otrzymywać aktualizacje dotyczące użytkownika.
Zalecamy wywoływanie funkcji watch raz dziennie. Odpowiedź metody watch zawiera też pole expiration z sygnaturą czasową wygaśnięcia watch.
otrzymywanie powiadomień;
Gdy w skrzynce pocztowej nastąpi aktualizacja zgodna z Twoim watch, aplikacja otrzyma wiadomość z powiadomieniem opisującą zmianę.
Jeśli skonfigurowano subskrypcję push, powiadomienie webhooka wysyłane na serwer jest zgodne z tym formatem: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ść żądania HTTP POST jest w formacie JSON, a rzeczywisty ładunek powiadomienia Gmaila znajduje się w polu message.data. Pole message.data to ciąg tekstowy zakodowany w standardzie Base64URL, który po zdekodowaniu staje się obiektem JSON zawierającym adres e-mail i nowy identyfikator historii skrzynki pocztowej użytkownika:
{"emailAddress": "user@example.com", "historyId": "9876543210"}
Następnie możesz użyć metody
history.list
aby uzyskać szczegóły zmian użytkownika od ostatniej znanej
historyId, zgodnie z opisem w artykule
Synchronizowanie klientów z Gmailem.
Na przykład użyj metody history.list, aby zidentyfikować zmiany, które zaszły między początkowym żądaniem watch a otrzymaniem wiadomości z powiadomieniem udostępnionej w poprzednim przykładzie. Przekaż 1234567890 jako startHistoryId do history.list. Następnie możesz zapisać wartość 9876543210 jako ostatnią znaną historyId do wykorzystania w przyszłości.
Jeśli zamiast tego skonfigurowano subskrypcję typu pull, więcej informacji o odbieraniu wiadomości znajdziesz w przykładowych kodach w przewodniku po subskrypcjach typu pull w Cloud Pub/Sub (w języku angielskim).
Odpowiedz na powiadomienia
Musisz potwierdzić wszystkie powiadomienia. Jeśli używasz dostarczania za pomocą webhooka, odpowiedź o sukcesie (np. HTTP 200) potwierdza powiadomienie.
Jeśli używasz pobierania (pobieranie REST, pobieranie RPC lub pobieranie strumieniowe RPC), musisz potwierdzać odbiór wiadomości za pomocą metody potwierdzania REST lub RPC. Więcej informacji o potwierdzaniu wiadomości asynchronicznie lub synchronicznie przy użyciu oficjalnych bibliotek klienta opartych na RPC znajdziesz w przykładach kodu w przewodniku subskrypcje pull Cloud Pub/Sub.
Jeśli nie potwierdzisz powiadomień (np. jeśli wywołanie zwrotne webhooka zwróci błąd lub przekroczy limit czasu), Cloud Pub/Sub ponowi wysyłanie powiadomienia w późniejszym czasie.
Zatrzymywanie aktualizacji skrzynki pocztowej
Aby przestać otrzymywać aktualizacje dotyczące skrzynki pocztowej, wywołaj metodę stop. Wszystkie nowe powiadomienia powinny przestać się pojawiać w ciągu kilku minut.
Ograniczenia
Oto ograniczenia związane z używaniem powiadomień push z serwera:
Maksymalna liczba powiadomień
Każdy obserwowany użytkownik Gmaila ma maksymalną częstotliwość powiadomień wynoszącą 1 zdarzenie na sekundę. Usługa odrzuca powiadomienia użytkowników przekraczające ten limit. Podczas obsługi powiadomień uważaj, aby nie wywołać kolejnego powiadomienia, które może spowodować pętlę powiadomień.
Niezawodność
Zwykle Cloud Pub/Sub dostarcza powiadomienia w ciągu kilku sekund. W rzadkich przypadkach powiadomienia mogą być opóźnione lub pominięte. Zadbaj o to, aby aplikacja nadal synchronizowała dane, nawet jeśli nie otrzymuje wiadomości push. Na przykład po pewnym czasie, w którym użytkownik nie otrzymywał powiadomień, możesz wrócić do okresowego wywoływania metody history.list.
Ograniczenia Cloud Pub/Sub
Interfejs Cloud Pub/Sub API ma też własne ograniczenia, które są szczegółowo opisane w dokumentacji dotyczącej cen i limitów.