Powiadomienia push

Przegląd

Interfejs Gmail API udostępnia powiadomienia push serwera, które umożliwiają monitorowanie zmian w skrzynkach pocztowych Gmaila. Możesz użyć tej funkcji, aby zwiększyć wydajność aplikacji. Pozwala to wyeliminować 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 powiadamianie różnymi metodami, w tym za pomocą webhooków i sondowania w jednym punkcie końcowym subskrypcji.

Wymagania wstępne

Aby dokończyć konfigurację, upewnij się, że spełniasz 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 ramach projektu (np. pasującą do wzorca projects/myproject/topics/*, gdzie myproject to identyfikator projektu podany w Google Developers Console).

Tworzenie subskrypcji

Postępuj zgodnie z przewodnikiem po subskrybentach Cloud Pub/Sub, aby skonfigurować subskrypcję utworzonego tematu. Skonfiguruj typ subskrypcji jako push webhooka (czyli wywołanie zwrotne HTTP POST) lub pull (czyli inicjowany przez Twoją aplikację). W ten sposób aplikacja będzie otrzymywać 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ć, musisz przyznać publish uprawnienia do gmail-api-push@system.gserviceaccount.com. Możesz to zrobić za pomocą interfejsu uprawnień w konsoli deweloperskiej Cloud Pub/Sub, postępując zgodnie z instrukcjami dotyczącymi kontroli dostępu na poziomie zasobów.

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ć watch w skrzynce pocztowej użytkownika Gmaila, podobnie jak w przypadku każdego innego wywołania interfejsu Gmail API. Aby to zrobić, podaj nazwę tematu utworzoną powyżej i inne opcje w żądaniu watch, np. labels, aby filtrować. Jeśli na przykład chcesz 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()

Odpowiedź na zegarku

Jeśli żądanie watch zostanie zrealizowane, otrzymasz odpowiedź podobną do tej:

{
  historyId: 1234567890
  expiration: 1431990098200
}

z bieżącą skrzynką pocztową historyId użytkownika. O wszystkich zmianach wprowadzonych po tym terminiehistoryId poinformujemy Twojego klienta. Jeśli musisz przetworzyć zmiany przed tym terminem historyId, zapoznaj się z przewodnikiem po synchronizacji.

Dodatkowo udane wywołanie watch powinno spowodować natychmiastowe wysłanie powiadomienia do tematu Cloud Pub/Sub.

Jeśli wywołanie watch zwróci błąd, szczegóły powinny wyjaśniać źródło problemu, które zwykle jest związane 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.

Odnowienie zegarka skrzynki pocztowej

Musisz ponownie wywołać funkcję watch co najmniej co 7 dni, w przeciwnym razie przestaniesz otrzymywać aktualizacje dotyczące użytkownika. Zalecamy wywoływanie funkcji watch raz dziennie. Odpowiedź watch zawiera też pole ważności z sygnaturą czasową wygaśnięcia watch.

Otrzymywanie powiadomień

Gdy w skrzynce pocztowej pojawi się aktualizacja zgodna z Twoimi watch, aplikacja otrzyma wiadomość z powiadomieniem opisującą zmianę.

Jeśli masz skonfigurowaną subskrypcję push, powiadomienie webhook do Twojego serwera będzie zgodne z tym 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 znaków 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ć history.list, aby uzyskać szczegóły zmian użytkownika od czasu jego ostatniego znanego identyfikatora historii, zgodnie z przewodnikiem synchronizacji.

Na przykład, aby użyć history.list do identyfikowania zmian, które zaszły między początkowym wywołaniem watch a otrzymaniem wiadomości z powiadomieniem udostępnionej w poprzednim przykładzie, przekaż 1234567890 jako startHistoryId do history.list. Następnie9876543210 można zapisać jako ostatni znany identyfikator historyId do wykorzystania w przyszłości.

Jeśli zamiast tego skonfigurowano subskrypcję typu pull, zapoznaj się z przykładowymi kodami w przewodniku po pobieraniu wiadomości przez subskrybenta Cloud Pub/Sub, aby dowiedzieć się więcej o odbieraniu wiadomości.

Odpowiadanie na powiadomienia

Wszystkie powiadomienia muszą zostać potwierdzone. Jeśli używasz dostarczania typu push za pomocą webhooka, potwierdzeniem powiadomienia będzie pomyślna odpowiedź (np. HTTP 200).

Jeśli używasz pobierania typu pull (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 po pobieraniu wiadomości przez subskrybenta Cloud Pub/Sub.

Jeśli powiadomienia nie zostaną potwierdzone (np. 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 dotyczące skrzynki pocztowej, zadzwoń pod numer stop. Wszystkie nowe powiadomienia powinny przestać przychodzić w ciągu kilku minut.

Ograniczenia

Maksymalna liczba powiadomień

Każdy obserwowany użytkownik Gmaila może otrzymywać maksymalnie 1 powiadomienie na sekundę. Powiadomienia powyżej tego limitu zostaną odrzucone. Zachowaj ostrożność podczas obsługi powiadomień, aby nie wywołać kolejnego powiadomienia i tym samym nie rozpocząć pętli powiadomień.

Niezawodność

Zazwyczaj wszystkie powiadomienia powinny być dostarczane niezawodnie w ciągu kilku sekund. W niektórych ekstremalnych sytuacjach mogą jednak być opóźnione lub pominięte. Zadbaj o to, aby aplikacja radziła sobie z taką sytuacją i nadal synchronizowała dane, nawet jeśli nie otrzymuje powiadomień push. Na przykład po pewnym czasie, w którym użytkownik nie otrzymywał powiadomień, można okresowo wywoływać funkcję 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.