Migracja z interfejsu Email Settings API

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 lub expired.
  • 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.