Migracja z interfejsu Email Settings API

Ten dokument pomoże Ci przenieść aplikację z wycofanego interfejsu Email Settings API na interfejs Gmail API.

Autoryzowanie żądań

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 migracji poczty innych użytkowników w domenie. Zamiast tego musisz używać standardowych kont usługi z uprawnieniami w całej domenie, które są dodawane do listy dozwolonych w konsoli administracyjnej Google, aby generować 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 implementować protokół, używaj udostępnionych bibliotek klienta.

Zarządzaj 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ądzaj filtrami

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

Stare ustawienie Nowe ustawienie Uwagi
od criteria.from
do criteria.to
temat, 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 dodawanie etykiety użytkownika jeszcze nie istnieje, musi zostać wyraźnie utworzone 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 settings.sendAs.

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

Zarządzanie klipami internetowymi

Ustawienia wycinka internetowego nie są dostępne w interfejsie Gmail API.

Zarządzanie automatycznym przekazywaniem dalej

Aby zarządzać automatycznym przekazywaniem 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 do przekazywania dalej muszą zostać utworzone i zweryfikowane przed użyciem.
  • Adresami przekazywania można zarządzać za pomocą zasobu settings.forwardingAddresses.

Zarządzanie ustawieniami POP

Aby zarządzać dostępem do protokołu 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ą o nieobecności 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
temat, responseSubject

Zarządzanie ustawieniami podpisu

Aby zarządzać podpisami e-maili w interfejsie Gmail API, użyj zasobu settings.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 artykule Zarządzanie ustawieniami języka.

Zarządzaj ustawieniami przekazywania

Aby zarządzać przekazywaniem dostępu w interfejsie Gmail API, użyj zasobu settings.delegates.

Stare ustawienie Nowe ustawienie
adres delegateEmail
status verificationStatus

Inne zmiany:

  • Ogólne
    • Aby korzystać z dowolnej metody przekazywania dostępu (w tym settings.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 adresu e-mail przedstawiciela w przypadku żadnej z nowych metod. Użytkownik, któremu przekazano uprawnienia, musi być określony za pomocą podstawowego adresu e-mail.
  • settings.delegates.create
    • Ta metoda może być teraz używana do tworzenia relacji przedstawicielstwa 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, metoda zwróci w treści odpowiedzi zasób settings.delegates zamiast pustej treści odpowiedzi.
    • Jeśli delegujący lub delegowany użytkownik jest wyłączony (np. zawieszony w Google Workspace), ta metoda zwraca błąd HTTP 4XX zamiast błędu HTTP 500.
  • settings.delegates.delete
    • Ta metoda może być teraz używana do usuwania przedstawicieli z dowolnym uprawnieniem VerificationStatus, a nie tylko tych, którzy mają uprawnienia accepted lub expired.
  • settings.delegates.get

Zarządzanie ogólnymi ustawieniami

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