Konfigurowanie powiadomień push w interfejsie Gmail API

Z tego dokumentu dowiesz się, jak zarządzać powiadomieniami push w Gmail API.

Gmail API udostępnia serwerowe powiadomienia push, które pozwalają śledzić zmiany w skrzynkach pocztowych Gmaila. Użyj tej funkcji, aby poprawić wydajność aplikacji. Eliminuje ona dodatkowe koszty sieciowe i obliczeniowe związane z sondowaniem zasobów w celu sprawdzenia, czy uległy zmianie. Gdy skrzynka pocztowa ulegnie zmianie, Gmail API powiadamia o tym aplikację serwera backendowego.

Wstępna konfiguracja Cloud Pub/Sub

Gmail API używa 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, na jednym punkcie końcowym subskrypcji.

Wymagania wstępne

Aby dokończyć konfigurację, spełnij wymagania wstępne 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 Gmail API ma wysyłać powiadomienia. Nazwa tematu może być dowolna w ramach projektu (np. pasująca do projects/myproject/topics/*, gdzie myproject to identyfikator projektu wymieniony w konsoli Google Cloud).

Tworzenie subskrypcji

Aby skonfigurować subskrypcję utworzonego tematu, postępuj zgodnie z instrukcjami w przewodniku po typach subskrypcji Cloud Pub/Sub . Skonfiguruj typ subskrypcji jako push webhook (czyli wywołanie zwrotne HTTP POST) lub pull (czyli inicjowane przez 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ć, przyznaj uprawnienia publish do gmail-api-push@system.gserviceaccount.com. Możesz to zrobić za pomocą 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 organizacji może uniemożliwić przyznanie uprawnień do publikowania. Aby rozwiązać ten problem, możesz skonfigurować wyjątek dla tego konta usługi.

Pobieranie aktualizacji skrzynki pocztowej Gmaila

Po zakończeniu wstępnej konfiguracji Cloud Pub/Sub skonfiguruj konta Gmail, aby wysyłały powiadomienia o aktualizacjach skrzynki pocztowej.

Żądanie watch

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 Gmaila. Działa to podobnie jak w przypadku innych wywołań Gmail API. W żądaniu watch podaj utworzoną nazwę tematu i inne opcje, np. labels do filtrowania. Aby otrzymywać powiadomienia o każdej zmianie w skrzynce odbiorczej, użyj na przykład tego żądania:

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ź watch

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

{ historyId: 1234567890 expiration: 1431990098200 }

Odpowiedź zawiera bieżący historyId skrzynki pocztowej użytkownika. Klient będzie otrzymywać powiadomienia o wszystkich zmianach po tym historyId. Jeśli musisz przetworzyć zmiany przed tym historyId, zapoznaj się z artykułem Synchronizowanie klientów z 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śnić przyczynę 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 tematem i subskrypcją, zapoznaj się z dokumentacją Cloud Pub/Sub.

Odnawianie watch skrzynki pocztowej

Musisz wywołać watch co najmniej raz na 7 dni, w przeciwnym razie przestaniesz otrzymywać aktualizacje dla użytkownika. Zalecamy wywoływanie watch raz dziennie. Odpowiedź metody watch zawiera też pole expiration ze znacznikiem czasu wygaśnięcia watch.

Otrzymywanie powiadomień

Gdy nastąpi aktualizacja skrzynki pocztowej zgodna z Twoim watch, aplikacja otrzyma komunikat z powiadomieniem opisujący zmianę.

Jeśli skonfigurowano subskrypcję push, powiadomienie webhook do serwera jest zgodne z 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 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 dla użytkownika od czasu ich ostatniego znanego historyId, zgodnie z opisem w artykule Synchronizowanie klientów z Gmail API.

Aby na przykład zidentyfikować zmiany, które zaszły między początkowym watch żądaniem a otrzymaniem komunikatu z powiadomieniem udostępnionym w poprzednim przykładzie, użyj history.list metody. Przekaż 1234567890 jako startHistoryId do history.list. Następnie możesz zapisać 9876543210 jako ostatni znany historyId do wykorzystania w przyszłości.

Jeśli zamiast tego skonfigurowano subskrypcję pull, więcej informacji o odbieraniu wiadomości znajdziesz w przykładach kodu w przewodniku po subskrypcjach pull w Cloud Pub/Sub.

Odpowiadanie na powiadomienia

Wszystkie powiadomienia muszą zostać potwierdzone. Jeśli używasz dostarczania push webhook push delivery, potwierdzeniem powiadomienia jest pomyślna odpowiedź (np. HTTP 200).

Jeśli używasz dostarczania pull (REST Pull, RPC Pull, lub RPC StreamingPull), musisz wysłać wywołanie potwierdzenia (REST lub RPC). Więcej informacji o potwierdzaniu wiadomości asynchronicznie lub synchronicznie za pomocą oficjalnych bibliotek klienta opartych na RPC znajdziesz w przykładach kodu w przewodniku po subskrypcjach pull subscriptions w Cloud Pub/Sub.

Jeśli nie potwierdzisz powiadomień (np. jeśli wywołanie zwrotne webhook 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ć przychodzić w ciągu kilku minut.

Ograniczenia

Oto ograniczenia związane z pracą z powiadomieniami push z serwera:

Maksymalna liczba powiadomień

Każdy obserwowany użytkownik Gmaila może otrzymywać maksymalnie 1 powiadomienie na sekundę. Wszystkie powiadomienia użytkownika przekraczające ten limit są odrzucane. Podczas obsługi powiadomień uważaj, aby nie wywołać kolejnego powiadomienia, co może spowodować pętlę powiadomień.

Niezawodność

Zwykle wszystkie powiadomienia są dostarczane niezawodnie w ciągu kilku sekund, ale w niektórych ekstremalnych sytuacjach mogą być opóźnione lub odrzucone. Zadbaj o to, aby aplikacja nadal się synchronizowała, nawet jeśli nie otrzymuje wiadomości push. Na przykład po pewnym czasie, gdy nie otrzymasz powiadomień od użytkownika, możesz okresowo wywoływać history.list metodę.

Ograniczenia Cloud Pub/Sub

Cloud Pub/Sub API ma też własne ograniczenia, które są szczegółowo opisane w dokumentacji dotyczącej cen i limitów.