Powiadomienia push

Omówienie

Interfejs Gmail API udostępnia powiadomienia push z serwera, które pozwalają śledzić zmiany w skrzynkach pocztowych Gmaila. Dzięki tej funkcji możesz poprawić wydajność aplikacji. Pozwala to wyeliminować dodatkowe koszty sieci i przetwarzania związane z zapytaniem o zasoby w celu sprawdzenia, czy uległy zmianie. Gdy nastąpi zmiana skrzynki pocztowej, interfejs Gmail API powiadomi Twoją aplikację serwera.

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ń na różne sposoby, w tym za pomocą webhooków i sondowania w pojedynczym punkcie końcowym subskrypcji.

Wymagania wstępne

Aby dokończyć konfigurację, spełnij wymagania w sekcji 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 (czyli pasującą do projects/myproject/topics/*, gdzie myproject jest identyfikatorem projektu wymienionym w Twoim projekcie w Google Developers Console).

Ze względu na limity Cloud Pub/Sub dotyczące liczby tematów zalecamy używanie jednego tematu do wszystkich powiadomień push Gmail API w aplikacji.

Tworzenie subskrypcji

Aby skonfigurować subskrypcję utworzonego tematu, postępuj zgodnie z przewodnikiem dla subskrybentów Cloud Pub/Sub. Skonfiguruj typ subskrypcji jako push webhooka (np. wywołanie zwrotne HTTP POST) lub pull (np. inicjowany przez Twoją aplikację). Dzięki temu 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 temacie.

Aby to zrobić, musisz przyznać uprawnienia publish do gmail-api-push@system.gserviceaccount.com. Możesz to zrobić, korzystając z interfejsu uprawnień w Konsoli programisty Cloud Pub/Sub zgodnie z instrukcjami dotyczącymi kontroli dostępu na poziomie zasobu.

Otrzymywanie powiadomień o zmianach w skrzynce pocztowej Gmail

Po zakończeniu początkowej konfiguracji Cloud Pub/Sub skonfiguruj konta Gmail, aby wysyłać powiadomienia o aktualizacjach skrzynki pocztowej.

Prośba o obejrzenie

Aby skonfigurować konta Gmail na potrzeby wysyłania powiadomień do tematu Cloud Pub/Sub, wystarczy użyć klienta Gmail API do wywołania watch w skrzynce pocztowej użytkownika Gmaila, tak jak w przypadku każdego innego wywołania Gmail API. Aby to zrobić, podaj nazwę tematu utworzonego powyżej oraz inne opcje w prośbie watch, np. labels, aby włączyć filtr. Aby na przykład 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ź

Jeśli żądanie watch się powiedzie, otrzymasz odpowiedź podobną do tej:

{
  historyId: 1234567890
  expiration: 1431990098200
}

z bieżącą skrzynką pocztową historyId użytkownika. Wszystkie zmiany wprowadzone po tym terminie historyId będą wysyłane do Twojego klienta. Jeśli chcesz przetworzyć zmiany przed historyId, zapoznaj się z przewodnikiem po synchronizacji.

Ponadto pomyślnie wykonane wywołanie watch powinno spowodować natychmiastowe wysłanie powiadomienia do tematu Cloud Pub/Sub.

Jeśli w wyniku wywołania funkcji watch wystąpi błąd, w szczegółach powinien być wyjaśniony jego powód, który zwykle wiąże się z konfiguracją tematu i subskrypcji Cloud Pub/Sub. Aby sprawdzić, czy konfiguracja jest prawidłowa, i rozwiązać problemy z tematem i subskrypcją, zapoznaj się z dokumentacją Cloud Pub/Sub.

Odnawianie zegara skrzynki pocztowej

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

Otrzymywanie powiadomień

Gdy nastąpi zmiana skrzynki pocztowej odpowiadająca Twoim watch, aplikacja otrzyma powiadomienie z opisem tej zmiany.

Jeśli masz skonfigurowaną subskrypcję push, powiadomienie webhooka wysyłane na serwer będzie zgodne z 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 znaków zakodowany w formacie base64url, który po dekodowaniu tworzy 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ć parametru history.list, aby uzyskać szczegóły zmian wprowadzonych przez użytkownika od czasu użycia przez niego ostatnio znanego parametru historyId, zgodnie z przewodnikiem po synchronizacji.

Jeśli masz skonfigurowaną subskrypcję typu „pull”, więcej informacji o odbieraniu wiadomości znajdziesz w przykładach kodu w przewodniku po subskrypcji typu „pull” w Cloud Pub/Sub.

Odpowiadanie na powiadomienia

Wszystkie powiadomienia muszą być potwierdzone. Jeśli używasz webhooka do przesyłania danych w trybie push, pomyślna odpowiedź (np. HTTP 200) potwierdzi powiadomienie.

Jeśli używasz dostawy typu pull (REST Pull, RPC Pull lub RPC StreamingPull), musisz wykonać wywołanie potwierdzenia (REST lub RPC). Więcej informacji o potwierdzaniu wiadomości w sposób asynchroniczny lub synchroniczny znajdziesz w oficjalnych bibliotekach klienta opartych na RPC. Przykłady kodu znajdziesz w przewodniku po subskrypcji 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 spróbuje ponownie wysłać powiadomienie w późniejszym terminie.

Zatrzymywanie aktualizacji skrzynki pocztowej

Aby przestać otrzymywać powiadomienia o poczcie, zadzwoń pod numer stop. Po kilku minutach nie będziesz już otrzymywać nowych powiadomień.

Ograniczenia

Maksymalna częstotliwość powiadomień

Każdy obserwowany użytkownik Gmaila ma maksymalną częstotliwość powiadomień wynoszącą 1 zdarzenie/s. Wszystkie powiadomienia o użytkownikach, które przekraczają tę częstotliwość, zostaną odrzucone. Podczas obsługi powiadomień zachowaj ostrożność, aby nie wywołać kolejnego powiadomienia i w ten sposób nie rozpocząć pętli powiadomień.

Niezawodność

Zazwyczaj wszystkie powiadomienia powinny być dostarczane w ciągu kilku sekund, ale w niektórych ekstremalnych sytuacjach mogą być opóźnione lub nie dotrzeć. Zadbaj o to, aby aplikacja nadal synchronizowała się, nawet jeśli nie otrzyma żadnych powiadomień push. Może to być na przykład okresowe wywoływanie funkcji history.list po okresie bez powiadomień dla użytkownika.

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.