Overview

azureQuery provides a chaining (fluent) JavaScript API for getting at Windows Azure. The initial implementation targets Windows Azure storage, with blob storage operations currently implemented. Inspired to a large degere by jQuery, azureQuery can perform operations on whole sets of things such as "all containers" or "all blobs in a container.

The latest version of azureQuery is 0.1 and contains: blob storage support.

Some Examples

var containerList = aq.storage().containers().containerCollection; get a list of all containers in the storage account
var blobList = aq.storage().container('test').blobs().blobCollection; get a list of all blobs in a container
aq.storage().container('test').blobs().each(function (blob) { ... }); perform operations on each blob in a container
aq.storage().container('docs').blob('hello.txt').text("hello!") create a blob with some text in it
aq.storage().container('docs').blob('contacts.json').json(contacts); create a blob with the JSON of a JavaScript object
var contacts = aq.storage().container('docs').blob('contacts.json').json(); retrieve an object from a blob that contains JSON
aq.storage().containers().blobs().remove(); delete all blobs in all containers

5 Reasons to Like azureQuery

  • Brings client-side JavaScript into the fold of developer environments with an API for accessing WIndows Azure.
  • Allows client-side logic for cloud interaction, reflecting today's trend where more of a web application logic is in the client rather than on the server compared to the past.
  • Fluent API allows you to use chaining and jQuery-like approaches in your JavaScript cloud code.
  • Can perform operations on whole sets of things that match selectors (such as 'all containers' or 'all blobs ending in .xml').
  • JSON support allows you to effortlessly store and retrieve JSON objects in Windows Azure storage.

Stop! Read This!

5 Reasons to be Cautious in Your Use of azureQuery

  • Power. You can delete all your cloud data in a single statement, so be careful (actually, we have deletes off by default to protect you -- you have to explicitly enable deletes. But still, be careful).
  • Incomplete. We're just getting started on azureQuery - so the functionality you need may not be here yet. Our first two areas are blob storage (available now) and table storage (coming soon), but we're not stopping with storage.
  • New. That's right, this is brand new. And though we do use an extensive suite of unit tests, you nevertheless might be the first to really exercise an area of code; so you'd better be careful with it. Don't let a bug delete your storage. We implore you to carefully test things with data you can afford to lose first.
  • Unsecure. We're still working out the security model for azureQuery. That means if you adopt it now, you'll have to add in your security handling.

Set-up

To use azureQuery you need the client-side azureQuery.js library. You also need server-side code, which we've provided for VS2012 ASP.NET Web API.

Quick Start

1. Ensure you have: VS2012, Windows Azure SDK.
2. Download azureQuery to a local folder on your machine.
3. Ensure the local Windows Azure Storage Emulator is running.
4. Open the sample solution in /samples or the reference solution in /src.
5. Build and Run (F5). By default the supplied projects are configured to use your local Windows Azure Storage Emulator storage. Interact with dashboard or run the unit tests. Confirm operations using your preferred storage explorer.
6. To access actual Windows Azure storage instead of local emulator storage, modify the connection strings section of the solution's Web.config file.

The Client

Include azureQuery.js in your web client markup and then use it in your JavaScript code.

  <script src="~/Scripts/azureQuery.js"></script>
A base aq object is the starting point for your operations. For example, the code below creates a blob in a container with some XML:

aq.storage().container('orders').blob('order-0001').text('<order id="0001">...</order>');

The Server

On the server side of things, you need Web API set up with controllers (currently there is only one, BlobController) that inherit from the azureQueryLib.dll library.

MVC Web API Project

You can set up your server-side solution either of two ways:

1. Use Our Server Project.

You can use our source project (in the /src folder) as your starting point, a VS2012 MVC4 / Web API project. Add in your additional functionality. This is the easiest way to get familiar with azureQuery. Just be sure to update Web.config with your storage account credentials.

2. Add our controllers and library to your existing MVC4 project.

You can amend your existing MVC4/Web API project to use azureQuery. To do so, reference our azureQueryLib.dll library and set up controllers to reference the library. See our sample project (in the /samples folder) for an example of how to do this. Here's how you define a blob controller (BlobController.cs):

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using azureQuery;

namespace VS2012.Controllers
{
    public class BlobController : AzureQueryBlobController
    {
    }
}
Ideally, we'd prefer to avoid the server side altogether and have azuerQuery interact directly with the Windows Azure data center APIs; alas, Ajax cross-domain restrictions require your communication to route through your web server.

Server Configuration

The association of the storage account name with Windows Azure storage account credentials is handled on the server side via web.config settings.

It is recommended the default storage name be associated with Windows Azure Dev Storage for local testing.

web.config
  <connectionStrings>
    <add name="default" connectionString="UseDevelopmentStorage=true" />
    <add name="commerce" connectionString="DefaultEndpointsProtocol=http;AccountName=contosocommerce;AccountKey=9yhX...71FhuV94Ykmpg=="/>
    <add name="content" connectionString="DefaultEndpointsProtocol=http;AccountName=contosocontent;AccountKey=redfxN...XSb5A==" />
  </connectionStrings>

The Core AQ object

aq is the object from whom all azureQuery statement chains begin. You can use the aq object two ways: to invoke feature area library functions, and to set options. The two statements below set a storage option, and then perform a storage operaton.

aq.storageOptions.allowDeletes = true;
aq.storage().container('orders').remove();

Libraries

Currently, there is only one feature area, named storage(). It supports blob storage, with table storage planned next on the roadmap.

Library Description Example
Storage Blob storage operations aq.storage("orders").blob('order-1001").text(orderXml);

Storage Library

The storage library is specified with aq.storage() or aq.storage(storageAccouontName).

var containerList = aq.storage("commerce").containers().containerCollection;
Leaving out storageAccountName defaults to the name "default".

var containerList = aq.storage().containers().containerCollection;

Storage Library Examples

var containerList = aq.storage().containers().containerCollection; get a list of all containers in the storage account
var blobList = aq.storage().container('test').blobs().blobCollection; get a list of all blobs in a container
aq.storage().container('test').blobs().each(function (blob) { ... }); perform operations on each blob in a container
aq.storage().container('docs').blob('hello.txt').text("hello!") create a blob with some text in it
aq.storage().container('docs').blob('contacts.json').json(contacts); create a blob with the JSON of a JavaScript object
var contacts = aq.storage().container('docs').blob('contacts.json').json(); retrieve an object from a blob that contains JSON
aq.storage().containers().blobs().delete; delete all blobs in all containers

Storage Library Functions

storage(accountName) selects the storage library for the specified storage account (default: "default")
.containers(...) selects containers matching the list of container(s) which may include wildcards.
.container(name) selects a single container
.blobs(...) selects blobs matching the list of blob(s) which may include wildcards.
.blob(name) selects a single blob
.each iterates through selected containers or blobs
.create creates containers or blobs
.copy copies selected containers or blobs
.remove removes selected containers or blobs

.containers(...)

containers(...) selects a list of containers matching the parameter(s). You always use containers() after aq.storage().

You can specify no parameters (all containers), a single container name, or a list of container names. A container name may contain a wildcard specification. An asterisk may be used to indicate all containers ('*'), starts-with ('order*'), or ends-with ('*files'). containers() is the same as containers('*').

aq.storage().containers('2012', '2011', '2010').create();    // Create three containers.
The return value of containers(...) is this (the aq object), from which you can chain additional operations, including the .blobs and .blob functions to access blobs within the selected containers. The aq object's selection type is set to containers. Operabtions you can perform on a selection of containers include create, copy, and remove.

After a selection is made, the aq's containerCollection property is set to an array of JavaScript objects describing the containers (use .name to get to the container name).

var containerList = aq.storage().containers('*').containerCollection;
You may also iterate through the selected containers using the .each_ function.

aq.storage().containers('*').each(function (container) {
    alert(container.name);
};
containers makes a round-trip to the server. To select a single container without making a round-trip to the server, use container(name) instead of containers(name).

.container(name)

container selects a single container by name. The container does not have to already exist. Wildcards are not permitted. From container(name) you can get to blob objects. All of the functions available to containers are also available to container, including create, copy, remove, each blobs, and blob.

var container = aq.storage().container('orders');

.blobs(...)

blobs(...) selects a list of blobs within the already-selected containers that match the parameter(s). You always use blobs() after containers() or container().

You can specify no parameters (all blobs), a single blob name, or a list of blob names. A blob name may contain a wildcard specification. An asterisk may be used to indicate all blobs ('*'), starts-with ('order.*'), or ends-with ('*.xml'). blobs() is the same as blobs('*').

aq.storage().container('temp').blobs().remove();    // Delete all blobs in the container.
The return value of blobs(...) is this (the aq object), from which you can chain additional operations. The aq object's selection type is set to blobs. Operations you can perform on a selection of blobs include create, copy, and remove.

After a selection is made, the aq's blobCollection property is set to an array of JavaScript objects describing the blobs (use .name to get to the blob name).

var blobList = aq.storage().container('orders').blobs().blobCollection;
You may also iterate through the selected blobs using the .each function.

aq.storage().containers('orders').blobs().each(function (blob) {
    alert(blob.name);
};
blobs makes a round-trip to the server. To select a single blob without making a round-trip to the server, use blob(name) instead of blobs(name).

.blob(name)

blob selects a single blob by name. The blob does not have to already exist. Wildcards are not permitted. From blob(name) you can store and retrieve blobs using the text, bytes, or json functions. All of the functions available to blobs are also available to blob, including create, copy, remove and, each.

var blob = aq.storage().container('orders').blob('test.txt');

Last edited Jul 30, 2012 at 5:53 PM by dpallmann, version 78

Comments

No comments yet.