W tym dokumencie opisujemy najważniejsze różnice między interfejsem Email Settings API a Gmail API. Z tego przewodnika dowiesz się, jak przenieść swoją aplikację do interfejsu Gmail API.
Autoryzowanie zapytań
Podobnie jak Email Settings API, interfejs Gmail API autoryzuje żądania za pomocą protokołu OAuth 2.0. Główna różnica polega na tym, że uprawnienia interfejsu Gmail API są ograniczone do poszczególnych użytkowników, a nie całej domeny. Oznacza to, że autoryzowanie konta administratora domeny nie pozwala na migrację poczty innych użytkowników w domenie. Zamiast tego musisz używać standardowych kont usługi z uprawnieniami w całej domenie, które zostały dodane do białej listy w konsoli administracyjnej do wygenerowania odpowiedniego tokena uwierzytelniania.
Zakres interfejsu API ustawień poczty e-mail został użyty:
https://apps-apis.google.com/a/feeds/emailsettings/2.0/
Odpowiednie zakresy w interfejsie Gmail API to:
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
Zmiany protokołu
Interfejs API do ustawień poczty e-mail korzysta z protokołu GDATA opartego na formacie XML. Interfejs Gmail API korzysta z formatu JSON. Ustawienia składają się głównie z par klucz/wartość, więc ładunki w różnych wersjach są koncepcyjnie podobne.
Przykład tworzenia etykiety:
Interfejs API ustawień poczty e-mail
POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain name}/{username}/label
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name="label" value="status updates" />
</atom:entry>
Gmail API
POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
"name": "status updates"
}
Użyj dostarczonych bibliotek klienta, zamiast bezpośrednio implementować protokół.
Zarządzanie etykietami
Etykietami możesz zarządzać w interfejsie Gmail API, korzystając z zasobu Etykiety.
Stare ustawienie | Nowe ustawienie | Uwagi |
---|---|---|
labelId | id | |
etykieta | nazwa | |
unreadCount | messagesUnread | |
widoczność | labelListVisibility | SHOW to teraz labelShow HIDE to teraz labelHide |
Inne zmiany:
- Podczas aktualizowania lub usuwania etykiet interfejs Gmail API odwołuje się do etykiet według identyfikatora, a nie nazwy.
Zarządzanie filtrami
Aby zarządzać filtrami w interfejsie Gmail API, użyj zasobu Filtry.
Stare ustawienie | Nowe ustawienie | Uwagi |
---|---|---|
od | criteria.from | |
criteria.to | ||
podmiot | criteria.subject | |
hasTheWord | criteria.query | |
doesNotHaveTheWord | criteria.negatedQuery | |
hasAttachment | criteria.hasAttachment | |
shouldArchive | action.removeLabelIds | Użyj INBOX jako identyfikatora etykiety |
shouldMarkAsRead | action.removeLabelIds | Użyj UNREAD jako identyfikatora etykiety |
shouldStar | action.addLabelIds | Użyj STARRED jako identyfikatora etykiety |
etykieta | action.addLabelIds | Aby dodać, użyj identyfikatora etykiety |
forwardTo | action.forward | |
shouldTrash | action.addLabelIds | Użyj TRASH jako identyfikatora etykiety |
neverSpam | action.removeLabelIds | Użyj SPAM jako identyfikatora etykiety |
Inne zmiany:
- Jeśli nie ma jeszcze etykiety użytkownika, musisz ją utworzyć bezpośrednio przy użyciu metody labels.create.
Zarządzanie aliasami „wyślij jako”
Aby zarządzać aliasami „wyślij jako” w interfejsie Gmail API, użyj zasobu SendAs.
Stare ustawienie | Nowe ustawienie |
---|---|
nazwa | displayName |
adres | sendAsEmail |
replyTo | replyToAddress |
makeDefault | isDefault |
Zarządzanie wycinkami z internetu
Ustawienia funkcji Web Clip nie są już dostępne przez interfejs API.
Zarządzanie ustawieniami automatycznego przekazywania dalej
Aby zarządzać automatycznym przekazywaniem dalej w interfejsie Gmail API, użyj zasobu Settings (Ustawienia).
Stare ustawienie | Nowe ustawienie | Uwagi |
---|---|---|
enable | włączone | |
forwardTo | emailAddress | |
działanie | dyspozycja | KEEP to teraz leaveInInbox ARCHIVE to teraz archive DELETE to teraz trash MARK_READ to teraz markRead |
Inne zmiany:
- Adresy do przekazywania dalej należy utworzyć i zweryfikować przed użyciem
- Adresami przekierowania można zarządzać za pomocą zasobu ForwardingAddresses.
Zarządzanie ustawieniami POP
Aby zarządzać dostępem POP w interfejsie Gmail API, użyj zasobu Settings.
Stare ustawienie | Nowe ustawienie | Uwagi |
---|---|---|
enable | accessWindow | Wyłączona, gdy ma wartość disabled |
enableFor | accessWindow | ALL_MAIL to teraz allMail MAIL_FROM_NOW_ON to teraz fromNowOn |
działanie | dyspozycja | KEEP to teraz leaveInInbox ARCHIVE to teraz archive DELETE to teraz trash MARK_READ to teraz markRead |
Zarządzanie ustawieniami IMAP
Aby zarządzać dostępem IMAP w interfejsie Gmail API, użyj zasobu Settings.
Stare ustawienie | Nowe ustawienie |
---|---|
enable | włączone |
Zarządzanie ustawieniami automatycznej odpowiedzi na czas nieobecności
Aby zarządzać automatyczną odpowiedzią o nieobecności w interfejsie Gmail API, użyj zasobu Settings.
Stare ustawienie | Nowe ustawienie |
---|---|
contactsOnly | restrictToContacts |
domainOnly | restrictToDomain |
enable | enableAutoReply |
endDate | endTime |
wiadomość | responseBodyHTML responseBodyplainText |
startDate | startTime |
podmiot | responseSubject |
Zarządzanie ustawieniami podpisu
Aby zarządzać podpisami e-maili w interfejsie Gmail API, użyj zasobu SendAs.
Stare ustawienie | Nowe ustawienie |
---|---|
podpis | podpis |
Inne zmiany:
- Teraz podpisami zarządza się dla poszczególnych aliasów.
Zarządzanie ustawieniami języka
Aby zarządzać ustawieniami języka w interfejsie Gmail API, użyj zasobu Settings (Ustawienia).
Stare ustawienie | Nowe ustawienie |
---|---|
language, | displayLanguage |
Więcej informacji znajdziesz w przewodniku Zarządzanie ustawieniami języka.
Zarządzanie ustawieniami przekazywania dostępu
Aby zarządzać przekazywaniem dostępu w interfejsie Gmail API, użyj zasobu Delegates.
Stare ustawienie | Nowe ustawienie |
---|---|
adres | delegateEmail |
status | verificationStatus |
Inne zmiany:
- Ogólne
- Aby można było korzystać z metod przekazywania dostępu (w tym delegates.create), użytkownik przekazujący dostęp musi mieć dostęp do Gmaila. Oznacza to na przykład, że użytkownika przekazującego nie można zawiesić wGoogle Workspace.
- Aliasu e-mail nie można używać jako adresu e-mail osoby z przekazanym dostępem w żadnej z nowych metod. Użytkownik, któremu przekazano dostęp, musi być odsyłany za pomocą jego podstawowego adresu e-mail.
- delegates.create
- Tej metody można teraz używać do tworzenia relacji z przekazywaniem dostępu między wieloma domenami należącymi do tej samej Google Workspace organizacji.
- Tej metody można teraz używać w przypadku użytkowników, którzy wymagają zmiany hasła po następnym zalogowaniu.
- Jeśli operacja się uda, metoda zwróci Users.settings.delegates zasób w treści odpowiedzi, a nie pustą treść odpowiedzi.
- Jeśli jeden z użytkowników przekazujących dostęp lub użytkownik z przekazanym dostępem jest wyłączony (np. zawieszony w Google Workspace), ta metoda zakończy się błędem HTTP 4XX, a nie błędem HTTP 500.
- delegates.delete
- Tej metody można teraz używać do usuwania przedstawicieli z dowolnymi elementami verificationStatus, a nie tylko przedstawicieli o wartości
accepted
lubexpired
.
- Tej metody można teraz używać do usuwania przedstawicieli z dowolnymi elementami verificationStatus, a nie tylko przedstawicieli o wartości
- delegates.get
- Jest to nowa metoda, która w zależności od potrzeb może być preferowana zamiast metody delegates.list.
Zarządzanie ustawieniami ogólnymi
Ustawienia ogólne nie są już dostępne w interfejsie API.