Z tego dokumentu dowiesz się, jak zarządzać powiadomieniami push w interfejsie 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. Umożliwia to wysyłanie powiadomień różnymi metodami, w tym za pomocą webhooków i sondowania, do jednego punktu końcowego 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, do którego interfejs Gmail API będzie wysyłać powiadomienia. Nazwa tematu może być dowolną nazwą wybraną w projekcie (np. matchingprojects/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 dotyczącym typu subskrypcji Cloud Pub/Sub. Skonfiguruj typ subskrypcji jako wysyłanie webhooka (czyli wywołanie zwrotne HTTP POST) lub pobieranie (czyli inicjowane przez aplikację). W ten sposób aplikacja otrzymuje powiadomienia o aktualizacjach.
Przyznawanie praw 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 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 dniu: historyId. Jeśli musisz przetworzyć zmiany przed tym terminem historyId, zapoznaj się z artykułem Synchronizowanie klientów z interfejsem Gmail API.
Dodatkowo udane wywołanie watch powoduje natychmiastowe wysłanie powiadomienia 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ć funkcję watch co najmniej raz na 7 dni. W przeciwnym razie przestaniesz otrzymywać aktualizacje dotyczące użytkownika. Zalecamy dzwonienie pod numer 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ącym 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 daje obiekt JSON zawierający 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 dotyczące użytkownika od jego ostatniej znanej
historyIddaty, zgodnie z opisem w artykule Synchronizowanie klientów z interfejsem Gmail API.
Na przykład użyj metody
history.list
do identyfikowania zmian, 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.
Odpowiedz na powiadomienia
Wszystkie powiadomienia muszą zostać potwierdzone. Jeśli używasz dostarczania za pomocą wywołania zwrotnego, potwierdzeniem powiadomienia jest pomyślna odpowiedź (np. HTTP 200).
Jeśli używasz pobierania (REST Pull, RPC Pull lub RPC StreamingPull), musisz wykonać wywołanie potwierdzające (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 próbę wysłania powiadomienia w późniejszym czasie.
Zatrzymywanie aktualizacji skrzynki pocztowej
Aby przestać otrzymywać aktualizacje 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ę. Wszystkie powiadomienia użytkowników przekraczające ten limit zostaną odrzucone. Podczas obsługi powiadomień uważaj, aby nie wywołać kolejnego powiadomienia, które może spowodować pętlę powiadomień.
Niezawodność
Zazwyczaj wszystkie powiadomienia są dostarczane w ciągu kilku sekund. W niektórych ekstremalnych sytuacjach mogą jednak 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 okresie, w którym użytkownik nie otrzymywał powiadomień, możesz okresowo wywoływać metodę 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.