Upload
bruce-mcpherson
View
5.240
Download
1
Tags:
Embed Size (px)
DESCRIPTION
Here's details on an API that will allow you to maintain Google Apps Script noSQL database directly from Excel
Citation preview
VBA API for
ScriptDBGoogle Apps ScriptDB from Excel
what is this API for?
• Allow maintenance and query Google Apps
Script ScriptDB directly from VBA
• Share data in real time between Google
Docs and Office
• a free noSQL database for Excel
• Migration or coexistence path for GAS and
VBA
COMPONENTS
VBA
API
Your
code Your GAS
webapp
Handler (s)
Your
codeYour
VBA
code
Your
ScriptDB
dispatcher
GAS
Library
API
Your
codeYour
codeMultiple
ScriptDB
PC
Registry
oauth2 /
rest
encrypted
oauth2
credentials
simple
noSql
authentication with oAuth2
One off
credential
storage
Registry
● Get oAuth2 credentials from Google Cloud Console
● Run the below to encrypt them on your PC, one time
only.
getGoogled("drive", , "xxxxx.apps.googleusercontent.com", "xxxxx").tearDown
● Credentials are shared between all VBA APIs
needing oAuth2 on Excel Liberation
● Thereafter, oauth2 dance is automatically handled in
all API requests
user/google
scope
optional access control
User and
Access
type
credentials
Registry
● You can also optionally add a couple more keys,
which are passed with every request in its header
● Equivalent to the RESTAPIkey and ApplicationID in
parse.com
● Your Gas Webapp handler can inspect these to
signal the GAS API the type of access allowed
● Only needs to be stored one time
scriptdbCom.init("anything",”some entry id” ,”some scope id”,
"your app id", _
"your restapikey", , , True, _
"Gas web app url endpoint").tearDown
your entry/
your scope
comparison with parse.com API
cParseCom
VBA APIcScriptDBCom
VBA API
cParseCom
GAS API
parse.com cloud based noSQL
database
VBA and GAS Main Apps are virtually the same code irrespective of the
database
GAS scriptDB
cloud based noSQL
database
GAS scriptDB
webApp and API
library
parse.com restAPI handler
optimization and batching
• The gas library api will batch all requests it can.
• You should also batch requests from VBA API. It will
automatically handle batching limits.
• It’s easy. Just enclose various operations with .batch()with getScriptDb("someSilo")
.batch(True)
.someoperations(...)
.someotheroperations(...)
.batch(false) better
when
batched
example - create an object
Data is stored in silos within one or more ScriptDb
code
getScriptDb("somesilo") _
.createObject(JSONParse("{'customerid':1}"))
response (.jObject.stringify)
{
"status":"good",
"results":[]
}
better
when
batched
example - do a query
Queries are by example, and can include limit/skip
code
getScriptDb("somesilo") _
.getObjectsByQuery(JSONParse("{'customerid':1}"), JSONParse("{'limit':10}"))
response (.jObject.stringify)
{"status":"good","count":1,"results":[ {
"siloId":"somesilo",
"customerid":1,
"objectId":"S320799307189"
} ]
}
example - update objects
All matching objects are updated to the given value. New
fields are created, existing fields are replaced
code
getScriptDb("somesilo") _
.updateObjects(JSONParse("{'customerid':1}"), JSONParse("{'name':'john'}"))
response (.jObject.stringify)
{ "status":"good","results":[]}
better
when
batched
example - count matching objects
Count operations can have optional queries
code
getScriptDb("somesilo") _
.count(JSONParse("{'customerid':1}")))
response
1
example - get object by id
Each object is assigned a unique Id returned by queries
code
getScriptDb("someSilo")
.getObjectById ("S320802188977")
response (.jObject.stringify)
{"status":"good","count":1,"results":[ {
"siloId":"somesilo",
"customerid":1,
"name":"john"
} ]
}
example - delete objects
All objects matching the query are deleted
code
getScriptDb("somesilo").deleteObjects(JSONParse("{'customerid':1}"))
response (.jObject.stringify)
{"status":"good","count":0,"results":[ ]}
better
when
batched
example - load a spreadsheet to
scriptDb
Example add-on for this is included in workbook
code
populateFromSheet "VBAParseData"
Reading sheet and creating scriptDB objects
With dset.populateData(wholeSheet(sheetName), , , , , , True).jObject(, True, True)
For Each job In .children
Debug.Assert scriptdbCom.createObject(job).isOk
Next job
.tearDown
End With
better
when
batched
limits and skipping
Queries are subject to limits, so you need to work multiple
passes for big queries using skip/limitDo
With sdb.getObjectsByQuery(Nothing, jobskip).jObject.child("results")
If .children.count = 0 Or Not sdb.isOk Then Exit Do
jobskip.child("skip").value = jobskip.child("skip").value + .children.count
For Each job In .children
jobStore.add , job.toString("objectId")
Next job
End With
Loop
{"results":["S320923864193","S320923308803", …. ]}
this is
automatically
handled for update
and delete
dates and times
These are handled the same was as
parse.com"date":{
"__type":"Date",
"iso":"2013-08-22T00:00:00.000Z"
}
with supplied conversion function used like this
Debug.Print "date converted", getAnIsoDate(jor.child("date"))
silos and parse classes
• A Silo is like a parse Class. For 2D data it
can be considered like a table.
• Multiple classes can be held in the same
scriptDB.
• scriptDB siloing is handled automatically
• A seperate cScriptDbCom instance should
be instatiated for each class being worked
on
multiple scriptDB
• The scriptDB dispatcher handled which actual scriptDB
to write to.
• Multiple DBs can be used by referencing multiple
libraries in the scriptDB dispatcher.
• Library names will be signalled to the dispatcher if they
are in the setup for this entryscriptdbCom.init("anything", "some entry name", , "your app id", "your restapikey", , _
"some library",, "your web app Url")
restricting operations
You may want to allow a different kind of access to certain
users.
• provide a different URL or use the app keys to signal
some restricted access , and include something like this
in the doGet() and doPost() functionsvar whatsAllowed = ['query','count','getbyid'];
• setting that configuration up under a different entryscriptdbCom.init("anything", "some restricted entry", , "your app id", "your restapikey", , _
, "your restricted web app Url")
performance versus parse.com
• Performance of parse.com as a rest API
handler seems to be much better than
scriptDB for most operations.
• A full analysis will be published on Excel
Liberation and associated blog at some
future date
accessing from other apps
• The scriptDB GAS handler API can be
accessed using any rest query mechanism.
• The VBA API just manages the conversation
with the scriptDB GAS handler
• Examples of other languages will be on
Excel Liberation at a later date.
public facing scriptdb
• Normally access is controlled by oAuth2 - especially if
you are allowing write access.
• oAuth2 is very much invisible in this API, as described
in this writeup, but you still need to get google
credentials
• You can dispense with oAuth2 altogether for public
facing scriptdb by signalling false in the entry setupscriptdbCom.init("anything", "readonly", , "your app id", "your restapikey", , "some library", False, _
"https://script.google.com/macros/s/AKfycbx7_gPpc38Map4QqHOQrzx_kvIX00nfYGO9OLq8_cMD486Va6M/exec")
further detail
All this code is downloadable or copyable from
Google Apps Script Libraries.
For more information see Excel Liberation