Migracja z interfejsu Email Settings API

W tym dokumencie opisujemy kluczowe różnice między interfejsem Email Settings API a interfejsem Gmail API. Z tego przewodnika możesz skorzystać, aby przenieść aplikację na interfejs Gmail API.

Autoryzowanie zapytań

Podobnie jak interfejs API ustawień poczty e-mail, interfejs Gmail API używa protokołu OAuth 2.0 do autoryzowania żądań. Jedną z kluczowych różnic jest to, że uprawnienia interfejsu Gmail API są ograniczone do konkretnego użytkownika, a nie całej domeny. Oznacza to, że autoryzowanie konta administratora domeny nie pozwala na migrację poczty dla innych użytkowników w domenie. Zamiast tego musisz użyć standardowych kont usługi z uprawnieniami na poziomie domeny, które znajdują się na białej liście w konsoli administracyjnej, aby wygenerować odpowiedni token uwierzytelniający.

Interfejs API Ustawienia poczty e-mail używał zakresu:

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 Email Settings API korzysta z protokołu GDATA opartego na XML. Interfejs Gmail API używa formatu JSON. Ponieważ ustawienia składają się głównie z par klucz-wartość, ładunki są pod względem koncepcyjnym podobne w różnych wersjach.

Przykład tworzenia etykiety:

Email Settings API

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"
}

Zamiast implementować protokół bezpośrednio, użyj dostarczonych bibliotek klienta.

Zarządzanie etykietami

Aby zarządzać etykietami w interfejsie Gmail API, użyj zasobu Labels.

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 za pomocą identyfikatorów zamiast nazw.

Zarządzanie filtrami

Aby zarządzać filtrami w interfejsie Gmail API, użyj zasobu Filters.

Stare ustawienie Nowe ustawienie Uwagi
od criteria.from
to criteria.to
subject criteria.subject
hasTheWord criteria.query
doesNotHaveTheWord criteria.negatedQuery
hasAttachment criteria.hasAttachment
shouldArchive action.removeLabelIds Użyj wartości INBOX jako identyfikatora etykiety.
shouldMarkAsRead action.removeLabelIds Użyj wartości UNREAD jako identyfikatora etykiety.
shouldStar action.addLabelIds Użyj wartości STARRED jako identyfikatora etykiety.
etykieta action.addLabelIds Użyj identyfikatora etykiety, aby dodać
forwardTo action.forward
shouldTrash action.addLabelIds Użyj wartości TRASH jako identyfikatora etykiety.
neverSpam action.removeLabelIds Użyj wartości SPAM jako identyfikatora etykiety.

Inne zmiany:

  • Jeśli etykieta użytkownika nie istnieje, musisz ją utworzyć za pomocą metody labels.create.

Zarządzanie aliasami „wyślij jako”

Aby zarządzać aliasami send-as w Gmail API, użyj zasobu SendAs.

Stare ustawienie Nowe ustawienie
nazwa wyświetlanaNazwa
adres sendAsEmail
replyTo replyToAddress
makeDefault isDefault

Zarządzanie klipami internetowymi

Ustawienia klipów internetowych nie są już dostępne za pomocą interfejsu API.

Zarządzanie ustawieniami automatycznego przekazywania dalej

Aby zarządzać automatycznym przekierowywaniem w interfejsie Gmail API, użyj zasobu Settings (Ustawienia).

Stare ustawienie Nowe ustawienie Uwagi
włącz 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 przekierowujące muszą zostać utworzone i zweryfikowane przed użyciem.
  • Adresami do przekazywania dalej można zarządzać za pomocą zasobu ForwardingAddresses.

Zarządzanie ustawieniami POP

Aby zarządzać dostępem do protokołu POP w interfejsie Gmail API, użyj zasobu Settings (Ustawienia).

Stare ustawienie Nowe ustawienie Uwagi
włącz accessWindow Wyłączone, gdy ustawione na 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 do IMAP w interfejsie Gmail API, użyj zasobu Settings (Ustawienia).

Stare ustawienie Nowe ustawienie
włącz włączone

Zarządzanie ustawieniami automatycznych odpowiedzi na okres nieobecności

Aby zarządzać automatyczną odpowiedzią na nieobecność w Gmail API, użyj zasobu Ustawienia.

Stare ustawienie Nowe ustawienie
contactsOnly restrictToContacts
domainOnly restrictToDomain
włącz enableAutoReply
endDate endTime
wiadomość responseBodyHtml
responseBodyPlainText
startDate startTime
subject responseSubject

Zarządzanie ustawieniami podpisu

Aby zarządzać podpisami e-mail w interfejsie Gmail API, użyj zasobu SendAs.

Stare ustawienie Nowe ustawienie
podpis podpis

Inne zmiany:

  • Podpisami można teraz zarządzać osobno dla każdego aliasu.

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 delegowania

Aby zarządzać delegowaniem w Gmail API, użyj zasobu Delegates.

Stare ustawienie Nowe ustawienie
adres delegateEmail
status verificationStatus

Inne zmiany:

  • Ogólne
    • Aby móc korzystać z dowolnej metody delegowania (w tym delegates.create), użytkownik delegujący musi mieć włączone Gmaila. Oznacza to na przykład, że użytkownik delegujący nie może zostać zawieszony wGoogle Workspace.
    • Aliasu e-maila nie można używać jako danych wejściowych adresu e-mail przedstawiciela w przypadku żadnej z nowych metod. Użytkownik delegowany musi być identyfikowany za pomocą podstawowego adresu e-mail.
  • delegates.create
    • Teraz za pomocą tej metody możesz tworzyć relacje delegowania w wielu domenach należących do tej samej organizacji. Google Workspace
    • Tej metody można teraz używać w przypadku użytkowników, którzy muszą zmienić hasło przy następnym logowaniu.
    • Jeśli operacja się powiedzie, zwróci ona zasób Users.settings.delegates w treści odpowiedzi, a nie pustą treść odpowiedzi.
    • Jeśli jeden z delegujących lub delegowanych użytkowników jest wyłączony (np. zawieszony w Google Workspace), ta metoda zakończy się niepowodzeniem z błędem HTTP 4XX zamiast HTTP 500.
  • delegates.delete
    • Teraz można używać tej metody do usuwania delegowanych kont z dowolną wartością verificationStatus, a nie tylko tych, które mają wartość accepted lub expired.
  • delegates.get
    • Jest to nowa metoda, która może być preferowana w porównaniu z metodą delegates.list w zależności od potrzeb.

Zarządzanie ustawieniami ogólnymi

Ustawienia ogólne nie są już dostępne w interfejsie API.