Wednesday, March 11, 2015
Documents List API Best Practices Batching ACL entries
ACL (Access Control List) entries control who can access Google Docs resources. This allows more specific control over resource privacy or permissions.
Many types of applications need to grant document access for several users at once. As an example: when a new user is added to a project in the Manymoon project management application, every user on the project needs to be granted access to all attached Google docs. If there are 10 users on the project and 10 shared documents, this means the app would typically need to perform 100 HTTP requests -- a lot of overhead. With batching of ACL requests, the application can reduce the number of requests to one per document, resulting in a 10x savings.
Before Batching
A typical ACL entry for a single user is created by making an HTTP POST to the ACL link provided with each resource entry. The POST body looks something like this:
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gAcl=http://schemas.google.com/acl/2007>
<category scheme=http://schemas.google.com/g/2005#kind
term=http://schemas.google.com/acl/2007#accessRule/>
<gAcl:role value=writer/>
<gAcl:scope type=user value=new_writer@example.com/>
</entry>
To achieve the same thing using the Python client library, use the following code:
from gdata.acl.data import AclScope, AclRole
from gdata.docs.data import AclEntry
acl = AclEntry(
scope = AclScope(value=user@example.com, type=user),
role = AclRole(value=writer)
)
With Batching
Instead of submitting the requests separately, multiple ACL operations for a resource can be combined into a single batch request. This is done by POSTing a feed of ACL entries. Each ACL entry in the feed must have a special batch:operation element, describing the type of operation to perform on the ACL entry. Valid operations are query, insert, update, and delete.
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:gAcl=http://schemas.google.com/acl/2007
xmlns:batch=http://schemas.google.com/gdata/batch>
<category scheme=http://schemas.google.com/g/2005#kind
term=http://schemas.google.com/acl/2007#accessRule/>
<entry>
<category scheme=http://schemas.google.com/g/2005#kind
term=http://schemas.google.com/acl/2007#accessRule/>
<gAcl:role value=reader/>
<gAcl:scope type=domain value=example.com/>
<batch:operation type=insert/>
</entry>
<entry>
<category scheme=http://schemas.google.com/g/2005#kind
term=http://schemas.google.com/acl/2007#accessRule/>
<id>https://docs.google.com/feeds/default/private/full/document%3Adocument_id/acl/user%3Aold_writer%40example.com</id>
<gAcl:role value=writer/>
<gAcl:scope type=user value=new_writer@example.com/>
<batch:operation type=update/>
</entry>
</feed>
The following code represents the same operation in the Python client library:
from gdata.data import BatchOperation
from gdata.acl.data import AclScope, AclRole
from gdata.docs.data import AclEntry
acl1 = AclEntry(
scope=AclScope(value=example.com, type=domain),
role=AclRole(value=reader),
batch_operation=BatchOperation(type=insert)
)
acl2 = client.get_acl_entry_by_self_link(
(https://docs.google.com/feeds/default/private/full/
document%3Adocument_id/acl/user%3Aold_writer%40example.com))
acl2.scope = AclScope(value=new_writer@example.com, type=user)
acl2.role = AclRole(value=writer)
acl2.batch_operation = BatchOperation(type=update)
entries = [acl1, acl2]
The feed of these entries can now be submitted together to apply to a resource:
results = client.batch_process_acl_entries(resource, entries)
The return value is an AclFeed, with a list of AclEntry elements for each operation, the status of which can be checked individually:
for result in results.entry:
print entry.title.text, entry.batch_status.code
The examples shown here are using the raw protocol or the Python client library. The Java client library also supports batch operations on ACL entries.
For more information on how to use batch operations when managing ACLs, see the Google Documents List API documentation, and the Google Data APIs batch protocol reference guide. You can also find assistance in the Google Documents List API forum.
 | Ali Afshar profile | twitter Ali is a Developer Programs engineer at Google, working on Google Docs and the Shopping APIs which help shopping-based applications upload and search shopping content. As an eternal open source advocate, he contributes to a number of open source applications, and is the author of the PIDA Python IDE. Once an intensive care physician, he has a special interest in all aspects of technology for healthcare. |
Tuesday, March 10, 2015
Retiring the Google Documents List API v3
With the arrival of the new Google Drive API v2, we are deprecating the Google Documents List API v3. We are confident that the Google Drive API covers all the functionality of the Documents List API, in addition to adding many improvements, including Drive UI Integration, a finer grained security model, and a better client library experience.
What does this mean for your app?
The Documents List API v3 will remain in action for more than a year, as per our deprecation policy, so there’s no rush, but we encourage you to migrate your code to the new platform. Documentation is available with samples in multiple languages and a migration guide outlining some of the major transition points.
If you have any questions or issues, please ask them on StackOverflow.com, where our team is waiting to hear from you.
| Ali Afshar profile | twitter Tech Lead, Google Drive Developer Relations. As an eternal open source advocate, he contributes to a number of open source applications, and is the author of the PIDA Python IDE. Once an intensive care physician, he has a special interest in all aspects of technology for healthcare |
Monday, March 9, 2015
Deprecating Tables and Records feeds of the Spreadsheets API
After more than two years in service, we have made the decision to deprecate the Table and Record feeds of the Google Spreadsheets API. Having thoroughly tested these feeds and received lots of your feedback, we feel that the functionality provided by these feeds is something much better satisfied by the List and Cell feeds in the API.
Our deprecation plan for these APIs will keep these feeds in service for an additional year from today’s date.
If you are a current user of the Table and Record feeds, we highly recommend that you take the time to migrate over to the List and Cell feeds. Since the List feed works very similarly to the Records feed, this should be a smooth process.
As always, if you have any questions, feel free to use the Spreadsheets API forum.
Want to weigh in on this topic? Discuss on Buzz
Expensify Accelerates Sign ups with the Provisioning API
Expensify does expense reports that dont suck by importing expenses and receipts from your credit cards and mobile phones, submitting expense reports through email, and reimbursing online with QuickBooks and direct deposit.
The Foundation: Single Sign-On
We were really excited when Google approached us to be a launch partner for their new Google Apps Marketplace because tons of our customers use Google Apps -- including us! We have long wanted to put an Expenses link up there next to Mail and Documents, and now we had our chance.
To do that, we installed the JanRain PHP OpenID library with the Google Apps Discovery extension. We’d already implemented Gmail OpenID and ironed out the kinks related to having multiple logins to a single account, so implementing this was a very straightforward process.
Lessons Learned
We quickly learned that while single sign-on is awesome, there was a high drop-off rate among admins installing Expensify into their domain. Digging deeper we determined it was due to the setup process being split: part of the setup was done from within Google Apps, but the final part had to be completed by signing in to our site. Not only that, a major part of the setup process was laboriously entering their employee’s emails. We decided to address each in turn by creating a setup wizard and importing the domain’s email list. We approached this change in two major ways:First, when the Google Apps admin installs the Expensify application, we created a custom configuration step that creates what we call an expense policy. This governs everything from who is part of the company, who can approve expenses, and ultimately who exports to QuickBooks to keep the general ledger in check. Previously this step had to be done after the application was already installed, usually when the admin first signed in. By making this step part of the install process, the entire setup felt much more intuitive and resulted in a higher completion rate.
Second, we used the Zend framework to connect to the Google Apps Provisioning API to fill the new expense policy with a list of all existing employees. This saved a ton of typing and resulted in a vast reduction in the time it took to deploy Expensify to the full company. With everything else in place, the code we used to do this looked something like this:
$oauthOptions = array(All of the users’ names and emails are presented in a table of employees that the person installing the app can use to set roles and quickly build an approval tree for all expenses.
requestScheme => Zend_Oauth::REQUEST_SCHEME_HEADER,
version => 1.0,
signatureMethod => HMAC-SHA1,
consumerKey => $CONSUMER_KEY,
consumerSecret => $CONSUMER_SECRET
);
$consumer = new Zend_Oauth_Consumer($oauthOptions);
$token = new Zend_Oauth_Token_Access();
$httpClient = $token->getHttpClient($oauthOptions);
$service = new Zend_Gdata_Gapps($httpClient, $domain );
$users = $service->retrieveAllUsers();
Once the setup is completed, we automatically create accounts for all of the selected employees and send out a brief email with tips to get started.
Results: 3.5x more users sign up
Overall it was a fast and painless process, has increased the flow of high-quality leads, and has accelerated their rate of converting into real users. Domain admins now sign up 3.5x more users right away than they have been using the previous two-part setup! Feel free to install our app to see how the setup process works, and respond to this post with questions about your implementation -- well try to help out as best we can. And of course if youre still doing your expense reports the old sucky way, please come visit our website (Expensify.com) and wed be happy to help ease your pain. Thanks for reading, let me know if theres anything I can help clarify!Want to weigh in on this topic? Discuss on Buzz