Trick and Tips

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.

Posted by Unknown at 1:15 AM

Email ThisBlogThis!Share to XShare to FacebookShare to Pinterest

Labels: acl, api, batching, best, documents, entries, list, practices