|
PowerGDocs Web Services GuideThe Web Services are part of PowerGDocs and allow other users to access and share Google documents available under currently logged in user Google account. The web services can be started and stopped in PowerGDocs using the Services tab. The person (administrator) who configures and starts the web service host, must be logged in Google Docs™. The service host remains active as long as the administrator remains logged in and PowerGDocs is running. A web page PGDocsService.html opens in the default web browser when the service starts and can be used to access and show the available service options. Other users with network access to the service host can share the same page. The PowerGDocs service is designed for use in an intranet environment and allows network users to gain access to their Google documents via the PowerGDocs API described in the section below. Multiple PowerGDocs services are supported on the same or different hosts, using different Google Docs™ accounts.
Web Services Authorization and SecurityThe PowerGDocs Web Services are available only to users who obtain from administrator the full URL of the service host. A service key is also provided by the administrator to users of the service in order to request their own authorization tokens required for the service. The service administrator has full control of the URL that hosts the service, the key and the token expiration time period. The token expiration values are summarized below:
Note that firewalls on the system hosting the PowerGDocs service should be configured to allow network users to reach it through administrator designated ports. Internet access to the service can be configured over an SSL connection using authorized URL redirects to the PowerGDocs service host. An option to log web services transactions keeps details of the services requests in a file webservices.log PowerGDocs Web Services APIThis section provides information for users who plan to access the PowerGDocs web service using a program interface of their choice. The web services are exposed and accessed with RESTful style interactions, supported via HTTP POST methods. The PowerGDocs web service currently handles six API requests: newtoken, download, upload, update, lookup and search. These service requests appear as part of the URI and are described below. All other information associated with each request is sent as part of the POST, in the body of the request message as content-type: application/x-www-form-urlencoded. Response from the web services is in XML format. Service TokensTo access the services API users must first obtain a valid token, using a key given by the person (administrator) who configured and started the web service. The token is required in all other service requests. The expiration of the token is set at the start of the service as noted above. A newtoken can be requested in HTML as:
<form id='myForm' method='post' action='http://10.8.99.20:8562/newtoken'>
<input type='hidden' name='key' value='LetMeIn123'>
<input type="submit" value="Request Token" />
</form>
The service responds in XML as:
<PowerGDocs request='newtoken'>
<status>OK</status>
<token>78ah80e120f</token>
</PowerGDocs>
The status will show an error when the key is invalid.
An equivalent newtoken request in PowerShell is:
$url = "http://10.8.99.20:8562/gDocs/newtoken"
$parameters = "key=78ah80e120f" # your key value
$http_request = New-Object -ComObject Msxml2.XMLHTTP
$http_request.open('POST', $url, $false)
$http_request.setRequestHeader("Content-type", "application/x-www-form-urlencoded")
$http_request.setRequestHeader("Content-length", $parameters.length)
$http_request.setRequestHeader("Connection", "close")
$http_request.send($parameters)
# output status & token
$http_request.statusText
$http_request.responseText
$xmldata=[xml] $http_request.responseText
$xmldata.PowerGDocs.GetAttribute("time")
if ($xmldata.PowerGDocs.status -eq 'OK') {
$xmldata.PowerGDocs.token
}
Service RequestsAn unexpired token is required as a parameter for the service requests below. The other two required service parameters are name and file, or text for lookup and search requests. The parameter values must be URL encoded. Note that the name parameter values refer to Google document names in download requests, but they refer to Google folder names in upload requests. The values for the name parameters can be the titles/names of Google documents and folders, or their corresponding resource ID's, in cases when the names are not unique. Examples of unique resource IDs, accepted as name values are: document%3A1FoWEjm_0S96XD9ObuPZX5gflMbOVG04Nq9A_xk2SWCo file%3A0B0RLuPmeBkOmZjZlNGUjdiYjd3N2MtOTBhOS00YjgzLWI0YjQtYhZWU5ZDVh folder%3A0B0RLuPmeBkOmNWU3MmMxOWEzNDQ4ZTEtN2I4NS00NmM1LWIyNTQtZmM3ZTQ1 The %3A sequence above is the URL encoded value of a colon [:]. Here is an example of a download request, specified in HTML:
<form method='post' action='http://10.8.99.20:8562/gDocs/download'>
<input type='hidden' name='token' value='78ah80e120f'>
<input type='hidden' name='name' value='mytest.html'>
<input type='hidden' name='file' value='C:\docs\myNewTest.html'>
<input type="submit" value="Download Request" />
</form>
The same download request in C# is:
using System.Net;
...
string token ="78ah80e120f";
string name ="mytest.html";
string file="C:%5Cdocs%5Cmytest.html"; //Note that file is url encoded
string postData ="token="+token + "&name=" + name + "&file="+file);
string url = "http://10.8.99.20:8562/gDocs/download";
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = postData.Length;
using(Stream writeStream = request.GetRequestStream())
{
UTF8Encoding encoding = new UTF8Encoding();
byte[] bytes = encoding.GetBytes(postData);
writeStream.Write(bytes, 0, bytes.Length);
}
HttpWebResponse response = (HttpWebResponse)request.GetResponse();
//Retrieve the response
using (StreamReader reader = new StreamReader(response.GetResponseStream())
{
Console.WriteLine(reader.ReadToEnd());
}
Similarly an upload request in HTML looks as follows:
<form method='post' action='http://10.8.99.20:8562/gDocs/upload'>
<input type='hidden' name='token' value='78ah80e120f'>
<input type='hidden' name='name' value='TestFolder'>
<input type='hidden' name='file' value='C:\docs\newlook.jpg'>
<input type="submit" value="Upload Request" />
</form>
An update request differs from the upload above only in the action='http://10.8.99.20:8562/gDocs/update'.All upload and update requests are executed asynchronously. To determine if any prior uploading requests have completed users can submit a lookup request. The lookup request shows additional details of the document and its folder.
<form method='post' action='http://10.8.99.20:8562/gDocs/lookup'>
<input type='hidden' name='token' value='78ah80e120f'>
<input type='hidden' name='name' value='newlook.jpg'>
<input type="submit" value="Lookup Request" />
</form>
The lookup response shows the update time and includes additional file and folder information.
<PowerGDocs request='lookup'>
<status>OK</status>
<doc title='newlook.jpg' id='document:6XD9Ob1FoWEjm_0S9uPZX5gflMbNq9Axk2SWC_oOVG04'
updated='10/26/2011 10:37 AM' folder='TestFolder'
fid='folder:mNWU3MmMxOWEzNDQ4ZTEtN2I4N0B0RLuPmeBkOS00NmM1LNTQtZmM3ZTQ1WIy'
/doc>
</PowerGDocs>
Note that a response can have multiple <doc> entries.
Partial names and unique resource IDs can also be used as name values in lookup requests.
The root folder is indicated by '*' and its id as fid=''.
A search request shows the same details as a lookup, however the results are based on full text search of documents in a specific folder or in all folders. Here is a sample search request for documents or files in all folders that contain data sheet.
<form method='post' action='http://10.8.99.20:8562/gDocs/search'>
<input type='hidden' name='token' value='78ah80e120f'>
<input type='hidden' name='name' value='*'>
<input type='hidden' name='text' value='data sheet'>
<input type="submit" value="Search Request" />
</form>
|