Web Service API JSON Dengan Web Apps Google Apps Script

Anda bisa memanfaatkan Web Apps dari Google Apps Script untuk membuat sebuah web service API JSON online dan realtime.

WEB APPS

Saat Apps Script di-deployment ditawarkan beberapa opsi platform di antaranya Web Apps dan API Executable:

Dalam eksperimen kali ini kita tidak akan menjadikannya sebagai API Executable melainkan memanfaatkan Web Apps dari Apps Script untuk menjadi sebuah layanan web service API JSON.

Alasannya API Executable hanya difokuskan melayani transaksi API yang kaku, sedangkan Web Apps memungkinkan Apps Script menjadi sebuah aplikasi interaktif yang bisa pula melayani transaksi API.

Web Apps bisa diilustrasikan setelah anda melayani permintaan suatu data, dalam waktu yang sama anda pun dapat mengirimkan file video atau survei balik kepada user SiLiKiDi

MENERIMA REQUEST DARI WEBSITE LAIN

Pintu Gerbang Komunikasi Dengan Web Apps

Sederhananya saat suatu website menyapa Web Apps anda, bisa dikatakan sebagai sebuah Request dari website tersebut untuk meminta data tertentu, info web apps, atau sekadar uji koneksi.

Tentunya website luar harus tahu ke alamat mana ditujukan request tersebut. Alamat ini ada setiap kali anda men-deploy Apps Script akan dibangkitkan sebuah URL Web Apps tersebut:

https://script.google.com/macros/s/.../exec

URL Web Apps itulah yang menjadi gerbang komunikasi menerima request atau mengirim balik respon.

Perlu anda ketahui bahwa setiap kali deployment maka URL Web Apps akan ikut berubah juga sehingga pastikan benar-benar solid Web Apps anda sebelum didistribusikan pada user SiLiKiDi

Selengkapnya tentang deployment Apps Script bisa anda simak pada artikel Telegram Bot Dengan Google Apps Script - The First Encounter SiLiKiDi

Script Fungsi Penerima Request

Setelah suatu request masuk melalui gerbang URL Web Apps, langkah selanjutnya mengolah paket request tersebut. Apps Script menyediakan dua fungsi:

doGet( e ) khusus request yang dikirimkan melalui protokol HTTP GET di mana nilai e adalah konten dari request yang dikirimkan user.
doPost( e ) khusus request yang dikirimkan melalui protokol HTTP POST di mana nilai e adalah konten dari request yang dikirimkan user.

Contoh script dari keduanya bisa dilihat berikut ini:


/*** Khusus Jalur GET ***/
function doGet( e ) {
  let content = JSON.parse( e.parameter );
  Logger.log( content );
}

/*** Khusus Jalur POST ***/
function doPost( e ) {
  let content = JSON.parse( e.postData.contents );
  Logger.log( content );
}

/*** NOTASI ES6 ***/
const doGet = ( e = {} ) => {
  const { parameter } = e;
  Logger.log( JSON.parse( parameter ) );
};

const doPost = ( e = {} ) => {
  const { parameter, postData: { contents, type } = {} } = e;
  const data = JSON.parse( contents );
  Logger.log( data );
};

Mengirim Respon Ke Website Lain

Lalu lewat mana Web Apps mengirim respon balik terhadap request yang datang? Tentunya masih menggunakan gerbang yang sama melalui URL Web Apps tersebut.

Bagaimana caranya Web Apps mengirim respon balik tersebut? Apps Script banyak menawarkan alternatif cara merespon request tersebut sebagian di antaranya:

Mengirim paket respon ke URL website yang bersangkutan. Cara ini menggunakan metode UrlFetchApp.fetch() dengan syarat anda harus mencatat URL dari website yang bersangkutan.
Tanpa pengiriman melainkan membuat sebuah output JSON, HTML, XML, Plain Text, dll untuk dibaca oleh website yang bersangkutan. Cara ini menggunakan Content Service dengan syarat website yang bersangkutan yang mengambilnya bukan menunggu kiriman.

Contoh script dari keduanya bisa dilihat berikut ini:


/***** KIRIMKAN JSON *****/
let clientRespon = {
    method: "post",
    contentType: "application/json",
    payload: {
      data: JSON.stringify( dataJSON )
    }
};
UrlFetchApp.fetch( clientURL, clientRespon );


/***** TAMPILKAN JSON *****/
return ContentService.createTextOutput( JSON.stringify( dataJSON ) ).setMimeType( ContentService.MimeType.JSON );

UrlFetchApp.fetch() bersifat hybrid bisa berperan untuk mengirim request atau respon balik ke website lain SiLiKiDi

RESPON BALIK DALAM FORMAT JSON

JSON atau JavaScript Object Notation adalah format pertukaran data lintas sistem yang paling populer dan hampir semua sistem atau platform apapun sudah menjadikan JSON sebagai standar format output sehingga dalam eksperimen ini akan difokuskan menghasilkan format keluaran JSON.

Notasi struktur JSON dapat dipelajari selengkapnya di json.org dengan ciri khas di antaranya:

Dibungkus dengan tanda brace atau kurung kurawal {...}
Nama judul field atau key diakhiri colon atau titik dua :
Nilai ditulis berada setelah field/key dan bila terdiri dari set nilai dipisahkan dengan tanda comma ,
Nilai yang diberi tanda double quote "..." berarti bentuknya string, selain itu berbentuk numerik, object, array, boolean.
Field atau key yang nilainya bercabang biasanya berisi set nilai berbentuk array dengan tanda bracket [...], object dengan tanda brace {...}, atau array yang mengandung kumpulan object [{...},{...}].


{
  "ok": true,
  "result": {
    "date": 1633997773,
    "client": {
      "username": "johndoe",
      "first_name": "JOHN",
      "last_name": "DOE"
    },
    "items": [
      { "id": 2038723721 },
      {
        "brand": "Sapatu",
        "price": "Rp 270.000"
      },
      null
    ]
  }
}

Saat JSON dikirimkan melalui protokol HTTP berbasis web, semua elemen dalam JSON sekalipun itu object, array, boolean akan diperlakukan sebagai string SiLiKiDi

Sehingga dapat dimaklumi seringkali dilibatkan konverter JSON.stringify() untuk memastikan JSON berbentuk string agar bisa dikirimkan melalui web.

Bila JSON bersifat statis bisa dideklarasikan langsung di dalam script seperti tampak berikut:


/***** CONTOH KONVERSI JSON DARI BENTUK STRING *****/
const stringJSON = '{ "oke": true, "result": { "date": 1633997773, "client": { "username": "johndoe", "firstname": "John" }, "items": [ { "id": 2038723721 }, { "brand": "Sapatu\'koe" } ] } }';
const dataJSON = JSON.parse( stringJSON );
const userName = dataJSON.result.client.username;
const firstName = dataJSON.result.client.firstname;
const idItems = dataJSON.result.items[0].id;
const brandItems = dataJSON.result.items[1].brand;

/***** CONTOH DEKLARASI STATIS DATA JSON *****/
const dataJSON = {
   "ok": true,
   "result": {
      "date": 1633997773,
      "client": {
         "username": "johndoe",
         "first_name": "JOHN",
         "last_name": "DOE"
      },
      "items": [
        { "id": 2038723721 },
        {
           "brand": "Sapatu",
           "price": "Rp 270.000"
        },
        null
      ]
   }
}

/***** CONTOH DEKLARASI STATIS LAINNYA *****/
let dataJSON = {}; //object induk
dataJSON[ "ok" ] = true;
dataJSON[ "brand" ] = "Sapatu";
let result = {}; //object sub induk
result[ "date" ] = 1633997773;
let items = []; //array sub induk dari sub induk object result
let itemsObject = {}; //object sub induk dari sub induk array items
itemsObject[ "id" ] = 2038723721;
items[0].push( itemsObject );
result[ "items" ] = items;
dataJSON[ "result" ] = result;

Bila JSON bersifat dinamis biasanya akan melibatkan iterasi for loop.

Implementasinya di dalam script seperti tampak berikut:


/***** CONTOH DEKLARASI DATA JSON *****/
let dataJSON = {
   "ok": true,
   "result": {
      "date": 1633997773,
      "client": {
         "username": "johndoe",
         "first_name": "JOHN",
         "last_name": "DOE"
      },
      "items": [
        {
           "id": 2038723721
        },
        {
           "brand": "Sapatu",
           "price": "Rp 270.000"
        },
        null
      ]
   }
}


/***** KIRIMKAN JSON *****/
let clientRespon = {
    method: "post",
    contentType: "application/json",
    payload: {
      data: JSON.stringify( dataJSON )
    }
};
UrlFetchApp.fetch( clientURL, clientRespon );


/***** TAMPILKAN JSON *****/
return ContentService.createTextOutput( JSON.stringify( dataJSON ) ).setMimeType( ContentService.MimeType.JSON );

WEB SERVICE API JSON

Web Service berarti sebuah proses lengkap mulai dari menerima request dengan doGet() atau doPost() dan mengirim respon balik dengan UrlFetchApp.fetch() atau Content Service.

Dalam eksperimen kali ini akan kita batasi menerima request melalui jalur doGet() dan meresponnya dengan membuat output JSON menggunakan Content Service. Jalur dan cara lainnya bisa anda coba rakit sendiri sebagai bahan latihan.

#1 Menyiapkan Fungsi Penerima Request

Cukup dengan membuat satu fungsi penerima request doGet() berikut ini kita akan mencoba meresponnya dengan menampilkan hasil dalam bentuk JSON statis:

#2 Deploy Untuk Mendapatkan URL Web Apps

Silahkan deploy apps script tersebut menjadi Web Apps lalu salin URL Web Apps yang telah di-generate tersebut.

#3 Uji URL Web Apps di Browser

Tempelkan URL Web Apps pada browser [disarankan Firefox] untuk melihat hasil respon dari web service Web Apps anda. Jika tampil seperti di bawah ini berarti anda telah berhasil membangun sebuah web service sederhana:

#4 Uji URL Web Apps di Postman

Akan lebih bagus lagi bila anda menguji URL Web Apps tersebut di Postman yang lebih banyak menampilkan informasi hasil responnya seperti tampak berikut:

Sampai sini anda bisa disebut berhasil membuat sebuah Web Service Minimalis dengan memanfaatkan Web Apps Google Apps Script SiLiKiDi

FINAL SCRIPT

Final Script dari eksperimen ini dapat anda unduh di repository.

EKSPERIMEN WEB SERVICE LANJUTAN

Eksperimen selanjutnya akan mulai mencoba web service yang lebih mahir lagi dengan menangani parameter-parameter tambahan dari user yang akan dikaitkan dengan data-data dari Google Sheets.

Dapatkan skrip semua materi di repository

Dukung donasi agar tutorial ini tetap operasional:
SiLiKiDi

TELEGRAM BOT SCRIPT

Cari Blog Ini