Gmail-API:n yleiskatsaus

Gmail-API on RESTful API, jonka avulla voi käyttää Gmailin postilaatikoita ja lähettää sähköpostia. Useimmille verkkosovelluksille (mukaan lukien mobiilisovellukset) Gmail API onparas valinta valtuutettuun pääsyyn käyttäjän Gmail-tietoihin.

Gmail API antaa joustavan, RESTful-käytön käyttäjän postilaatikkoon, luonnollisella käyttöliittymälläThreads,Messages,Labels,Drafts,History, ja.Settings.Valitsemastasi nykyaikaisesta kielestä sovelluksesi voi käyttää API:ta lisätäGmailin ominaisuuksia, kuten:

• Lue viestejä Gmailista
• Lähetä sähköpostiviestejä
• Muokkaa viesteihin ja viestiketjuihin käytettyjä merkintöjä
• Hae tiettyjä viestejä ja viestiketjuja
• Luo suodattimia, jotka merkitsevät viestit automaattisesti, välittää tai arkistoida viestejä

Tarvitset Gmailin API:n käyttöön vain valitsemasi kielen asiakaskirjaston ja sovelluksen, joka voi tunnistautua Gmailin käyttäjäksi.

Tyypillisiä käyttötapauksia

Gmailin API:ta voidaan käyttää monissa eri sovelluksissa, kuten,tyypillisesti:

• Lukusähköpostin poiminta, indeksointi ja varmuuskopiointi
• Tarrojen hallinta (tarrojen lisääminen/poistaminen)
• Viestien automaattinen tai ohjelmallinen lähettäminen
• Sähköpostitilien migraatio muilta palveluntarjoajilta
• Vakiomuotoisten sähköpostisignatuurien asettaminen verkkotunnuksen käyttäjille

Kuinka löydän lisää?

Käytä tätä dokumentaatiota aloittaaksesi Gmail-sovelluksen rakentamisen jo tänään:

• Asiakaskirjastot ovat ladattavissa useilla eri kielillä, ja ne helpottavat API-pyyntöjen tekemistä.
• Kehittäjäoppaiden aiheet auttavat sinua ymmärtämään paremmin, miten toteutat tietyt käyttötapaukset.
• Asiointirajapintaviite antaa yksityiskohtaisia tietoja jokaisesta Gmail-API:n resurssista ja metodista.

Asiointirajapinnan yleiskatsaus

Gmail-API on verkkopalvelu: se käyttää RESTful-API:tä JSON-hyötykuorman kanssa.Tässä osiossa on yleinen yleiskatsaus API:n ominaisuuksista ja niiden käytöstä. Tarkempia tietoja API:n resursseista ja menetelmistä on GmailAPI-viitteessä.

Keskeiset resurssityypit

Gmail API tarjoaa useita resurssityyppejä:

• Viestit
• Tarrat
• Luettelot
• Luonnokset
• Historia
• Ketjut
• Asetukset

Viestit ja tarrat ovat postilaatikon perusyksiköitä. Luonnokset, historia ja säikeet sisältävät kaikki yhden tai useampia viestejä, joihin on lisätty metatietoja.

Viestit ovat muuttumattomia: niitä voidaan vain luoda ja poistaa. Mitään viestin ominaisuuksia ei voi muuttaa lukuun ottamatta tiettyyn viestiin liitettyjä merkintöjä.

Viestien ja viestiketjujen luokittelussa ja järjestämisessä käytetään ensisijaisesti merkintöjä. Merkinnöillä on monista moniin -suhde viestien ja säikeiden kanssa: yksittäiseen viestiin voi olla liitetty useita merkintöjä ja yksi merkintä voi olla liitetty useisiin viesteihin tai säikeisiin. Tarroja on myös kahta tyyppiä: system ja user. Järjestelmälaput, kuten INBOX, TRASH tai SPAM, luodaan sisäisesti, eikä niitä voi luoda, poistaa tai muuttaa. Joitakin järjestelmätunnisteita, kuten INBOX, voidaan kuitenkin liittää viesteihin ja säikeisiin tai poistaa niistä. Käyttäjä tai sovellus voi lisätä, poistaa tai muuttaa käyttäjän merkintöjä.

Drafts edustavat lähettämättömiä viestejä. Itse viestejä ei voi muuttaa sen jälkeen, kun ne on luotu, mutta luonnoksen sisältämä viesti voidaan korvata.Luonnoksen lähettäminen poistaa luonnoksen automaattisesti ja luo viestin, jolla on SENT-järjestelmälappu.

Historia on kokoelma hiljattain muutettuja viestejä kronologisessa järjestyksessä.Historia on tarkoitettu kevyeksi menetelmäksi synkronoida asiakasta, mutta se sisältää tavallisesti vain viimeisten 30 päivän aikana tapahtuneita muutoksia. Joissakin tapauksissa, esimerkiksi kun asiakas on liian vanhentunut, asiakkaan pitäisi synkronoida manuaalisesti.

Säikeet ovat viestien kokoelmia, jotka edustavat keskustelua. Samoin kuin viesteihin, säikeisiin voidaan liittää myös tarroja. Toisin kuin viestejä, säikeitä ei kuitenkaan voi luoda, ainoastaan poistaa. Viestejä voidaan kuitenkin lisätä viestiketjuun.

Asetukset säätelevät sitä, miten Gmailin ominaisuudet käyttäytyvät käyttäjälle. Asetukset ovat käytettävissä POP- ja IMAP-käytölle, sähköpostin edelleenlähetykselle, suodattimille, automaattiselle lomavastaukselle, lähetysaliasille, allekirjoituksille, delegaatioille ja kielelle.

Auth ja Gmail API

Kuten muutkin Googlen REST API:t, Gmail API käyttääOAuth 2.0:aa autentikoinnin ja valtuuttamisen käsittelyyn. Sovelluksesi määrittää yhden tai useampiacopes: merkkijonoja, jotka yksilöivät resursseja, joita sen on käytettävä. Näitä laajuuksia käytetään yhdessä tunnisteiden kanssa turvaamaan käyttäjän pääsy resursseihin.Laajuusalue edustaa tiettyä käyttöoikeutta esimerkiksi yksittäiseen resurssiin tai resurssiryhmään:

• Lue viesti Gmailista (https://www.googleapis.com/auth/gmail.readonly)
• Muuta säikeeseen tai viestiin käytettyjä merkintöjä(https://www.googleapis.com/auth/gmail.modify)
• Lähetä viesti käyttäjän puolesta(https://www.googleapis.com/auth/gmail.compose)

Vaikka voit koodata verkkopalvelun auktorisointikutsut eksplisiittisesti, sinunsoveltuvuussovellusta kannattaa yleensä yksinkertaistaa käyttämällä Google API -asiakastietokirjastoja, jotka ovat saatavilla monille ohjelmointikielille.

Lisätietoja auth:n käyttämisestä Gmailin API:n kanssa on kohdassa Sovelluksen valtuuttaminen Gmailin kanssa.

Scopes

Gmailin API tukee useita hienojakoisia valtuusalueita salliakseen vain tarvittavan tason käyttöoikeudet. Pyytämällä vaaditun vähimmäistason käyttöoikeutta käyttäjät tuntevat olonsa varmemmaksi myöntäessään pääsyn postilaatikkoonsa.

Esimerkki käyttötapauksesta

Harkitse seuraavaa käyttötapausta: tulostetaan sivu viestiketjuista parhaillaan tunnistautuneelle käyttäjälle (esimerkiksi viimeisimmät viestit -paneelissa).Tämän saavuttamiseksi sovelluksesi suorittaisi seuraavat vaiheet:

1. Tunnistautumisesi käyttäjäksi käyttäenhttps://www.googleapis.com/auth/gmail.readonly-aluetta.
2. Kutsu API-metodi.GET https://www.googleapis.com/gmail/v1/users/<userId>/threads
3. Käsittele palautettua säikeiden luetteloa sovelluksessasi.

Varsinaisen esimerkkikoodin löydät valitsemasi kielen Pikakäynnistyksestä.

Yleiset käyttökohteet

Tässä osiossa esitellään hyvin korkean tason näkemys siitä, miten joitain yleisiä käyttötapauksia voidaan toteuttaa. Tarkemmat yksityiskohdat löytyvät kehittäjän oppaista.

Gmail-viestien lähettäminen

Sähköpostit lähetetään base64url-koodattuina merkkijonoina viestin rawominaisuuden sisällä. Viestin luominen ja lähettäminen:

1. Luo sähköpostin sisältö jollakin sopivalla tavalla, joka voi riippua käyttämästäsi ohjelmointikielestä.
2. Luo base64url-koodattu merkkijonoesitys tästä sisällöstä.
3. Luo uusi viestiresurssi ja aseta sen raw-ominaisuudeksi juuri luomaasi base64url-merkkijonoon.
4. Kutsu messages.sendlähettääksesi viestin.

Vastaanotettujen sähköpostiviestien noutaminen

Sähköpostin ID:n saatuasi voit noutaa sähköpostiviestin sisällön resurssin Users.messages

menetelmää get käyttäen.

Viestiä noutaessasi voit määrittää vastauksen hyötykuorman muodon.FULL-muoto (oletus) palauttaa koko jäsennellyn viestin payload-kentässä.MINIMAL-muoto palauttaa vain metatiedot, kuten tunnisteet ja tarrat.RAW-muoto palauttaa tiedot base64url-koodattuna merkkijonona raw-ominaisuudessa.

Sähköpostin muuttumishistoria

Viestin muutokset esitetäänHistory objects:llä. Ominaisuudenstart_history_id avulla voit määrittää, mistä ajankohdasta alkaen haluat muutokset palautettavan. Jotkin muutokset voivat vaikuttaa useampaan kuin yhteen viestiin, jolloin kyseistä muutosta edustava historia sisältää useita viestejä.

Tarrojen hallinta

Säikeeseen liitetyt tarrat liitetään myös kaikkiin säikeen sisällä oleviin viesteihin.Jos tarra poistetaan, se poistetaan kaikista säikeistä ja viesteistä, joihin sitä oli liitetty. messageListVisibility-ominaisuutta käytetään sen määrittämiseen, näkyvätkö tämän etiketin sisältävät viestit viestiluettelossa. Vastaavasti ominaisuutta labelListVisibility käytetään määrittämään, näkyykö etiketti etikettiluettelossa. Voit käyttäämessages.modify– taithreads.modify-metodia muuttaaksesi viesteihin tai säikeisiin sovellettavia merkintöjä.