Przegląd interfejsu API Gmaila

Przegląd interfejsu API Gmaila to interfejs API RESTful, którego można używać do uzyskiwania dostępu do skrzynek pocztowych Gmaila i wysyłania poczty. W przypadku większości aplikacji internetowych (w tym aplikacji mobilnych) interfejs API Gmaila jest najlepszym wyborem, jeśli chodzi o autoryzowany dostęp do danych Gmaila użytkownika.

Interfejs API Gmaila zapewnia elastyczny, RESTful dostęp do skrzynki odbiorczej użytkownika, z naturalnym interfejsem doThreads,Messages,Labels,Drafts,Historyi.Settings.W wybranym przez siebie nowoczesnym języku Twoja aplikacja może korzystać z interfejsu API, aby dodać funkcje Gmaila, takie jak:

• Odczytywanie wiadomości z Gmaila
• Wysyłanie wiadomości e-mail
• Modyfikowanie etykiet stosowanych do wiadomości i wątków
• Wyszukiwanie określonych wiadomości i wątków
• Tworzenie filtrów do automatycznego nadawania etykiet, przekazywania dalej, lub archiwizowania wiadomości

Wszystko, czego potrzebujesz, aby korzystać z interfejsu API Gmaila, to biblioteka kliencka dla wybranego języka oraz aplikacja, która może uwierzytelniać się jako użytkownik Gmaila.

Typowe przypadki użycia

Pakiet Gmail API może być używany w wielu różnych aplikacjach, w tym, zazwyczaj:

• Pobieranie, indeksowanie i tworzenie kopii zapasowych poczty tylko do odczytu
• Zarządzanie etykietami (dodawanie/usuwanie etykiet)
• Automatyczne lub programowe wysyłanie wiadomości
• Migracja kont e-mail od innych dostawców
• Ustawianie standardowych podpisów e-mail dla użytkowników w domenie

Jak dowiedzieć się więcej?

Korzystaj z tej dokumentacji, aby już dziś zacząć budować aplikację Gmaila:

• Biblioteki klienckie są dostępne do pobrania w wielu językach i upraszczają wykonywanie żądań API.
• Tematy przewodników dla programistów pomagają lepiej zrozumieć sposób wdrażania poszczególnych przypadków użycia.
• Odniesienie do interfejsu API zawiera szczegółowe informacje na temat każdego zasobu i metody interfejsu API Gmaila.

Przegląd interfejsu API

Przegląd interfejsu API Gmaila jest usługą internetową: wykorzystuje interfejs API typu RESTful z ładunkiem JSON. Szczegółowe informacje na temat zasobów i metod interfejsu API można znaleźć w referencji GmailAPI.

Kluczowe typy zasobów

Interfejs API Gmaila udostępnia kilka typów zasobów:

• Wiadomości
• Labels
• Drafts
• History
• Threads
• Settings

Wiadomości i etykiety są podstawowymi jednostkami skrzynki pocztowej. Wersje robocze, historia i wątki zawierają jedną lub więcej wiadomości z dodatkowymi metadanymi.

Wiadomości są niezmienne: mogą być tylko tworzone i usuwane. Żadne właściwości wiadomości nie mogą być zmienione poza etykietami zastosowanymi do danej wiadomości.

Etykiety służą jako podstawowe środki kategoryzacji i organizacji wiadomości i wątków. Etykieta ma relację wiele do wielu z komunikatami i wątkami: pojedynczy komunikat może mieć wiele etykiet zastosowanych do niego, a pojedyncza etykieta może być zastosowana do wielu komunikatów lub wątków. Etykiety występują również w dwóch typach:system i user. Etykiety systemowe, takie jak INBOX, TRASH lub SPAM, są tworzone wewnętrznie i nie można ich tworzyć, usuwać ani modyfikować. Jednak niektóre etykiety systemowe, takie jak INBOX, mogą być stosowane do wiadomości i wątków lub z nich usuwane. Etykiety użytkownika mogą być dodawane, usuwane lub modyfikowane przez użytkownika lub aplikację.

Drafts reprezentują niewysłane wiadomości. Same wiadomości nie mogą być modyfikowane po utworzeniu, ale wiadomość zawarta w wersji roboczej może być zastąpiona.Wysłanie wersji roboczej automatycznie usuwa wersję roboczą i tworzy wiadomość z etykietą systemową SENT.

Historia jest zbiorem ostatnio zmodyfikowanych wiadomości w porządku chronologicznym.Chociaż historia jest przeznaczona jako lekka metoda synchronizacji klienta, zazwyczaj zawiera tylko zapisy zmian w ciągu ostatnich 30 dni. W niektórych przypadkach, takich jak gdy klient staje się zbyt nieaktualny, klient powinien synchronizować się ręcznie.

Wątki są kolekcjami wiadomości, które reprezentują konwersację. Podobnie jak wiadomości, wątki mogą mieć również przypisane etykiety. Jednakże, w przeciwieństwie do wiadomości, wątki nie mogą być tworzone, a jedynie usuwane. Wiadomości można jednak wstawiać do wątku.

Ustawienia kontrolują zachowanie funkcji aplikacji Gmail dla użytkownika. Ustawienia są dostępne dla dostępu POP i IMAP, przekazywania wiadomości e-mail, filtrów, autoodpowiedzi na wakacje, aliasów wysyłania, podpisów, delegatów i języka.

Autoryzacja i interfejs API Gmaila

Jak inne interfejsy API REST Google, interfejs API Gmaila używa protokołuOAuth 2.0 do obsługi uwierzytelniania i autoryzacji. Twoja aplikacja określa jeden lub więcej zakresów: ciągów znaków identyfikujących zasoby, do których musi mieć dostęp. Zakresy te są używane wraz z zestawem tokenów w celu zabezpieczenia dostępu użytkownika do zasobów.Zakres reprezentuje konkretną formę dostępu do pojedynczego zasobu lub grupy zasobów, na przykład:

• Odczytaj wiadomość z Gmaila (https://www.googleapis.com/auth/gmail.readonly)
• Zmień etykiety zastosowane do wątku lub wiadomości(https://www.googleapis.com/auth/gmail.modify)
• Wyślij wiadomość w imieniu użytkownika(https://www.googleapis.com/auth/gmail.compose)

Mimo że możesz jawnie zakodować wywołania autoryzacji usługi sieciowej, zwykle powinieneś uprościć swoją aplikację, korzystając z bibliotek klienckich Google API dostępnych dla wielu języków programowania.

Więcej informacji na temat używania autoryzacji z interfejsem API Gmaila można znaleźć w temacieAutoryzowanie aplikacji za pomocą Gmaila.

Zakresy

Interaktywny interfejs API Gmaila obsługuje wiele drobnoziarnistych zakresów autoryzacji, które umożliwiają dostęp tylko do wymaganego poziomu. Dzięki żądaniu minimalnego wymaganego poziomu dostępu użytkownicy czują się pewniej, przyznając dostęp do swojej skrzynki pocztowej.

Przykładowy przypadek użycia

Rozważmy następujący przypadek użycia: drukowanie strony wątków dla aktualnie uwierzytelnionego użytkownika (na przykład w panelu ostatnich wiadomości).Aby to osiągnąć, aplikacja wykonałaby następujące kroki:

1. Uwierzytelnij się jako użytkownik, używając zakresuhttps://www.googleapis.com/auth/gmail.readonly.
2. Wywołaj metodę API.GET https://www.googleapis.com/gmail/v1/users/<userId>/threads
3. Przetwarzaj zwróconą listę wątków w swojej aplikacji.

W celu uzyskania rzeczywistego przykładowego kodu zapoznaj się z Quickstartem dla wybranego języka.

Wspólne zastosowania

Ta sekcja zapewnia bardzo wysokopoziomowy widok tego, jak można zaimplementować niektóre typowe przypadki użycia. Więcej szczegółów można znaleźć w przewodnikach dla programistów.

Wysyłanie wiadomości Gmail

Wiadomości e-mail są wysyłane jako zakodowane łańcuchy base64url w ramach rawwłaściwości wiadomości. Aby utworzyć i wysłać wiadomość:

1. Utwórz treść wiadomości e-mail w jakiś wygodny sposób, który może zależeć od używanego języka programowania.
2. Utwórz zakodowaną w base64url reprezentację łańcuchową tej treści.
3. Utwórz nowy zasób messageresource i ustaw jego właściwość raw na łańcuch base64url, który właśnie utworzyłeś.
4. Wywołaj messages.send, aby wysłać wiadomość.

Pobieranie odebranych wiadomości e-mail

Podając identyfikator wiadomości e-mail, możesz pobrać jej zawartość za pomocą metodyget zasobu Users.messages.

Gdy pobierasz wiadomość, możesz określić format obciążenia dla odpowiedzi.Format FULL (domyślny) zwraca całą sparsowaną wiadomość w polu payload.Format MINIMAL zwraca tylko metadane, takie jak identyfikatory i etykiety.Format RAW zwraca dane jako ciąg zakodowany w base64url we właściwości raw.

Historia zmian wiadomości e-mail

Zmiany wiadomości są reprezentowane przezHistory objects. Właściwośćstart_history_id pozwala określić, od którego punktu mają być zwracane zmiany. Niektóre zmiany mogą dotyczyć więcej niż jednej wiadomości i dlatego historia reprezentująca tę zmianę będzie zawierać wiele wiadomości.

Zarządzanie etykietami

Naklejki zastosowane do wątku są również zastosowane do wszystkich wiadomości w tym wątku.Jeśli etykieta jest usuwana, jest usuwana ze wszystkich wątków i wiadomości, do których była zastosowana. Właściwość messageListVisibility jest używana do określenia, czy wiadomości z tą etykietą pojawią się na liście wiadomości. Podobnie, właściwośćlabelListVisibility jest używana do określenia, czy etykieta pojawi się na liście etykiet. Możesz użyć metodymessages.modify lubthreads.modify aby zmienić etykiety stosowane odpowiednio do wiadomości lub wątków.