Migracja z interfejsu Email Settings API

W tym dokumencie opisujemy kluczowe różnice między Email Settings API a Gmail API. Z tego przewodnika dowiesz się, jak przenieść aplikację do interfejsu Gmail API.

Autoryzowanie zapytań

Podobnie jak interfejs Email Settings API, 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 poszczególnych użytkowników, a nie do całej domeny. Oznacza to, że autoryzacja konta administratora domeny nie umożliwia przenoszenia poczty innych użytkowników w domenie. Zamiast tego musisz używać standardowych kont usługi z uprawnieniami w całej domenie, które znajdują się na białej liście w konsoli administracyjnej, aby wygenerować odpowiedni token uwierzytelniania.

Interfejs Email Settings API 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. Ustawienia składają się głównie z par klucz/wartość, więc ładunki są koncepcyjnie 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 bezpośrednio wdrażać protokół, używaj udostępnionych 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 nich za pomocą identyfikatora, a nie nazwy.

Zarządzanie filtrami

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

Stare ustawienie Nowe ustawienie Uwagi
od criteria.from
do criteria.to
subject 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 Dodawanie za pomocą 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 etykieta użytkownika nie istnieje, musisz ją utworzyć za pomocą 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 wyświetlanaNazwa
adres sendAsEmail
replyTo replyToAddress
makeDefault isDefault

Zarządzanie klipami internetowymi

Ustawienia klipu internetowego nie są już dostępne w interfejsie API.

Zarządzanie ustawieniami automatycznego przekazywania dalej

Aby zarządzać automatycznym przekazywaniem dalej w interfejsie Gmail API, użyj zasobu Settings.

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 przekazywania 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 POP w interfejsie Gmail API, użyj zasobu Settings.

Stare ustawienie Nowe ustawienie Uwagi
włącz accessWindow Wyłączone, gdy ustawiona jest 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
włącz włączone

Zarządzanie ustawieniami automatycznej odpowiedzi o nieobecności

Aby zarządzać automatyczną odpowiedzią z informacją o urlopie w interfejsie Gmail API, użyj zasobu Settings.

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 w interfejsie Gmail API, użyj zasobu SendAs.

Stare ustawienie Nowe ustawienie
podpis podpis

Inne zmiany:

  • Podpisami zarządza się teraz w przypadku każdego aliasu.

Zarządzanie ustawieniami języka

Aby zarządzać ustawieniami języka w interfejsie Gmail API, użyj zasobu Settings.

Stare ustawienie Nowe ustawienie
language displayLanguage

Więcej informacji znajdziesz w przewodniku po zarządzaniu 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 korzystać z dowolnej metody przekazywania dostępu (w tym delegates.create), użytkownik przekazujący dostęp musi mieć włączoną usługę Gmail. Oznacza to na przykład, że użytkownik delegujący nie może być zawieszony w Google Workspace.
    • Aliasu e-mail nie można używać jako danych wejściowych adresu e-mail przedstawiciela w przypadku żadnej z nowych metod. Użytkownik delegowany musi być określony za pomocą podstawowego adresu e-mail.
  • delegates.create
    • Za pomocą tej metody można teraz tworzyć relacje delegowania w wielu domenach należących do tej samej organizacji Google Workspace.
    • Ta metoda może być teraz używana w przypadku użytkowników, którzy muszą zmienić hasło przy następnym logowaniu.
    • Jeśli operacja się uda, ta metoda zwróci w treści odpowiedzi zasób Users.settings.delegates, a nie pustą treść odpowiedzi.
    • Jeśli użytkownik delegujący lub użytkownik delegowany jest wyłączony (np. zawieszony w Google Workspace), ta metoda zwraca błąd HTTP 4XX zamiast błędu HTTP 500.
  • delegates.delete
    • Ta metoda może być teraz używana do usuwania delegatów z dowolnym verificationStatus, a nie tylko delegatów, którzy mają wartość accepted lub expired.
  • delegates.get
    • Jest to nowa metoda, która w zależności od potrzeb może być lepsza od metody delegates.list.

Zarządzanie ustawieniami ogólnymi

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