Google APIs -rajapintakoodailut esimerkkien kanssa - Oskari Järvelin

Artikkelia ja esimerkkejä on uudistettu julkaisun jälkeen paremmiksi 10.4.

Lyhyt taustoitus

Asiakkaallani on sivuillaan yhteydenottolomake, jolla asiakkaat pyytävät tarjousta asiakkaani myymistä tuotteista. Asiakas on joutunut erikseen siirtämään tiedot tarjoukseen, laskemaan tarjoushinnan Google Spreadsheetsillä ja lähettämään tarjouksen PDF:nä sähköpostitse.

Toiminnan kasvaessa rajusti syntyi tarve minimoida tarjousten lähetttämiseen vaadittava työaika ja manuaalinen työ automatisoimalla tarjousten luominen mahdollisimman pitkälle.

Tässä tapauksessa avuksi rientää Google APIs eli Googlen rajapinnat, joilla saa kaksi verkkopalvelua juttelemaan suoraan esimerkiksi PHP:llä. Tässä tapauksessa Contact Form 7:llä lähetetyt tiedot pitäisi saada talteen suoraan asiakkaan Driveen.

Googlen rajapinnat ovat ovat kohtuullisesti dokumentoitu, mutta esimerkkejä ja ohjeita löytyy hyvin vähän internetin syövereistä. Tähän haluan tehdä nyt muutosta omalta osaltani jo oppimieni asioiden kohdalta.

Luvassa on esimerkit ainakin…

  • Kuinka kerätä Contact Form 7:llä lähetetyt arvot
  • Kuinka initoida yhteys Googlen rajapintoihin
  • Kuinka luoda uusi kansio
  • Kuinka luoda uusi Spreadsheet
  • Kuinka lisätä käyttöoikeuksia kansioon tai tiedostoon
  • Kuinka siirtää tiedosto kansioon
  • Kuinka nimetä Spreadsheet uudelleen
  • Kuinka kopioida Sheet Spreadsheetistä toiseen
  • Kuinka selvittää Spreadsheetin kaikkien sheetien ID:t
  • Kuinka nimetä Sheet uudelleen
  • Kuinka poistaa Sheet
  • Kuinka kirjoittaa dataa haluttuun Spreadsheetiin
  • Kuinka lukea dataa halutusta Spreadsheetistä

Lomake oli tässä tapauksessa toteutettu Contact Form 7:lla, joka tarjoaa kiitettävästi valmiita koukkuja saadun datan käsittelyyn. Alla tekemäni lyhyt funtio, jolla saa kerättyä halutut kentät onnistuneen lomakkeen lähettämisen jälkeen.

Google APIs

Yhteys Googlen rajapintoihin alustetaan luomalla uusi Client. PHP Quickstart löytyy täältä. Lataa Client Library, luo Service Account ja aktivoi Sheets API sekä Drive API. Lataa Service Accountin kirjautumistiedot ja nimeä ne uudelleen creds.json -nimellä.

Alla oleva funktio hakee Client Libraryn ja Service Accountin tiedoilla uuden asiakkuuden, ja lisää sille oikeudet Spreadsheetseihin, Driveen, ja Driven tiedostoihin.

Kaikki oikeudet eli Scopet löydät täältä. Kukin toiminto listaa dokumentaatiossaan mitkä scopet se vaatii toimiakseen.

Uuden kansion luominen

Funktio hakee Clientin, jolla alustaa yhteyden Googlen palveluun. Uuden kansion luominen palauttaa Folder-instanssin, josta myöhemmin tarvitsemme vain kansion ID:n. ID:n palautamme funktiosta viimeisenä.

Uuden Spreadsheetin luominen

Funktio hakee Clientin, jolla alustaa yhteyden Sheets-serviceen. Uuden Spreadsheetin luominen palauttaa koko Spreadsheet-instanssin, josta tulevaa käyttöä varten tarvitsemme vain ID:n. Uuden spreadsheetin ID:n palautamme funktiosta lopuksi.

Jos tiedoston luotuasi käyt kurkkaamassa Driveesi, huomaat pian saman ongelman kuin minä. Luodessasi Service Accountin loit myös uuden Drive-tilin, johon uuden tiedostot luodaan. Päästäksesi omasta Drivestäsi käsittelemään luomaasi tiedostoa, tulee sinun lisätä itsellesi oikeudet tiedostoon.

Käyttöoikeuksien lisääminen

Tämä funktio tarvitsee ID:n tiedostoon tai kansioon, johon oikeuksia ollaan myöntämässä.  Roolin vaihtoehdot ovat organizer/owner, writer, commenter tai reader, mutta owner on jo varattu Service Accountille.

Tiedoston siirtäminen kansioon

Tässä esimerkissä siirretään spreadsheet kansioon, joten funtion vastaanottamien muuttujien nimet ovat spreadsheetId ja folderId. Huomaa, että tämä funtio poistaa tiedoston aiemmasta kansiostaan!

Spreadsheetin nimeäminen uudelleen

Funktio vastaanottaa kaksi argumenttiä: uuden nimen ja spreadsheetin ID:n. Uudelleennimeämisen olen toteuttanut batchUpdatena, jolla pystyisi ajamaan useita requesteja kerralla samaan tiedostoon.

Sheetin kopioiminen spreadsheetistä toiseen

Funktio vastaanottaa kolme argumenttiä:

  • originalSpreadsheet on alkuperäisen spreadsheetin ID
  • sheetId on alkuperäisen sheetin ID alkuperäisessä spreadsheetissä
  • spreadsheetId on kohdespreadsheetin ID

Sheetin ID:n selvittäminen

Jos spreadsheetin sisällä halutaan poistaa tai nimetä uudelleen yksittäinen sheet, tulee ensin selvittää asiakirjan sheet:sien ID:t. Funktio hakee saamansa ID:n kaikkien sheet:sien ID:t ja palauttaa ne arrayna.

Yksittäisen Sheetin uudelleennimeäminen

Funktio vastaanottaa sekä spreadsheetin että sheetin ID:t, jotka halutaan nimetä uudelleen.

Yksittäisen Sheetin poistaminen

Funktio vastaanottaa sekä spreadsheetin että sheetin ID:t, joka halutaan poistaa.

Datan kirjoittaminen spreadsheetiin

Datan kirjoittamiseen tein funktion, joka kirjoittaa 2-ulotteisesta arraysta jokaisen parin ensimmäisen arvon kertomaan sijaintiin toisen arvon kertoman datan.

Tämä lähestymistapa on mielestäni monessa kohtaa pienillä tietomäärillä helpompi ja selkeämpi tapa. Tämä tapa on kuitenkin tietuemäärien kasvaessa ehdottomasti huono ja todella hidas tapa toimia! ValueRange voi ottaa vastaan myös kerralla useita arvoja ja sijainteja, jotka se voi siirtää kerralla. Pienillä datamäärillä nopeuseroa kuitenkaan ei synny.

Datan lukeminen spreadsheetistä

Funktio vastaanottaa muuttujina spreadsheetin ID:n ja alueen solut Sheets-syntaksina, jonka arvot palautetaan arrayna.